Reports

Sentinel EMS REST API provides the following endpoints for viewing and generating reports:

Endpoint URL Description
Core Reports  

Search Reports

GET /ems/api/v5/reports

Retrieve a list of all the available reports, including predefined and custom reports. You can also retrieve a specific report based on its name. This endpoint returns report details, such as unique identifier, name, and parameter list.

Generate Report

GET /ems/api/v5/reports/{reportId}

Generate a report in the given output format.

Data Export Reports  

Search Data Export Reports

GET /ems/api/v5/reportTemplates

Retrieve a list of all the available data export reports. You can use the isConfigurable input parameter to filter the user-defined or predefined data export reports.

Get Data Export Report

GET/ems/api/v5/reportTemplates/{reportId}

Retrieve details of a specific data export report.

Generate Data Export Report

GET /ems/api/v5/reportTemplates/{reportId}/generateReport

Trigger a job for the given data export report.

The report job is asynchronous. It runs in the background and takes time to complete depending on the volume of the data to be exported and the number of jobs in the queue.

Copy Data Export Report

POST /ems/api/v5/reportTemplates/{reportId}/copy

Create a data export report by copying a predefined report.

Configure Data Export Report

POST /ems/api/v5/reportTemplates/{reportId}/configure

Configure the details of a user-defined data export report as identified by the reportId.

Delete Data Export Report

DELETE /ems/api/v5/reportTemplates/{reportId}

Delete a user-defined data export report.

Search Report Jobs

GET /ems/api/v5/reportJobs

Retrieve a list of all available report jobs.

Get Report Job

GET /ems/api/v5/reportJobs/{reportJobId}

Retrieve the details specific report job. You can set the getDownloadUrl parameter to true in the input to retrieve the signed URL for downloading the data export report in the response.

Reset Report Job

POST /ems/api/v5/reportJobs/{reportJobId}/reset

Restart a report job.

Delete Report Job

DELETE /ems/api/v5/reportJobs/{reportJobId}

Delete a report job.

Steps for Generating Core Reports

To generate a report:

1.Use the Search Reports endpoint to retrieve a list of all reports.

2.From the response, note down the name and mandatory parameters of the report that you want to generate.

3.Use the Generate Report endpoint to run the specific report, by using the report name and a list of mandatory parameters (copied in the step above). Note the following:

You need to provide all mandatory parameters of the report.

You can specify a report parameter value by using the = symbol.

Steps for Generating and Downloading Data Export Reports

To generate a data export report:

1.Use the Search Data Export Reports endpoint to retrieve a list of all reports.

2.From the response, note down the name or ID, parameters of the data export report, and allowed entity types for which the custom attributes can be exported (if supported).

3.Use the Search Custom Attributes endpoint to retrieve the list of available custom attributes of the allowed entity types and note down the ones to be exported.

NOTE   This step is not relevant for data export reports for SCL Add-on for RMS.

4.Use the Copy Data Export Report endpoint to create a copy of the predefined data export report. Add the custom attributes you want to export for the allowed entity types. You can copy only predefined (non-configurable) reports.

NOTE    

You cannot copy and configure the following:

> Custom Entities data export report because all attributes in the specified custom entity are included in this report by default.

>Data export reports for SCL Add-on for RMS.

5.(Optional) Use the Configure Data Export Report endpoint to modify a user-defied data export report. You can modify the display name and description of the report, and add or remove the custom attributes you want to export. You cannot configure predefined data export reports. The list of the custom attributes overwrites the previous ones.

NOTE    

You cannot copy and configure the following:

> The Custom Entities data export report because all attributes in the specified custom entity are included in this report by default.

>Data export reports for SCL Add-on for RMS.

6.Use the Generate Data Export Report endpoint to start exporting the data using a specific data export report. This triggers a report job where the status of the data export operation can be seen. The name of the created report job is the name of the data export report followed by the time stamp when the job is triggered. Note the following:

You need to provide all mandatory parameters of the data export report.

NOTE   For the Custom Entities data export report, it is mandatory to specify Custom entity ID in the request.

Use the = symbol to specify a parameter value and the & symbol to separate report parameters.

The link for the report job is available in the Location response header of the API call.

7.(Optional) Use the Search Report Jobs endpoint to retrieve the list of report jobs. You can filter the search based on the report job name.

8.Use the Get Report Job endpoint to retrieve a report job based on its identifier. A report job can be in following states: NOT_STARTED, IN_PROGRESS, COMPLETED, FAILED. If the state of a report job is COMPLETED, you can retrieve the URL for downloading the data export report by setting the getDownloadUrl parameter to true.

9.In case the report job fails, you can use the Reset Report Job endpoint to restart the failed report job, and then execute the Get Report Job endpoint again. Note that you can reset only the FAILED report jobs.

Best Practices on Generating Data Export Reports

Some notes on best practices to generate data export reports:

>If you have a large dataset, use relevant filters to reduce the time taken in report generation. Instead of creating one report with a massive amount of data, we recommend running multiple reports with segmented data.
For example, instead of a monthly report, consider generating weekly reports. Similarly, rather than generating reports for all customers, entitlements, products, or features, narrow it down to specific ones.

> It is recommended to schedule report generation during off-peak hours. Keep in mind that once a report is in progress, it cannot be canceled, so plan accordingly.