Custom Reports and Data Export with Usage Intelligence

The Usage Intelligence Interactive Dashboard is a mine of information which provides runtime intelligence related to product usage, environment statistics, event tracking, licensing information as well as user engagement and churn reports.

However we understand that some customers might have custom reporting requirements as well as needs to export Business Intelligence data from Usage Intelligence to integrate with third party products or platforms. For this reason Revulytics has developed a fully-fledged Reporting Web API which is available to all premium customers.

The Reporting Web API gives you the flexibility to create your own custom reports according to your requirements and retrieve the data either in raw JSON format or as a readily formatted HTML chart or table. Such data can then be parsed and/or integrated directly into your own reporting platform, CRM, ERP solution etc.

In this blog post we will introduce you to the Usage Intelligence Reporting Web API, explain the basics of building reports and provide some example requests using JavaScript. By the end of the post you will learn how to:

  • Authenticate with the Server
  • Build Custom Reports
  • Get Formatted Data
  • Get Raw JSON Data

The Basics

The Reporting API handles data requests as JSON objects and can reply either with raw data as a JSON object or with a formatted chart or table wrapped in an HTML page.

There are two request methods which you can use to get data from the server:

  • HTTP POST – This is the preferred method since it is more suited for long data requests and should be used if you’re building a custom application which handles raw data. When using this method the JSON request object is sent as POST data.
  • HTTP GET – This method is ideal when requesting formatted data to be included in an HTML page. When using this method the JSON request object is appended to the URL as a parameter. The complete URL can be used as the source of an iframe or can be manually entered in the address bar of the browser. When submitting a GET request, the following URL parameters are accepted:
    • query – The JSON request object should be specified in this parameter. This value needs to be URL encoded.
    • resultFormat – Specify the type of response required. The accepted values are “raw”, “highcharts”, and “table”. If not specified it will default to “raw”.
    • hcType – Only required if resultFormat is set to “highcharts” and is used to specify the type of chart. The accepted values are “pie”, “bar”, “column”, and “line”.
    • uiHcTitle – Optional parameter when resultFormat is set to “highcharts” or “table” to specify a title for the chart / table.

All requests made to the Reporting API can be done both via a POST or GET request, with the exception of logging in which can only be done via a POST request.

More information on POST vs GET requests can be found in the Reporting API documentation.

Authenticating with the Server

The first step to be able to generate reports is to authenticate with the server. The Web API supports two methods of authentication, either via a POST request to https://api.revulytics.com/auth/login, which returns a session ID as part of the JSON response, or else via cookies if getting formatted data.

Logging In – Using a Session ID

This method is preferred if the API is accessed from a script or application which needs to authenticate without using a web browser. The user and session ID are managed by the application and they will need to be sent with every request to the API as part of the JSON data. To log in using this method the request JSON object must specify the user and password, which are the email address and password you use to log in to your Revulytics account, and useCookies set to false:

{
 "user": "user@mycompany.com",
 "password": "mypassword",
 "useCookies": true
 }

The JSON response will include the status which reflects whether authentication was successful or not, and if successful it will include the sessionId to be used in all further requests:

{
 "status": "OK",
 "sessionId": "VSB8E2BzSC2eZSJm4QmTpA"
 }

Logging In – JavaScript Example

In the following JavaScript example, we are making a POST request to log in and chose to manage the session ID within the script. The sessionId is retrieved from the JSON response and set as the value of a hidden field with ID “hSessionID“.

function login() {
 var request = new XMLHttpRequest();
 var url = "https://api.revulytics.com/auth/login";
 request.open("POST", url, true);
 request.setRequestHeader("Content-type", "application/json");
 reques.setRequestHeader("Accept", "application/json");
 request.onreadystatechange = function() {
 if (request.readyState == 4 && request.status == 200) {
 //Parse the response to a JSON object
 var json = JSON.parse(request.responseText);

//Set value of hidden input field to the session ID for future use
document.getElementById("hSessionID").value = json.sessionId;
}
}

var data = JSON.stringify(
{
"user":"user@mycompany.com",
"password":"mypassword",
"useCookies":false
});

request.send(data);
}

Logging In – Using Cookies

If the API is accessed via a web browser and the data is requested as a formatted chart or table, this method is the most convenient way to manage the authentication session. When using cookies, the login is done by the user when viewing the page in their web browser. The first time data is requested, the API will return the Revulytics login page and the requested chart or table will be displayed once you log in successfully. Once a cookie for api.revulytics.com which contains a valid session ID is created, subsequent requests for data will return the chart or table straight away.

Revulytics Usage Intelligence Login

Logging Out

Logging out is done via a GET or POST request to https://api.revulytics.com/auth/logout, and this invalidates the session that was created when you logged in. If cookies were used to log in, then no JSON data should be sent and the request will simply delete the cookie and invalidate the session from the server. Otherwise if the session was being managed by a script or application, JSON data should be sent with the request which includes the user and sessionId:

{
 "user": "user@mycompany.com",
 "sessionId": "VSB8E2BzSC2eZSJm4QmTpA"
 }

