Use the API to retrieve reports

The Time Portal API can be used to retrieve any report using HTTP.  This can be useful when creating integrations with other applications such as Microsoft Power Automate (previously known as Microsoft Flow.)

 As illustrated, a POST request can be made to the "reports" API endpoint to receive a file content response.  The request must include an authorization header and the body must include a "report criteria" object as described below.

To request a specific report, append the name of the report to the API endpoint.  For example, the LocationSummary report can be retrieved with the following method:

https://mapi.timeportal.io/api/reports/locationSummary

Where to find the name of the report

The name of each report can be determined from the URL which is shown in the address field of the browser when on a report screen within the Time Portal web application.  When setting the criteria for the Location Summary report, for example, notice the URL ends with the name of the report,  locationSummary.

How to get the report criteria

The report criteria includes all the parameters which are entered on report screens such as the one illustrated above. This information is expressed in Javascript Object Notation (JSON) and resembles the following:

{

"dateRangeOption":{"id":0,"label":"Selected Dates"},
"startDate":"2020-05-11",
"endDate":"2020-06-28",
"crews":null,
"employees":null,
"jobs":null,
"locations":null,
"cropVarieties":null,
"growers":[{"id":123456","label":"Orchid Farms"}],
"statuses":[{"id":1,"label":"Uploaded"},{"id":4,"label":"Approved"},{"id":5,"label":"Complete"}],
"format":{"id":1,"label":"PDF"},
"companyId":123456

}

Notice the JSON includes an array for entering the ID of one or more growers as well as other information such as statuses and companyId.  Although it is possible to determine these values within the web application, it is much easier to simply run the report in Time Portal and grab a copy of the request payload from Google Chrome's Developer Tools.  

Use Google Chrome to navigate to the desired report page in Time Portal then press the F12 function key to display the developer tools. Select the Network Tab (it may be necessary click the right-chevron icon to find it.)  Enter your desired report parameters in Time Portal and run the report.  After doing so, find the request to the API endpoint and scroll to the bottom of the Headers view to show the Request Payload.  As shown below, the source (instead of parsed) view of the Request Payload is selected.

The Request Payload can be copied from Google Chrome Developer Tools and pasted into the Body field of the HTTP Request tool that is being used to perform the POST.  

Note.  The "dateRangeOption" parameter has not yet been implemented in the UI and will have to be manually added to the JSON object as outlined above. Valid values are:

Until the "dateRangeOption" parameter has been implemented, you may simply copy and paste the following into the Request Payload (just inside the opening bracket "{" and before "startDate").

"dateRangeOption":{"id":0,"label":"Selected Dates"},

After doing so, just change the value of "id" as appropriate based on the above table.

How to get the Authorization Header

Microsoft Power Automate and other HTTP client tools include options for specifying request headers including the Authorization Header.  Since Time Portal uses industry standard Auth Tokens, the Authorization Header is expected to contain a string similar to this:

Bearer xxxxxxxxxxxxxxxxxxx

where xxxxxxxxxxxxxx is a valid Auth Token issued by Time Portal in response to a successful login request.  The token is short lived and includes information that identifies you and your company. 

In a typical workflow, a request to the Login method will be used to to retrieve an Auth Token, then a second request (including the Auth Token within the Authorization Header) will be made to retrieve the report.  

Microsoft Power Automate and other HTTP client tools include options to authenticate with a user name and password.  The output of such requests will include the Auth Token.  The following information is required to authenticate with Time Portal: