Inspections

In order to retrieve the raw data and images from an inspection, you can use the inspection services.

Endpoint: /api/services/custom/inspection

All endpoints of this service share the following behavior:

The {identifier} can be either the task id, inspection id, or the task's external id (called “reference” in the user interface).
You need the permission to view tasks (Tasks.View), either globally or for the team the inspection belongs to.
If no inspection or task is found for the identifier, the server responds with 404 Not Found.
Successful responses are wrapped in the usual result object (result, targetUrl, success, error, unAuthorizedRequest, __abp) – except for the picture download, which returns the image file itself.

1. Getting inspection raw data

Obsolete

This endpoint is obsolete. Please use the report data endpoint instead.

Url: /{identifier}/data

HTTP method: GET

Example:

Request:

GET https://dev.iclportal.com/api/services/custom/inspection/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data HTTP/1.1
Authorization: Bearer <long token>
Accept-Encoding: gzip, deflate

Response:

{
  "result": [
    {
      "externalId": null,
      "created": "2017-12-20T15:54:42Z",
      "closed": "2017-12-21T08:47:45Z",
      "checklist": "SV",
      "checklistId": "c965a4d8-9be8-4f4f-aaf3-409bab9a3c48",
      "chapter": "Messung Anspeisung",
      "headline": "Zeitpunkt",
      "questionName": "Netzart_mes",
      "questionTitle": "Netzart",
      "questionType": "TextBoxIdentifier",
      "value": "SV",
      "isSelected": false,
      "valueRaw": null,
      "likelihoodToFail": null,
      "priorityFactor": null,
      "rating": null,
      "scopePath": ""
    },
    ...
  ],
  "targetUrl": null,
  "success": true,
  "error": null,
  "unAuthorizedRequest": false,
  "__abp": true
}

The data in the result array is a flattened-out representation of all the answers that the inspector entered during an inspection. The entries are ordered by checklistid and then by scopePath.

The scopePath is a very important concept if you are working with repeated sections (headlines or chapters). Whenever an answer value belongs to some repeated section (e.g. information about a defect within a repeated headline), it will have a scopePath which denotes that. In the following example, a repeated headline “Defect” has two questions “location” and “defect_picture”:

[
    {
      "externalId": null,
      "created": "2017-12-20T15:54:42Z",
      "closed": "2017-12-21T08:47:45Z",
      "checklist": "SV",
      "checklistId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "chapter": "Staircase",
      "headline": "Defect",
      "questionName": "location",
      "questionTitle": "Where is the defect located?",
      "questionType": "TextBoxIdentifier",
      "value": "1st floor",
      "isSelected": false,
      "valueRaw": null,
      "likelihoodToFail": null,
      "priorityFactor": null,
      "rating": null,
      "scopePath": "/Defect:0"
    },{
      "externalId": null,
      "created": "2017-12-20T15:54:42Z",
      "closed": "2017-12-21T08:47:45Z",
      "checklist": "SV",
      "checklistId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "chapter": "Staircase",
      "headline": "Defect",
      "questionName": "defect_picture",
      "questionTitle": "Picture:",
      "questionType": "TakePictureIdentifier",
      "value": "47c89e2d-4665-4fe0-947a-f99feff40a96.jpeg",
      "isSelected": false,
      "valueRaw": "b2a5161e-cd5c-4c0a-9ce6-2af34b8082df",
      "likelihoodToFail": null,
      "priorityFactor": null,
      "rating": null,
      "scopePath": "/Defect:0"
    }
]

As you can see, all answers belonging to one specific repeated headline (or chapter) will always have the same scopepath.

note

If there was another repeated defect headline its scopepath would be “/Defect:1” as the scopePath is always constructed using the headlines name and its index within the scope

The values you get for each row should be quite self-explanatory. The only field which deserves further explanation, however, is “valueRaw”.

valueRaw: is a helper field for finding questions. When your checklist contains a question of type “MakeObservationIdentifier” where the user has to select some item from a hierarchy of items, then the value of that answer will be the human-readable version of that selected item and its path. E.g.: Defect/Staircase/HandrailMissing This particular item (HandrailMissing) can also be found using its unique identifier (XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX) and it is this identifier, which is included in valueRaw.

2. Getting the list of pictures

Url: /{identifier}/pictures

HTTP method: GET

Example:

Request:

GET https://dev.iclportal.com/api/services/custom/inspection/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/pictures HTTP/1.1
Authorization: Bearer <long token>
Accept-Encoding: gzip, deflate

