Report Rules

Report rules is a mechanism for writing custom reports using rules.

This is a powerful mechanism which allow the use of Clarive rule ops to generate data that can be gathered from many sources, not only the Clarive database.

To write a report rules, we need to take in consideration many reporting strategies, primarily:

• Authentication - your rule should take care of checking if the user is allowed or not to see the report.

• Paging - large amounts of data requires paging to be setup.

Report Metadata

As part of the report rule, need to declare metadata that defines the column types that being returned by the report.

The good news is that we can return different report metadata depending on input parameters, so reports can be highly dynamic depending on what we want to show.

The metadata structure needs to be returned with a function assigned to the stash key report_meta.

This is the typical metadata structure generated by a ClaJS Server CODE op that we need to include in our Report rule:

cla.stash( 'report_meta', function(){
    return {
       fields: {
           ids: [ 'id', 'title'],
           columns: [
                {id: 'id', text: 'Mid'},
                {id: 'title', text: 'Title'}
           ],
           report_name: 'MyReport',
           report_type: 'custom',
           hide_tree: true
       }
    }
});

Where a function() returns the report metadata structure that's going to be used to generate the report.

Report Data

The report data will be a result of calling a function assigned to the stash variable report_data.

The function will return a hash data structure with 2 fields: data (with an array of objects) and the cnt field, which is the total count of rows.

The following is an example of a Server CODE op entry in ClaJS for a direct topic collection query.

cla.stash( 'report_data', function( params ){
    var db = require('cla/db');

    var start = params.start || 0;
    var limit = params.limit || 25;

    // sorting
    var sort = {};
    var dir = params.dir;

    if( params.sort ) {
        sort[ params.sort ] = dir == 'ASC' ? 1 : -1;
    }
    else {
        sort['_seq'] = 1;
    }

    var where = {};
    var query = params.query;
    if( query ) {
        where['_txt'] = cla.regex(query);
    }

    var rs = db.getCollection('topic').find( where );
    rs.fields({ mid: 1, title: 1 });
    rs.sort( sort );
    rs.skip( start );
    rs.limit( limit );

    var cnt = rs.count();

    var doc;
    var rows = [];

    while( doc = rs.next() ) {
        rows.push({
            id: doc.mid,
            title: doc.title
        });
        print( doc.title );
    }

    return { data: rows, cnt: cnt }
});

Report Security

Report security needs to be implemented by the rule, otherwise the rule will not be visible to the user in the Report explorer.

Here's an example of a Server CODE palette op with ClaJS code that checks for a certain username and returns true/false (allow/block) access from the user to the report:

cla.stash( 'report_security', function( params ){
    if ( params.username == 'admin' ) {
        return true;
    }
    else {
        return false;
    }
});

CLARIVE 7.0 You can also check for user roles instead of user ids. The params object comes loaded with an array of the logged in user roles.

cla.stash( 'report_security', function( params ){
    if ( params.roles.indexOf('DEVELOPER') > -1 ) {  // assuming you have the DEVELOPER role in your system
        return true;
    }
    else {
        return false;
    }
});

Todo

In the Clarive 7.2 release there will be a more robust security checker as part of the rule palette.

Super Users

Super users (users that have the action.admin.root) have access to the report automatically. In other words, the system will not execute the report_security method when the user is a super user.