By default a GET request to log out returns a user friendly HTML message. However if a POST request was done the response will be a JSON object which includes the status, and if the request fails it will also include a reason.

{
 "status": "OK"
 }

Logging Out – JavaScript Example

In the following example, we are making a POST request to log out and specifying the user and sessionId, which we saved as the value of the hidden field with ID “hSessionID” when we logged in.

function logout() {
 var request = new XMLHttpRequest();
 var url = "https://api.revulytics.com/auth/logout";
 request.open("POST", url, true);
 request.setRequestHeader("Content-type", "application/json");
 request.setRequestHeader("Accept", "application/json");

var data = JSON.stringify(
{
"user":"user@mycompany.com",
"sessionId":document.getElementById("hSessionID").value
});

request.send(data);
}

More information about Authentication is available in the Reporting API documentation.

Building Custom Reports

Once you have generated a session ID you can start requesting report data. The Reporting API currently supports six types of requests for data:

  • Generic Reports – Get reporting data related to session runtimes, user profile info, user distribution and activity for each product version, edition, and language, geo location, operating system and platform info, etc. This data can be retrieved for new, active, and lost users with various filtering and segmentation options. These reports can be generated for a past date range where you specify the start/end date or else on the latest known data of tracked users based on the date last seen.
  • Event Tracking Management – Used to get a list of event names and categories that have been reported by your application and which of these are currently enabled for collection.
  • Event Tracking Reports – Get report data on event usage , including event usage counts in the form of a data table or timeline, and advanced event tracking reports with filtering and segmentation options.
  • Churn-Related Reports – Get user profile info related to lost users, including event usage and runtime statistics for the time they were still engaged with your product before they were declared lost.
  • License Key Registry Management – Used to query the license key registry, retrieve license key usage details, get a list of abused keys, add new keys to the registry or update license key properties for existing keys such as to sync data with your CRM or licensing server.
  • Metadata Queries – Used to get a list of available filtering and segmentation properties or a list of possible property values which have been reported by your application. If you’re providing filtering and segmentation in your application, you can use this to populate the list of filtering and segmentation options which the user can choose from.

In the next sections we will go through some examples to get formatted and raw data by doing a request for Generic Reports.

Getting Formatted Data

If you would like to display data from Usage Intelligence in an HTML page, then getting formatted data will make this easy for you to show such data in the form of a chart or table. Let’s take an example where we need to get a chart of our product version distribution for current data, formatted as a bar chart like the following:

Software Version Distribution Analytics

We can get this data by making a request for a Generic Report and in order to get a ready formatted chart, we must make a GET request.

Building the Request JSON

An explanation of each property that needs to be included in the request JSON can be found in the Reporting API documentation. The following is an example of the JSON object to get the Version Distribution report we need:

{
 "productId": 2376158762,
 "startDate": "2015-12-18",
 "clientStatus": ["active", "new", "lost"],
 "levels":
 {
 "level1":
 {
 "sort": "active",
 "segments":
 [{
 "limit": 10,
 "type": "regex",
 "split": true,
 "value": ".*"
 }],
 "property": "prodVersion",
 "sortDirection": "desc"
 }
 },
 "daysUntilDeclaredLost": 30,
 "dateReportedLost": "dateDeclaredLost",
 "globalFilters": {}
 }

Building the URL

The request will need to be made to https://api.revulytics.com/reporting/generic and the following parameters must be included in the URL:

  • query – Specify the request JSON object in this parameter
  • resultFormat – Use “highcharts” as the result format
  • hcType – In order to get a bar chart this value needs to be set to “bar”
  • uiHcTitle – Specify the title of the chart, in our example this is set to “Version Distribution”

Getting Formatted Data – JavaScript Example

In the following example, we are building the URL to get the formatted chart, and then setting the source of an iframe with ID “chart” to that URL.

function getFormattedData() {
 var json =
 {
 "productId": 2376158762,
 "startDate": "2015-12-18",
 "clientStatus": ["active", "new", "lost"],
 "levels":
 {
 "level1":
 {
 "sort": "active",
 "segments":
 [{
 "limit": 10,
 "type": "regex",
 "split": true,
 "value": ".*"
 }],
 "property": "prodVersion",
 "sortDirection": "desc"
 }
 },
 "daysUntilDeclaredLost": 30,
 "dateReportedLost": "dateDeclaredLost",
 "globalFilters": {}
 };

//Encode the JSON object
var encodedJson = encodeURIComponent(JSON.stringify(json));

//Build the URL
var url = "https://api.revulytics.com/reporting/generic/current";
url += "?query=" + encodedJson + "&resultFormat="highcharts"""";
url += ""&hcType=""bar""&uiHcTitle=Version Distribution"";

//Set the iframe source as the URL
document.getElementById(""chart"").src = url;
}

More URL examples can be seen in the Dashboard by clicking on a chart’s context menu and selecting the URL option. From the URL you will be able to see the JSON object that was requested to build that chart.

Getting Raw Data

If you are building a custom application then getting raw data as a JSON object will allow you to parse

Leave a Reply

Your email address will not be published. Required fields are marked *