Response:

{
  "result": [
    {
      "id": "bc73aeed-a283-482e-bf5e-4cfa26ce7513",
      "title": "737ae90e-d683-4909-b3de-961ccbed7b16.jpeg",
      "description": null,
      "showInReport": false,
      "scope": "Inspection"
    },
    {
      "id": "b2a5161e-cd5c-4c0a-9ce6-2af34b8082df",
      "title": "47c89e2d-4665-4fe0-947a-f99feff40a96.jpeg",
      "description": null,
      "showInReport": true,
      "scope": "Checklist"
    }
  ],
  "targetUrl": null,
  "success": true,
  "error": null,
  "unAuthorizedRequest": false,
  "__abp": true
}

The data in the result array is a list of all the pictures taken during an inspection. Particularly interesting is the field scope which denotes, whether the picture was taken within a checklist, or in the inspections general picture tab.

note

When you are getting the answer of a “TakePicture” question from the raw data endpoint, you will actually get the title of that picture as the answer value.

Also, you will get the id of the picture as valueRaw. In the raw data example above, one answer actually contained the picture b2a5161e-cd5c-4c0a-9ce6-2af34b8082df.

Use the picture's id to download the picture from the download image endpoint.

3. Downloading a picture

Url: /{identifier}/pictures/{pictureIdentifier}/raw

HTTP method: GET

The pictureIdentifier is the unique id (GUID) of the picture. You get it from the list of pictures (id) or from the valueRaw of a picture answer. For pictures of older inspections, the picture's title is also accepted as a fallback.

If the picture cannot be found, the server responds with 404 Not Found.

note

Downloading a picture does not work using the Swagger UI: the image is delivered malformed and cannot be opened.

Example:

Request:

GET https://dev.iclportal.com/api/services/custom/inspection/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/pictures/b2a5161e-cd5c-4c0a-9ce6-2af34b8082df/raw HTTP/1.1
Authorization: Bearer <long token>
Accept-Encoding: gzip, deflate

Response:

HTTP/1.1 200 OK
Cache-Control: public, max-age=172800
Content-Type: image/jpeg
Content-Encoding: gzip
Server: Microsoft-IIS/10.0
Set-Cookie: fileDownload=true; path=/
Content-Disposition: attachment; filename=47c89e2d-4665-4fe0-947a-f99feff40a96.jpeg
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Wed, 02 May 2018 08:56:52 GMT
Content-Length: 45776

… raw data …

4. Getting the report data

Returns the detailed data of all checklists of an inspection in the default language of the workbook. This is the recommended replacement of the obsolete raw data endpoint. The data is returned row by row (one row per answer), so it remains independent from the structure of the checklists.

Url: /{identifier}/reportdata

HTTP method: GET

Example:

Request:

GET https://dev.iclportal.com/api/services/custom/inspection/6603837e-2d0d-4b3b-9264-99867c4151a8/reportdata HTTP/1.1
Authorization: Bearer <long token>
Accept: application/json

Response (abbreviated: each row contains more fields than shown here, see the table below):

{
  "result": [
    {
      "inspectionId": "6603837e-2d0d-4b3b-9264-99867c4151a8",
      "inspectionName": "Main Street 1",
      "inspectorName": "John Doe",
      "taskId": "5bb89fe4-25dd-4014-b00e-c3ed05c15213",
      "workbookTemplate": "Building inspection",
      "workbookVersion": "12",
      "checklist": "Staircase",
      "checklistName": "staircase",
      "checklistId": "c965a4d8-9be8-4f4f-aaf3-409bab9a3c48",
      "groupLevel1": "Staircase",
      "groupLevel1Name": "staircase",
      "groupLevel2": "Defect",
      "groupLevel2Name": "Defect",
      "question": "Where is the defect located?",
      "questionName": "location",
      "questionType": "TextBoxIdentifier",
      "answer": "1st floor",
      "answerRaw": "1st floor",
      "path": "/Defect:0",
      "order": 0,
      "language": "en"
    }
  ],
  "targetUrl": null,
  "success": true,
  "error": null,
  "unAuthorizedRequest": false,
  "__abp": true
}

The most important fields of a row:

Name	Description
inspectionId, inspectionName, inspectorName	The inspection the answer belongs to, its title and the user who created it
createdDate, closedDate, sentDate	When the inspection was created, completed and sent
taskId	The id of the task of the inspection, or `null` if the inspection has no task
workbookId, workbookTemplate, workbookVersion	The workbook the inspection was carried out with
checklist, checklistName, checklistId	The title, name and id of the checklist
groupLevel1 … groupLevel3	The titles of the groups (e.g. chapter and headline) the question is in. `groupLevelXName` and `groupLevelXId` contain their names and ids
question, questionName, questionId, questionType	The title, name, id and type of the question
answer	The answer as text. For catalog and content item questions, this is the display text of the selected item
answerRaw	The raw value of the answer
isSelectedAnswer	Whether this answer was selected (for questions with selectable answers)
path	The scope path of the answer within repeated sections (see the explanation of the scopePath in the raw data endpoint)
scopeName1 … scopeName3, scopeIndex1 … scopeIndex3	The names and indexes of the repeated sections the answer is in
order	The position of the row within its checklist
language	The language the checklist data is returned in

If the checklist data of the inspection cannot be loaded (e.g. because the inspection was created with an old data format or its workbook is not available), the server responds with 400 Bad Request.

5. Getting the report data in a specific language

Same as the report data endpoint, but returns the checklist data in the given language.

Url: /{identifier}/reportdata/{language}

HTTP method: GET

Name	Type	Required?	Description
language	string	Required	A language of the workbook (e.g. `en` or `fr`), or `user` to get the data in the language the inspector selected when starting the inspection. If the language cannot be found, the default language of the workbook is used.

Example:

GET https://dev.iclportal.com/api/services/custom/inspection/6603837e-2d0d-4b3b-9264-99867c4151a8/reportdata/fr HTTP/1.1
Authorization: Bearer <long token>
Accept: application/json

The language field of each row tells you which language was actually used.

6. Getting the inspected items

Returns the list of (content) items that were inspected (or should have been inspected) in an inspection.

Url: /{identifier}/inspecteditems

HTTP method: GET

Example:

Request:

GET https://dev.iclportal.com/api/services/custom/inspection/6603837e-2d0d-4b3b-9264-99867c4151a8/inspecteditems HTTP/1.1
Authorization: Bearer <long token>
Accept: application/json

Response:

{
  "result": [
    {
      "inspectionId": "6603837e-2d0d-4b3b-9264-99867c4151a8",
      "title": "Elevator 1",
      "externalId": "ELV-0001",
      "contentItemId": "0f0b5e0c-6f53-4a8e-9a2b-3c1d2e4f5a6b",
      "contentTypeDefinitionId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "contentTypeName": "elevator",
      "wasInspected": true
    }
  ],
  "targetUrl": null,
  "success": true,
  "error": null,
  "unAuthorizedRequest": false,
  "__abp": true
}

Name	Type	Description
inspectionId	string	The unique id of the inspection
contentItemId	string	The unique id of the content item
title	string	The title of the content item
externalId	string	The external id of the content item
contentTypeDefinitionId	string	The unique id of the content type of the item
contentTypeName	string	The name of the content type of the item
wasInspected	boolean	`true` if the item was actually inspected, `false` if it should have been inspected but was not

7. Getting the content item values of an inspection

Extracts all content item information (properties) from the checklists of an inspection, i.e. the values of content item properties as they were entered by the app user during the inspection.

note

This only returns property values that were actually set in the checklist. If a field of a content item was not mapped to any checklist field and, thus, not changed, it is not returned. Empty values are not returned either.

Url: /{identifier}/contentitems

HTTP method: GET

Example:

Request:

GET https://dev.iclportal.com/api/services/custom/inspection/6603837e-2d0d-4b3b-9264-99867c4151a8/contentitems HTTP/1.1
Authorization: Bearer <long token>
Accept: application/json

Response:

{
  "result": {
    "elevator": [
      {
        "title": "Elevator 1",
        "maxload": 630,
        "id": "0f0b5e0c-6f53-4a8e-9a2b-3c1d2e4f5a6b"
      }
    ]
  },
  "targetUrl": null,
  "success": true,
  "error": null,
  "unAuthorizedRequest": false,
  "__abp": true
}

The result is an object with one entry per content type name. Each entry is a list of the content items of this type that were used in the checklists, containing their property values and their unique id.

1. Getting inspection raw data​

2. Getting the list of pictures​

3. Downloading a picture​

4. Getting the report data​

5. Getting the report data in a specific language​

6. Getting the inspected items​

7. Getting the content item values of an inspection​

1. Getting inspection raw data

2. Getting the list of pictures

3. Downloading a picture

4. Getting the report data

5. Getting the report data in a specific language

6. Getting the inspected items

7. Getting the content item values of an inspection