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