Reports

In order to download reports generated for a specific inspection, the following REST service can be used. Endpoints: ~~/api/services/app/reports~~ /api/services/custom/externalreport /api/reports

Obsolete endpoints: ~~/api/services/app/reports~~

1. Querying reports

Once an inspector has finished an inspection, or created a draft report, that list of reports can be retrieved.

Url: /getall

HTTP method: GET

Example:

GET https://dev.iclportal.com/api/services/custom/externalreports/getall HTTP/1.1

{
   "results":[
      {
         "id":"c87be9ab-1d35-4c6a-8444-2aed3eb9a717",
         "isDraft":false,
         "reportState":3,
         "fileName":"TheActualFilename.pdf",
         "mimeType":"application/pdf",
         "recipients":"",
         "error":null,
         "creationTime": "2016-03-15T14:55:06.182Z",
         "created":"2016-03-15T15:10:08.257Z",
         "inspectionCompletedDate": "2016-03-15T15:05:06.182Z",
         "inspectionSentDate": "2016-03-15T15:10:12.182Z",
         "workAreaId":"51cd73f7-d176-4833-9bd5-903eb9d8c0d3"
      },
   ],
   "__count":1
}

Example 2 – getting a list of 10 reports that were successfully created since a specific point in time:

GET https://dev.iclportal.com/api/services/custom/externalreports/getall?$filter=Created+ge+datetime%272016-03-15T00:00:00%27&$inlinecount=allpages&$top=10 HTTP/1.1 HTTP/1.1

{
   "results":[
      {
         "id":"c87be9ab-1d35-4c6a-8444-2aed3eb9a717",
         "isDraft":false,
         "reportState":3,
         "fileName":"TheActualFilename.pdf",
         "mimeType":"application/pdf",
         "recipients":"",
         "error":null,
         "creationTime": "2016-03-15T14:55:06.182Z",
         "created":"2016-03-15T15:10:08.257Z",
         "inspectionCompletedDate": "2016-03-15T15:05:06.182Z",
         "inspectionSentDate": "2016-03-15T15:10:12.182Z",
         "workAreaId":"51cd73f7-d176-4833-9bd5-903eb9d8c0d3"
      },
   ],
   "__count":1
}

Name	Type	Description
id	string	The unique identity of a report. Note: Whenever a report is re-created, a new record is created for it. Therefore, the id will also change
isDraft	boolean	If `true`, indicates that this is not a final report, but a draft report that was created before completing an inspection to get a preview of the document
reportState	number	Specifies which state a report is in. Can be 0..new, 1..pending, 2..failed, 3..completed
fileName	string	The file name
mimeType	string	The mime type
recipients	string	Comma separated list of all the e-mail addresses that this report was sent to
error	string	In case the report state is 2..failed, this field will show the error message
creationTime	date	The point in time the record of this report was created. Note: This happens in the app, so using this to filter reports can lead to missing data as these recorts may not be synchronized yet
created	date	The point in time the report was created on the server. This field can be used for querying incremental changes.
inspectionCompletedDate	date	The point in time the user completed the inspection in the app. Note: This happens in the app, so using this to filter reports can lead to missing data as these recorts may not be synchronized yet
inspectionSentDate	date	The point in time when the app determined, that all data was transferred to the server and all final reports were created successfully. Note: This happens in the app, so using this to filter reports can lead to missing data as these recorts may not be synchronized yet
workAreaId	string	The unique identity of the team that this report (and its parent inspection) was created in

The process of creating the reports is the following:

The user completes the inspection in the app. (inspectionCompletedDate)
Therefore, the records for the final reports are created (creationTime)
The server creates the reports and sets their created date. (created)
Upon receiving the acknowledgement that all reports have been created, the app flags the inspection as sent (inspectionSentDate) This shows that those date fields always have the following relationship: inspectionCompletedDate < creationTime < created < inspectionSentDate

Parameters: This is an ODATA 3.0 Endpoint allowing you to query the tasks in the system.

note

You can use all the attributes of the returned json objects to create a query. However, due to the ODATA specification, you must uppercase them in the query. As this is a convention in JSON and the JavaScript workd, our results are returned with the attribute names lowercased.

Example: You get a task like:

{"workAreaTitle":"Vienna Inspectors", …}
As you can see, the “workAreaTitle” attribute is starting with a lowercased letter.
If you, however, query the ODATA endpoint using “workAreaTitle”, you need to uppercase its first letter:
/getall?$filter=WorkAreaTitle+eq+….

note

“WorkArea” is our internal name for “Team”

2. Retrieving list of reports for an inspection

Once an inspector has finished an inspection, or created a draft report, that list of reports can be retrieved.

Url: /getofinspection

HTTP method: GET

Example:

GET https://dev.iclportal.com/api/services/app/reports/getofinspection?inspectionId=<uniqueid> HTTP/1.1

Name	Type	Required?	Description
inspectionId	string	Required	The unique identity of the inspection that the reports belong to. (To get the inspectionId, see 3.3)

The server will respond with a 200 OK containing a result object in the respone body, which in turn is a JSON array containing the following entries:

Name	Type	Description
id	string	The unique id of that report.
isDraft	boolean	True if this is a draft report that may be deleted at any time. False if this a final report.
reportState	enumeration	The current state this particular report is in: Pending = 0, // waiting to be generated Generating = 1, // currently being generated Failed = 2, // failed generating report Generated = 3, // report is complete and can be retrieved
fileName	string	The actual filename of this report.
mimeType	string	The mimetype of the reports file.
recipients	string	The list of e-mail recipients that this report is/has been sent to.
error	string	In case an error occurred during generating this report, this field contains the actual error message.
created	date	The date and time that this report has been generated.
workAreaId	string	The globally unique id of the workarea/team that this report is associated to.

Sample request and response 2

Request:

