Run report use case

How to get reports?

To fetch a report from JetAdvice, you are required to send 3 requests to our server:

1. GET /reports/RunRequest Registers a report request to be processed on server, which is returned with "ReportRequestGuid".
2. GET /reports/RunResult Fetches the status of "ReportRunGuid"(=ReportRequestGuid) from server. If completed, it returns with list of File identifiers.
3. GET /reports/RunResultFile Fetches the actual report from server for specified file identifier.

Accept http request header and our query param OutputFormat can be difficult to set apart. Both are handling formatting of response, but there's difference in usage:

  1. Accept http request header is used to control the format of the response of any request except /reports/RunResultFile endpoint. For ex:
    • Accept: application/xml (or text/xml), will return the response in XML format.
    • Accept: application/json, will return the response in JSON format.
  2. OutputFormat query param is only used by /reports/RunRequest endpoint. This controls the format of report to be generated and downloaded through /reports/RunResultFile endpoint. For ex:
    • &outputformat=5, will generate the report in JSON format
    • &outputformat=2, will generate the report in XML format
    • &outputformat=1, will generate the report in CSV format

Why this design?

  1. Some might know about our old /reports/Run endpoint which was synchronous report generation, with limitation/high risk of http timeout for large reports
  2. Asynchronous pattern lets our customers requests and handle responses independently and with better performance using async programming.
  3. Asynchronous pattern avoid both threads and network connections waiting for long time, while report is being generated

Use query param NoDownload=true!

Using NoDownload=true is recommended for all users!

Current default: Multiple response types (deprecated)

