Email reports plugin comes with Countly Lite. This article will walk you through how it functions. The main highlights of the article are how to create reports and send them via email, and how you can develop your own email reports for other sections of Countly (e.g., via plugin).

Getting started

After you have logged in to your Countly account, you can access email reports from Management section in the main menu on the right side.

Create Email reports

It is quite easy to create an email report. On the email reports view, click the Create new report button which opens up a drawer that asks for the report details.

Injectable email reports

As mentioned earlier, email reports provide only core type email reports. But you can also add your own report types to the Email reports plugin via your own plugin or any other section of Countly.

Adding report type to email reports drawer

To add report type to the email reports drawer, append the relevant html to the appropriate block. Same goes for the settings that are specific to the report type only. Settings basically are the input fields, radio-boxes etc that are required by that report. Also, add the event handlers if required. Do not forget to trigger cly-report-widget-section-complete event from each event handler that you add.

app.addPageScript("/manage/reports", function(){
    var setting = '<div class="section">' +
                    '    <div class="label">Dropdown</div>' +
                    '    <div id="reports-dropdown" class="cly-select" style="width: 100%; box-sizing: border-box;">' +
                    '        <div class="select-inner">' +
                    '            <div class="text-container">' +
                    '                <div class="text">' +
                    '                    <div class="default-text">Select</div>' +
                    '                </div>' +
                    '            </div>' +
                    '            <div class="right combo"></div>' +
                    '        </div>' +
                    '        <div class="select-items square" style="width: 100%;"></div>' +
                    '    </div>' +
                    '</div>';

    var reportType = '<div data-report-type="your-report-type" class="opt cly-grid-3">' +
                        '      <div class="inner">' +
                        '          <span class="icon your-report-type"></span>' +
                        '          <span>Your report type</span>' +
                        '      </div>' +
                        '</div>';

    $("#reports-widget-drawer .details #report-types .opts").append(reportType);
    $("#reports-widget-drawer .details").append(setting);

    $("#reports-dropdown").on("cly-select-change", function() {
        $("#reports-widget-drawer").trigger("cly-report-widget-section-complete");
    });
});

Registering report options

After you have added the report type to the UI, the next step is to register the report options. Essentially there are 6 report options: ajax, init, settings, reset, set, tableData, each being a callback function called by the email reports plugin wrapped within the document.ready event. To add the report callback options use the following method - app.addReportsCallbacks("report-type", reportsOptions)

$(document).ready(function() {
    if(typeof app.addReportsCallbacks === "function"){
        app.addReportsCallbacks("report-type", reportOptions);
    }
});

Report options -

1. ajax Initializes email reports with report data by sending request to the server
2. init Initializes the email reports drawer with relevant settings for the report type
3. settings Returns an object with the setting values for the current report type
4. reset Resets the report setting values
5. set Sets the report settings values
6. tableData Returns data to be displayed in the reports table for each row

var reportsOptions = {
    ajax: function(){
        return $.when(countlyDashboards.someServerRequest()).done(function () {});
    },

    init: function(){
        $("#some-settings").show();
        $("#some-settings").hide();
    },

    settings: function(){
        var settings = {
            setting: $('#setting-section').clySelectGetSelection(),
            another_setting: $('#another-setting-section').clySelectGetSelection()
        };

        return settings;
    },

    reset: function(){
        $("#setting").clySelectSetSelection("", "");
    },

    set: function(reportData){
        $("#setting").clySelectSetSelection(id, value);
    },

    tableData: function(reportData){
        return "Some data to be displayed";
    }
};

Preparing report data: server-side

Now the final step that remains is to prepare the server-side data for the report. Email reports plugin dispatches an event /email/report which in turn returns the report data which is then sent out by the email reports plugin.

plugins.register("/email/report", function(ob){
    return new Promise((resolve, reject) => {
        var params = ob.params;
        var report = params.report;

        versionInfo.page = (!versionInfo.title) ? "http://count.ly" : null;
        versionInfo.title = versionInfo.title || "Countly";

        if(report.report_type == "report-type"){
            var template = "/templates/email.html";
            fs.readFile(dir + template, 'utf8', function (err, template) {
                var message = ejs.render(template);
                report.subject = "Email subject";
                report.data = {
                    "host": host, 
                    "report": report, 
                    "version": versionInfo, 
                    "message": message
                }

                resolve();
            });
        }else{
            resolve();
        }
    })
});

Every report type needs to register the email report event in order to send out the report as email. It is important for report type to set data property to report object with message, host, report, version as mandatory keys assigned to the key.

There are also two other event that are dispatched by the email reports plugin - 1. /report/authorize - To authorize the user (Used by all report options create, update, send etc) 2. /report/verify - To verify the email report (Used when fetching all the reports and displaying in the reports table)

plugins.register("/report/authorize", function(ob){
    return new Promise((resolve, reject) => {
        var report = ob.report;

        if(report.report_type == "report-type"){
            report.authorized = true;
            resolve();
        }else{
            resolve();
        }
    })
});

plugins.register("/report/verify", function(ob){
    return new Promise((resolve, reject) => {
        var report = ob.report;

        if(report.report_type == "report-type"){
            report.isValid = true;
            resolve();
        }else{
            resolve();
        }
    })
});

Both authorize and verify uses authorized and isValid keys to check the authenticity of the user and the validity of the report respectively.

Adding reports drawer to your plugin or any countly section

To add the email reports to any section first you need to add the add report button with id add-report which in turn will open the email reports drawer, but it needs to be initialised first using app.getReportsCallbacks()["reports"].initialize(element, report-type, callback) All this needs to be done on the view that will load the email reports drawer.

app.addPageScript("/some-view", function(){
    if(countlyGlobal["plugins"].indexOf("reports") < 0){
        return;
    }

    var addEmailButton = '<div id="add-report" class="item"><i class="fa fa-cog"></i><span>Create report</span></div>';

    $("#some-id-after-which-button-will-be-added").after(addEmailButton);

    var reportsCallbacks = app.getReportsCallbacks()["reports"];

    if(!reportsCallbacks) return;

    reportsCallbacks.initialize("#element", "report-type", callback);
});

The element refers to the DOM element after which the email drawer will be placed. The callback function will include your report settings and report type which will be added to the drawer just like mentioned earlier in previous sections. Rest all the things remain same as explained in above sections.