GET https:// dev.iclportal.com/api/services/app/reports/getofinspection?inspectionId=98e678a5-e771-46dd-b933-8a3ee9059684 HTTP/1.1
Host: dev.iclportal.com
Connection: keep-alive
Accept: application/json, text/plain, */*
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/50.0.2661.102 Safari/537.36
Authorization: Bearer <long token>

Response:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 204
Content-Type: application/json; charset=utf-8
Expires: -1
Server: Microsoft-IIS/8.0
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Mon, 25 Jan 2016 11:23:53 GMT

{
   "results":[
      {
         "id":"c87be9ab-1d35-4c6a-8444-2aed3eb9a717",
         "isDraft":false,
         "reportState":3,
         "fileName":"TheActualFilename.pdf",
         "mimeType":"application/pdf",
         "recipients":"",
         "error":null,
         "created":"2016-03-15T15:10:08.257Z",
         "workAreaId":"51cd73f7-d176-4833-9bd5-903eb9d8c0d3"
      },
   ],
   "__count":1
}

3. Downloading reports

In order to download a generated report (reportstate=3), you can use this url

Url: /get

HTTP method: GET

Example:

GET https://dev.iclportal.com/api/reports/get/<reportId> HTTP/1.1

Name	Type	Required?	Description
reportId	string	Required	The unique identity of the report

The server will respond with a 200 OK containing the actual report file in the response stream.

Sample request and response 3

Request:

GET https:// dev.iclportal.com /api/reports/get/c87be9ab-1d35-4c6a-8444-2aed3eb9a717 HTTP/1.1
Host: dev.iclportal.com
Connection: keep-alive
Authorization: Bearer <long token>

Response:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/pdf
Content-Encoding: gzip
Expires: -1
Server: Microsoft-IIS/10.0
Set-Cookie: fileDownload=true; path=/
Content-Disposition: attachment; filename=TheActualFilename.pdf
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Wed, 01 Jun 2016 10:13:00 GMT
Content-Length: 83756

%PDF-1.5
4 0 obj
<</Type /Page/Parent 3 0 R/Contents 5 0 R/MediaBox [0 0 595.45001221 841.70001221]/Resources<</Font<</FAAAAH 7 0 R/FAAABA 10 0 R/FAAABD 13 0 R/FAAABG 16 0 R/FAAABJ 19 0 R/FAAACF 25 0 R>>/XObject<</X1 28 0 R>>>>/Group <</Type/Group/S/Transparency/CS/DeviceRGB>>/Annots[23 0 R 27 0 R ]>>
endobj
5 0 obj
<</Length 29 0 R/Filter /FlateDecode>>stream
x  Y r M K  N2   oԐR EY3.  U I EOjf 6 _ _  y S~  = H * #\  . n  8 M ~x-  
......

4. Getting changed reports

This api provides you with a way to get all the reports that have changed since the last time the API was called. This is realized using a changeToken which you need to store in an external system.

For a more in-depth example, see the incremental changes walkthrough.

GET https://dev.iclportal.com/api/services/custom/externalReports/GetChanges HTTP/1.1
Accept: application/json
Authorization: Bearer HwBUGEn1p9S5BJi6iM.....

Response gives us the reports (as expected) but includes a nextChangeToken and nextLink that can be used to get the next 500 changed reports.

{
    "result": {
        "results": [
         {
         "id": "4b2c2e24-52b6-4f3f-8efa-3fd7b15c3e0c",
         "reportState": 3,
         "error": null,
         "isDraft": false,
         "fileName": null,
         "mimeType": null,
         "recipients": "optiqser@opti-q.com,s.p@opti-q.com",
         "taskTitle": null,
         "taskId": null,
         "inspectionId": "a4da0ea9-e567-4c15-8c8f-25526b17d1a4",
         "taskExternalId": null,
         "inspectionTitle": "Brandschutz-Kontrolle 13.08.2021",
         "workAreaTitle": "Brandschutz Test",
         "workbookTitle": "Brandschutz-Kontrolle",
         "creationTime": "2021-08-13T11:58:39.72Z",
         "created": "2021-08-13T11:59:50.637Z",
         "inspectionCompletedDate": "2021-08-13T11:58:13.533Z",
         "inspectionSentDate": "2021-08-13T12:00:51.95Z",
         "workAreaId": "c9518bd5-016f-4030-9937-86e5c3a1b97f",
         "isDeleted": false, // this also gives you deleted reports
         "deletionTime": null
         },
         {
         "id": "9ab5d5b7-d692-4600-a82b-c0e1e271c4d7",
         "reportState": 3,
         "error": null,
         "isDraft": false,
         "fileName": null,
         "mimeType": null,
         "recipients": null,
         "taskTitle": null,
         "taskId": null,
         "inspectionId": "a4da0ea9-e567-4c15-8c8f-25526b17d1a4",
         "taskExternalId": null,
         "inspectionTitle": "Brandschutz-Kontrolle 13.08.2021",
         "workAreaTitle": "Brandschutz Test",
         "workbookTitle": "Brandschutz-Kontrolle",
         "creationTime": "2021-08-13T11:59:58.31Z",
         "created": "2021-08-13T12:00:25.94Z",
         "inspectionCompletedDate": "2021-08-13T11:58:13.533Z",
         "inspectionSentDate": "2021-08-13T12:00:51.95Z",
         "workAreaId": "c9518bd5-016f-4030-9937-86e5c3a1b97f",
         "isDeleted": false, // this also gives you deleted reports
         "deletionTime": null
         },
            ... many many more... (500 total)
        ],
        "nextChangeToken": "AAAAAAAFpYA",
        "nextLink": "https://dev.iclportal.com/api/services/custom/externalReports/GetChanges?changeToken=AAAAAAAFpYA"
    },
    "targetUrl": null,
    "success": true,
    "error": null,
    "unAuthorizedRequest": false,
    "__abp": true
}

this endpoint also returns deleted reports

As this endpoint is for getting any incremental changes, it also returns deleted reports, so that you can remove them from your system accordingly.

Directly get to the last page

As there are no more changes, the system simply returns the latest change available, which is usually the very same change token we just used in the request.

However, you can use this mechanism to get straight to the last page of changed reports by using the highest possible change token __________8 This comes in handy, if you only want to start for getting changes from now on and do not wish to go through all the historical changes.

1. Querying reports​

2. Retrieving list of reports for an inspection​

Sample request and response 2​

3. Downloading reports​

Sample request and response 3​

4. Getting changed reports​

1. Querying reports

2. Retrieving list of reports for an inspection

Sample request and response 2

3. Downloading reports

Sample request and response 3

4. Getting changed reports