Skip to content

Creating Reports in JS

Your plugins can have their own reports in them. These reports are visible under the Internal tab in the report area.

To create a report, head over to the CLARIVE_BASE/plugins/ directory or create one if it does not exist.

Then create a plugin directory for your plugin, let's call it myplugin.

 mkdir $CLARIVE_BASE/plugins/myplugin

 # and inside that directory we create an /init directory

 mkdir $CLARIVE_BASE/plugins/myplugin/init/personalReport.js

Now we create our personalReport.js file ($CLARIVE_BASE/plugins/myplugin/init/personalReport.js) with the following contents:

var reg = require('cla/reg');

reg.register('report.myplugin.personal', {
    name: _('My Personal Report'),
    metaHandler: function(config) {
        return {
            fields: {
                columns: [
                    { id: 'name', text: 'Name' },
                    { id: 'value', text: 'Value', width: 300 }
                ]
            },
            report_rows: 100
        };
    },
    securityHandler: function(username) {
        var permissions = cla.modelJSON('Permissions');
        var userRoles = permissions.userRoles(username).map(function(v) {
            return v.role;
        });
        // in this system, a role of name "CLIENT" exists
        return userRoles.indexOf('CLIENT') > -1 ? true : false;
    },
    dataHandler: function(config, params) {
        var rows = [{ name: 'aaa', value: 'bbb' }];
        return {
            rows: rows,
            total: rows.length
        };
    }
});

Now restart the Clarive web server so that it picks up the report.

With an administrator (root) user, head over to the Topic > Reports > Internal interface tab to see your report.

Initially only administrator users can see internal reports. To make them available to other users, use security_handler function while registering your report.

Report definition

When registering a report, first choose a registration key, such as report.[mypluginname].[myreportkey] using all lower case letters, no spaces or special characters.

The registration key must be unique in the system.

The name: field is the report name visible by users.

Within the report definition, there can be 3 critical methods:

  • metaHandler(config) - defines the column names and column types for the report.

  • securityHandler(username) - checks if a given user can see the report.

  • dataHandler(config) - generates the data rows that will be shown by the report.

metaHandler(config)

This function will be called once when the report is first run by the user. It must return the column metadata so that the Clarive UI knows what columns to render for the user.

The function must return the following data structure:

fields - an object that contains the columns array of columns.

Each column is an Object with the following structure:

  • id: the unique id of the column
  • text: the text shown in the column header
  • width (optional): the number of pixels the column will have
  • hidden (optional): true or false to show the column or hide it. The user may add a hidden column later to the report.
  • sortable (optional): true or false to allow the user to sort by this column.

report_rows - the number of rows per page for the report. This is used to build the pager below in the report table.

securityHandler(username)

This function is executed everytime the user opens the Report UI, to decide if the report should be in the list, available to the user to run, or not.

Implement here a security check logic to allow users to access the report.

Then return true (user can see the report) or false (user view/run permission denied)

dataHandler(config)

This function is executed once for every page of data requested.

The function should use the config data to determine which page is the current page the user is viewing.

The function must return an Object with the following keys:

rows - an array of Objects of each row in the report table. The structure of the row object must match the columns parameter sent by the metaHandler(), where each id in the columns array is a key in the row object.

total - the total number of rows in the data set. This is used by the report table UI to calculate the number of pages in the resulting data set.