By default (without NoDownload=true), the /reports/runResult endpoint will return following responses:

  1. ReportRunResult object with Status=Pending, if report request is still not processed on server.
  2. ReportRunResult object with Status=Finished and list of Files empty, if report generated have no data.
  3. Report object, actual report generated for request (so you don't call the /reports/RunResultFile)

New default: Single response type!

The behavior of NoDownload=true will become the new default!

Some frameworks/API Clients can't handle multiple response types. Therefore we plan to unify the response type for this endpoint.

In the future NoDownload=true behavior will be the new default (even without setting NoDownload=true).

Using NoDownload=true now, will ensure your code won't break when this planned change is applied.

What does NoDownload=true do?

It will override the default behavior for response types, preventing you from getting the actual report (when report generation is completed).

Using NoDownload=true query param, will ensure API always returns ReportRunResult (inclduing when Status=Finished).

It will (instead of providing the report file) list Files with file identifiers when report generation is completed. Use the File identifiers and /reports/RunResultFile to get actual report.

Step 1. /reports/RunRequest

Request

Examples

https://api2.jetadvice.com/reports/runRequest?reportguid=fa463591-f6c5-4aa4-a7a8-16c3f0955a1d&customerid=1234                                                               // Period = last 3 months
https://api2.jetadvice.com/reports/runRequest?reportguid=fa463591-f6c5-4aa4-a7a8-16c3f0955a1d&customerid=1234&outputformat=2                                                // Report in Xml format                
https://api2.jetadvice.com/reports/runRequest?reportguid=fa463591-f6c5-4aa4-a7a8-16c3f0955a1d&customerid=1234&dealerid=123                                                  // Report to run for DealerID = 123
https://api2.jetadvice.com/reports/runRequest?reportguid=fa463591-f6c5-4aa4-a7a8-16c3f0955a1d&customerid=1234&startdate=2015-01-01                                          // Period = from 2015-01-01 till NOW
https://api2.jetadvice.com/reports/runRequest?reportguid=fa463591-f6c5-4aa4-a7a8-16c3f0955a1d&customerid=1234&startdate=2015-01-01&enddate=2016-01-01                       // Period = Whole 2015
https://api2.jetadvice.com/reports/runRequest?reportguid=fa463591-f6c5-4aa4-a7a8-16c3f0955a1d&customerid=1234&startdate=2015-01-01&enddate=2015-12-31+23:59:59              // Period = Whole 2015
https://api2.jetadvice.com/reports/runRequest?reportguid=fa463591-f6c5-4aa4-a7a8-16c3f0955a1d&customerid=1234&startdate=2015-01-01+00:00:00&enddate=2015-12-31+23:59:59     // Period = Whole 2015
https://api2.jetadvice.com/reports/runRequest?reportguid=fa463591-f6c5-4aa4-a7a8-16c3f0955a1d&customerid=1234&tagid=123                                                     // Require devices to be tagged with Tag ID = 123                
https://api2.jetadvice.com/reports/runRequest?reportguid=fa463591-f6c5-4aa4-a7a8-16c3f0955a1d&customerid=1234&activedevicewithin=123                                        // Require devices to be Active within ActiveDeviceWithinID = 123

URI parameters

Name Description Type Additional info
ReportGuid The Report to run globally unique identifier Required
CustomerID The Customer to run the View for integer Required
StartDate Optional - Format(utc): "dd-mm-yyyy+hh:mm:ss" (date is required, time is optional) Default - Use period from Report date Data type: DateTime
EndDate Optional - Format(utc): "dd-mm-yyyy+hh:mm:ss" (date is required, time is optional) Default - Use period from Report date Data type: DateTime
TagID Optional - Result of view, will only contain devices tagged with Tag ID integer None
ActiveDeviceWithin Optional - Set this to filter devices ActiveDeviceWithin None
OutputFormat Optional - Output format of the generated report OutputFormat_Values None
DealerID Optional - Dealer ID integer None

Response

Model: ReportRunRequest

Name Description Type Additional info
ReportGuid Report identifier globally unique identifier None
ReportRequestGuid Report request identifier globally unique identifier None

Sample

Accept header: application/json

{
  "ReportGuid": "f8ceac67-a4c4-4071-b743-93acfb9d00a3",
  "ReportRequestGuid": "b291bc66-978d-4a1b-8a26-915cc010d249"
}

Accept header: application/xml, text/xml

    <ReportRunRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <ReportGuid>f8ceac67-a4c4-4071-b743-93acfb9d00a3</ReportGuid>
        <ReportRequestGuid>b291bc66-978d-4a1b-8a26-915cc010d249</ReportRequestGuid>
    </ReportRunRequest>

Step 2. /reports/RunResult

Request

Examples

https://api2.jetadvice.com/reports/runResult?reportrunguid=61251adf-afb8-4e66-8de8-37f6b5e68957&customerid=1234                                                               // NoDownload = false (deprecated) which implies it will return response with Report content, if available 
https://api2.jetadvice.com/reports/runResult?reportrunguid=61251adf-afb8-4e66-8de8-37f6b5e68957&customerid=1234&nodownload=true                                               // NoDownload = true which implies it will return response with list of ReportRunFile identifiers, if available

URI parameters

Name Description Type Additional info
ReportRunGuid Report run request identifier to generate report globally unique identifier None.
NoDownload [Deprecated] Use this param to override default functionality to return ReportRunResult object instead of actual report generated boolean None

Response

Model: ReportRunResult

Name Description Type Additional info
ReportRunGuid Report request identifier to fetch report result globally unique identifier None
StateID Report request current state ReportRunResultState_Values None
Files Files as result of ReportRunRequest Collection of File None

Sample

Accept header: application/json

{
  "ReportRunGuid": "a757269f-2c0a-45ee-ac00-7f344af79847",
  "StateID": "Finished",
  "Files": [
    {
      "ID": "57c1962c-49ef-4383-a8d8-73c5a84a89b4"
    },
    {
      "ID": "95ae3a12-a674-4ad0-80b5-590c23f21c19"
    }
  ]
}

Accept header: application/xml, text/xml

    <ReportRunResult xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <ReportRunGuid>a757269f-2c0a-45ee-ac00-7f344af79847</ReportRunGuid>
      <StateID>Finished</StateID>
      <Files>
        <File>
          <ID>57c1962c-49ef-4383-a8d8-73c5a84a89b4</ID>
        </File>
        <File>
          <ID>95ae3a12-a674-4ad0-80b5-590c23f21c19</ID>
        </File>
      </Files>
    </ReportRunResult>

Step 3. /reports/RunResultFile

Request

Examples:

https://api2.jetadvice.com/reports/runResultFile?ReportRunFileGuid=763db5f2-4172-4987-8e61-bb0eda78aba3&customerid=1234                                                       // Returns with actual report content corresponding to ReportRunFileGuid

URI parameters

Name Description Type Additional info
ReportRunFileGuid Report run result file identifier to get actual report globally unique identifier None

Response

Resource Description

The format of the Report result is flexible by nature. Depending on the Report setup, the number and types of fields in the result is variable. "OutputFormat" from ReportRunRequest determine response format.

Samples

JSON (ReportRunRequest.OutputFormat=5)

[
    {
        "Device name":"HP Business InkJet 1200",
        "IPv4":"128.253.217.61",
        "Serial #":"TH4AE110NC",
        "Hostname":"HP7C4BE5"
    },
    {                    
        "Device name":"HP CM8060 Color MFP",
        "IPv4":"192.168.0.169",
        "Serial #":"SG73OC100N",
        "Hostname":"NPI0F8B33"
    },
    ...
]

XML (ReportRunRequest.OutputFormat=2)

<?xml version="1.0"?>
<Report>
    <Dates>
        <ReportRun>2015-01-01 10:00:00Z</ReportRun>
        <PeriodStart>2014-01-01 00:00:00Z</PeriodStart>
        <PeriodEnd>2014-12-31 23:59:59Z</PeriodEnd>
    </Dates>
    <Devices>
        <Device>
            <Notice-Message/>
            <Printer-Name>HP Business InkJet 1200</Printer-Name>
            <IPv4>128.253.217.61</IPv4>
            <Serial>TH4AE110NC</Serial>
            <Hostname>HP7C4BE5</Hostname>
        </Device>
        <Device>
            <Notice-Message/>
            <Printer-Name>HP CM8060 Color MFP</Printer-Name>
            <IPv4>192.168.0.169</IPv4>
            <Serial>SG73OC100N</Serial>
            <Hostname>NPI0F8B33</Hostname>
        </Device>
        ...
    </Devices>
</Report>
<?xml version="1.0"?>
<Report>
    <Dates>
        <ReportRun>2015-01-01 10:00:00Z</ReportRun>
        <PeriodStart>2014-01-01 00:00:00Z</PeriodStart>
        <PeriodEnd>2014-12-31 23:59:59Z</PeriodEnd>
    </Dates>
    <Supplies>
        <Supply>
            <Device-Name>HP Business InkJet 1200</Device-Name>
            <IPv4>128.253.217.61</IPv4>
            <Serial>TH4AE110NC</Serial>
            <Hostname>HP7C4BE5</Hostname>
            <Supply-Name>Document Feeder Kit HP L2718A</Supply-Name>
            <Supply-Product>L2718A</Supply-Product>
        </Supply>
        <Supply>
            <Device-Name>HP CM8060 Color MFP</Device-Name>
            <IPv4>192.168.0.169</IPv4>
            <Serial>SG73OC100N</Serial>
            <Hostname>NPI0F8B33</Hostname>                
            <Supply-Name>TK-6307H</Supply-Name>                
            <Supply-Product>1T02LH0CS2</Supply-Product>
        </Supply>
        ...
    </Supplies>
</Report>

CSV (ReportRunRequest.OutputFormat=1)

"Device name";"IPv4";"Serial #";"Hostname"
"HP Business InkJet 1200";"128.253.217.61";"TH4AE110NC";"HP7C4BE5"
"HP CM8060 Color MFP";"192.168.0.169";"SG73OC100N";"NPI0F8B33"
...