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.
- Enable REST API
- Generate the REST API token
- Get an API token and REST authorization
- Get UserID using REST API
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.
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.
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:
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.
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.
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.
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.
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.
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.
The response contains details about the status of rendering as shown below.
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.