How to manage reports using REST API

You can use REST APIs to manage and automate your reporting. This article will cover the prerequisites for using REST with reporting, explain the REST resources, and give you some real use cases.

Prerequisites

You must have read the following articles and completed the set up within them in order to manage reporting via REST APIs.

REST reporting resources

Read ReportTemplates GET /applications/{applicationid:int}/reporttemplates
Read Reports GET /applications/{applicationid:int}/reports
Read Report GET /applications/{applicationid:int}/reports/{reportid:long}
Create Report POST /applications/{applicationid:int}/reports
Update Report PUT /applications/{applicationid:int}/reports/{reportid:long}
Delete Report  DELETE /applications/{applicationid:int}/reports/{reportid:long}
Read ReportFormats GET /applications/{applicationid:int}/reports/formats
Render Report POST /applications/{applicationid:int}/reports/{reportid:int}/renderings
Read RenderingStatus GET /applications/{applicationid:int}/reports/{reportid:int}/renderings/{renderingid:long}
Cancel Rendering DELETE /applications/{applicationid:int}/reports/{reportid:int}/renderings/{renderingid:long}

 

REST resources explained

ReportTemplates GET /applications/{applicationid:int}/reporttemplates

Report Templates (also referred to as Report Definitions) are the predefined reports in GpsGate. A list of all Report Templates is available here. You can use the ReportTemplates resource to check which report templates are available on your server. Similar to most other resources, each entity (report template in this case) has an identifier (reportTemplateId) which can be used to refer to a specific report template.
ReportTemplates_Response.PNG

Read Report GET /applications/{applicationid:int}/reports
Read Reports GET /applications/{applicationid:int}/reports/{reportid:long}

Read report and read reports resources are for getting a specific report or all reports respectively. The response contains all details of the report. Tables 1, 2 and 3 below provide a short explanation for each field.

GetReport_Response.PNG

Table 1: report fields

id report's ID
applicationId ID of the application that owns the report
definitionId reportTemplateID
name report's name
description report's description
showParameters a flag that indicates if the parameters are visible to users
reportFormatId default formatID of the report
parameters report parameters: to check the parameters of each report, you must log in to Site Admin and check the report template (see table 2)
schedule object used for scheduled reports (see table 3)

 

Table 2: parameters

parameterName parameter's name
value a property used only for periodical parameters (daily, weekly, monthly, or custom should be specified) and single value parameters (e.g. HarshTurnPoints, SeatBeltPoints); ignored if specified for other parameters
visible a flag that indicates if the parameter is visible
periodStart starting timestamp of a period parameter ("parameterName" = "Period"); used only for the period parameter and ignored if specified for other parameters
periodEnd ending timestamp of a period parameter ("parameterName" = "Period"); used only for the period parameter and ignored if specified for other parameters
arrayValues used only for array parameters (list of TagIDs, EventRuleIDs, etc.) and ignored if specified for other parameters
timeSpan used only for TimeStamp parameters and ignored if specified for other parameters

 

Table 3: schedule

transport either Email or FileSave
scheduleType schedule type; either DayOfMonth or WeeksAndDays
dayOfMonth only used if scheduleType is dayOfMonth
weekInMonth only used if scheduleType is WeeksAndDays
daysInWeek only used if scheduleType is WeeksAndDays
hours the hour that the schedule is triggered
minutes the minute that the schedule is triggered
seconds the second that the schedule is triggered
recipients UserIDs for whom the schedule is triggered
reportFormatId Gives the possibility to render the report in a different format than the report's default format when it's triggered by the scheduler. See the 'Report Formats' section of this article for more information.
ignoreSendingBlank ignores the result if there is no data in the report for the specified period

 

Create Report POST /applications/{applicationid:int}/reports

The model for creating a report is the same as the model that is used in Read Report & Read Reports resources. For more details, see the 'Read Report & Read Reports' section of this article.
When creating a report, the ID should be zero or it should be removed from the request. Here is an example that creates a report similar to the report in 'Read Report & Read Reports' example:

Screenshot_2021-05-28_at_13.17.51.pngCreateReport_Response.PNG

Update Report PUT /applications/{applicationid:int}/reports/{reportid:long}

Update report uses the same model as the get report(s) and create report operations. The following example shows how to update the report we created in the last example.
Note that you can't update ReportID, ApplicationID and DefinitionID.

UpdateReport_Request.PNGUpdateReport_Response.PNG

Delete Report DELETE /applications/{applicationid:int}/reports/{reportid:long}

The delete report API is for removing a report. It will delete the specified report and all its dependencies. In this example, we remove the report we created in the last example.

DeleteReport_Request.PNGDeleteReport_Response.PNG

Report Formats GET /applications/{applicationid:int}/reports/formats

A report can be rendered in different formats. Currently GpsGate supports "HTML", "PDF", "CSV" and "CSV ZIP" formats. Each format has an identifier (reportFormatId) in the system. When you render a report, you should specify the format by passing through the reportFormatId. This resource is to obtain all available reportFormatIds. In the following example, you can see there are four report formats available in this application. Note that these reportFormatIds are used later when we trigger rendering a report.

ReportFormats_Request.PNGReportFormats_Response.PNG

Render Report POST /applications/{applicationid:int}/reports/{reportid:int}/renderings

The render resource is for rendering a report. When rendering a report, new parameters can be specified which gives the possibility to render a report with different parameters than the default ones. It's also possible to email the result of rendering by specifying an email address in the model and setting "sendEmail" flag to "true" as specified in the following figure. In this example, the report will be sent to support@gpsgate.com when it's ready. Note that we can also request the rendering in a different format than the report's default format by setting "reportFormatId" to our desired format.

CreateRendering_Request.PNG

The response model of a rendering request is the same as the response from the get rendering resource. It contains an ID property that is used for checking the status of this rendering. See the 'Read rendering status' section of this article for more details.

CreateRendering_Response.PNG

Read  rendering status

GET /applications/{applicationid:int}/reports/{reportid:int}/renderings/{renderingid:long}

In the above example, the RenderID in the response was 1677 ("id": 1677). In this API, we use this id to check the status of our requested rendering.

GetRendering_Request.PNG

The response contains details about the status of rendering as shown below.

GetReport_Response.PNG

Table 4: definitions of each field of the response

reportID the report's ID
isReady a flag that indicates if the result of rendering is ready (it's true when data is processed and the file is rendered)
outputFile a link to the result file on your server (this is available when isReady flag is set)
percentage the percentage of work complete (90% of the work is assigned for data processing and the remaining 10% is for rendering)
currentStep the current executing step
steps the total number of steps
reportFormatId requested format id (for more details, see the 'Report Formats' section of this article)
parameters the set of parameters for which the rendering is triggered (see the 'Read Report & Read Reports' section for more details on the parameters model)
id rendering identifier; obtained from the response of the 'render report' request

 

 

Cancel rendering DELETE /applications/{applicationid:int}/reports/{reportid:int}/renderings/{renderingid:long}

Cancel rendering is for canceling an ongoing rendering request. Requests to this resource for finished renderings are ignored.

CancelRendering_Request.PNGCancelRendering_Response.PNG