Skip to main content

Getting started with Reports

Introduction​

This tutorial shows you how to create and use reports in the ODSL language and the REST API.

What is a report?​

A report configuration is a variable containing an expression that is used to generate a report.

When a report configuration is run, it produces a report. The generated report is a variable of any type.

Creating a report configuration​

We are going to create a report that summarises usage metrics by user to see much each user is using the system.

Creating the script​

First we need to create a script that performs the aggregation of the metrics for the report. Create an odsl file called report_functions.odsl and add the following code to it:

/**
 * @category report
 * Example functions for creating reports
 */

function userMetrics()
    userMetrics = aggregate ${metric}
        match user != null and timestamp >= #START and timestamp <= #END
        group _id="$user", value=sum(1)
    end
end

Upload this file to the server by right-clicking in the code and selecting Upload this script

upload-script

This creates the function userMetrics which we will use in our expression.

Date Range

Note the use of the variables #START and #END in the aggregation - these are the range of dates that are passed into the report build

Create the report​

//#region Create a report
USER_METRICS = Report()
USER_METRICS.category = "Tutorial"
USER_METRICS.name = "User Metrics Summary"
USER_METRICS.description = "Summarise the usage metrics by user"
USER_METRICS.script = "report_functions"
USER_METRICS.expression = "userMetrics()"
USER_METRICS.tags = ["tutorial", "example"]

save USER_METRICS
//#endregion

Test the report​

We can test the report by executing the build method on the report configuration or getting the report

//#region Get and run the report
config = ${reportconfig:"USER_METRICS"}
report = config.build()
print report.data
//#endregion

//#region Run the report directly
report = run report USER_METRICS
print report.data
//#endregion

//#region Run the report with a range
rep = run report USER_METRICS with "between(2023-01-01,2023-01-31)"
print rep.data
//#endregion

Saving reports​

You can run and save a version of a report which will remain fixed, i.e. the data generated by the report configuration is now static in the report.

Saving​

//#region Run and save the report
save ${report:"USER_METRICS"}
//#endregion

//#region Run and save the report with a range
save ${report:"USER_METRICS", "_range=between(2023-01-01,2023-01-31)"}
//#endregion

Getting the saved report​

You can get the saved report by using the version number of the report or ~LATEST for the latest version of a report

//#region Get the saved report
rep = ${report:"USER_METRICS"}
print rep.data
//#endregion

Versioning​

Both report configurations and reports are versioned - this means when they are saved, if there are changes made, the old version is saved in the archive and the new version becomes current with a new version number.

Versioning is covered in detail in Data Versioning, but below are some examples of how to use versioning with respect to reports and report configurations.

Report configurations​

You may want to tag a specific version of a report configuration as the production version whilst you work on a future version - that way users can still use the version you want them to use.

//#region Tag a version of a report
tag ${report:"USER_METRICS":1} as MAR23
//#endregion

//#region Get a tagged version of a report
rep = ${report:"USER_METRICS":MAR23}
print rep
//#endregion