Getting Started

Introduction and Assumptions

Reading this document assumes you are familiar with:

1. Common RESTful HTTP response codes.
2. JSON serialization.
3. Using the WebSocket, and retrieving your ghostId.
4. How to retrieve the id of ReportResults you wish to download.

Running a Report

To create report results, use the WebSocket's mergeReportResult command. The report will be run and results created as soon as the merge completes. Each ReportType has its own logic, will summarize differently, and require different ReportParameterTypes.

For example, all reports require startDate and endDate parameters, and the Tag Summary also requires the tags parameter. For a full list of required and optional parameters, please see the Reports API Reference.

To target only specific assets, set the ReportResult.options.targets to a valid search expression..

Here's a process flow:

1. Reconnect to the WebSocket and re-use your ghostId.
   If you don't have a valid ghostId, send login and retrieve it.
2. Send subscribe command with the reportResult SubscriptionType.
3. Send a mergeReportResult command, and check the mergeReportResultResponse for the id.
4. Wait for reportResultMerged messages (with the id from step 3) and check the status for completed (or failed).
   Use the progress value of the object to see the report's progress.
5. Once you know the report is complete, sent a separate HTTP GET for the results to this service.

Retrieving Results as a large JSON object

Downloading the raw, un-transformed results is easy. Once the report is finished processing, send a GET request for the results here:

https://reports.fleetfreedom.com/json/reportResultId?ghostId=ghostId&breakdown=boolean

After sending the GET command, you will receive one of the following responses:

Downloading Results

Completed results are not stored in a particular format as user preferences vary greatly and have an effect on the display of those results. Users can choose a different language or prefer measurements in kilometres or miles. So in order to download the results in a chosen file format, you must request that they are built. Once built, the results are available again instantly.

Downloading results is a two or three step process.

1. Request a build for a given Report Results
2. Optional: Check the progress and status of the build
3. Retrieve the built file

Step 1: Request a build

Requesting a build requires a GET command of the following format:

https://reports.fleetfreedom.com/<format>/reportResultId?ghostId=ghostId&breakdown=boolean&rebuild=boolean&redirect=boolean

For example, if I want the results as a spreadsheet including the detailed breakdown:

https://reports.fleetfreedom.com/xlsx/42?ghostId=<ghostId>&breakdown=true&redirect=true

After sending the GET command, you will receive one of the following responses:

Step 2: Check build progress

https://reports.fleetfreedom.com/queue/<queue-token>/status?ghostId=<ghostId>

Once a build is in progress, you can check the status of the build before going to get the produced file. The response body is a JSON object with two keys; status and progress.

Check the Retry-After response header for a reasonable time limit between checks on build status.

The progress is a floating-point number between 0 and 1.

The status can be one of three values:

Examples

Step 3: Download the file

https://reports.fleetfreedom.com/queue/<queue-token>?ghostId=<ghostId>

After the build completes, the file can be downloaded using the build queue-token given in step 1.

Cancel a build

https://reports.fleetfreedom.com/queue/<queue-token>/cancel?ghostId=<ghostId>

If you no longer need the results file, or wish to free some resources for your user, you can request a build be cancelled.

The processor chooses resources based on the session and user making the requests. If you request many builds at once, the processor may not begin to prepare them all in order to keep resources available for other users.