Inspektionen

Um die Rohdaten und Bilder einer Inspektion abzurufen, können Sie die Inspektionsdienste verwenden.

Endpunkt: /api/services/custom/inspection

Für alle Endpunkte dieses Dienstes gilt:

• Der {identifier} kann entweder die Aufgaben-ID, die Inspektions-ID oder die externe ID der Aufgabe (in der Benutzeroberfläche "Referenz" genannt) sein.
• Sie benötigen die Berechtigung zum Anzeigen von Aufgaben (Tasks.View), entweder global oder für das Team, zu dem die Inspektion gehört.
• Wird zum Bezeichner keine Inspektion und keine Aufgabe gefunden, antwortet der Server mit 404 Not Found.
• Erfolgreiche Antworten sind in das übliche Ergebnisobjekt verpackt (result, targetUrl, success, error, unAuthorizedRequest, __abp) – außer beim Herunterladen eines Bildes, das die Bilddatei selbst liefert.

1. Abrufen von Inspektionsrohdaten

Veraltet

Dieser Endpunkt ist veraltet. Bitte verwenden Sie stattdessen den Endpunkt für Berichtsdaten.

Url: /{identifier}/data

HTTP-Methode: GET

Beispiel:

Anfrage:

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

Antwort:

{
  "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
}

Die Daten im Ergebnis-Array sind eine reduzierte Darstellung aller Antworten, die der Inspektor während einer Inspektion eingegeben hat. Die Einträge sind nach checklistid und dann nach scopePath geordnet.

Der scopePath ist ein sehr wichtiges Konzept, wenn Sie mit wiederholten Abschnitten (Überschriften oder Kapiteln) arbeiten. Immer wenn ein Antwortwert zu einem wiederholten Abschnitt gehört (z.B. Informationen über einen Mangel innerhalb einer wiederholten Überschrift), hat er einen scopePath, der dies kennzeichnet. Im folgenden Beispiel hat eine wiederholte Überschrift "Defect" zwei Fragen "location" und "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"
    }
]

Wie Sie sehen können, haben alle Antworten, die zu einer bestimmten wiederholten Überschrift (oder einem Kapitel) gehören, immer denselben scopepath.

Hinweis

Wenn es eine weitere wiederholte Überschrift "Defect" gäbe, würde ihr scopepath "/Defect:1" lauten, da der scopePath immer aus dem Namen der Überschrift und ihrem Index innerhalb des Scopes gebildet wird.

Die Werte, die Sie für jede Zeile erhalten, sollten ziemlich selbsterklärend sein. Das einzige Feld, das eine weitere Erklärung verdient, ist "valueRaw".

valueRaw: ist ein Hilfsfeld für die Feststellung von Fragen. Wenn Ihre Checkliste eine Frage des Typs "MakeObservationIdentifier" enthält, bei der der Benutzer ein Element aus einer Hierarchie von Elementen auswählen muss, dann ist der Wert dieser Antwort die vom Menschen lesbare Version des ausgewählten Elements und seines Pfads. Z.B.: Defect/Staircase/HandrailMissing Dieses bestimmte Element (HandrailMissing) kann auch über seinen eindeutigen Bezeichner (XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX) gefunden werden und dieser Bezeichner ist in valueRaw enthalten.

2. Abrufen der Liste der Bilder

Url: /{identifier}/pictures

HTTP-Methode: GET

Beispiel:

Anfrage:

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

Antwort:

{
  "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
}

Die Daten im Ergebnis-Array sind eine Liste aller Bilder, die während einer Inspektion aufgenommen wurden. Besonders interessant ist das Feld scope, das angibt, ob das Bild im Rahmen einer Checkliste oder im allgemeinen Bildregister der Inspektion aufgenommen wurde.

Hinweis

Wenn Sie die Antwort auf eine "TakePicture"-Frage vom Endpunkt für Rohdaten erhalten, bekommen Sie den Titel des Bildes als Antwortwert.

Außerdem erhalten Sie die ID des Bildes als valueRaw. Im Beispiel der Rohdaten oben enthielt eine Antwort tatsächlich das Bild b2a5161e-cd5c-4c0a-9ce6-2af34b8082df.

Verwenden Sie die ID des Bildes, um das Bild vom Endpunkt zum Herunterladen von Bildern herunterzuladen.

3. Herunterladen eines Bildes

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

HTTP-Methode: GET

Der pictureIdentifier ist die eindeutige ID (GUID) des Bildes. Sie erhalten sie aus der Liste der Bilder (id) oder aus dem valueRaw einer Bild-Antwort. Für Bilder älterer Inspektionen wird ersatzweise auch der Titel des Bildes akzeptiert.

Wird das Bild nicht gefunden, antwortet der Server mit 404 Not Found.

Hinweis

Das Herunterladen eines Bildes funktioniert nicht über die Swagger UI: Das Bild wird fehlerhaft ausgeliefert und kann nicht geöffnet werden.

Beispiel:

Anfrage:

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

Antwort:

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. Abrufen der Berichtsdaten

Liefert die detaillierten Daten aller Checklisten einer Inspektion in der Standardsprache des Workbooks. Dies ist der empfohlene Ersatz für den veralteten Endpunkt für Rohdaten. Die Daten werden zeilenweise (eine Zeile pro Antwort) geliefert und sind dadurch unabhängig von der Struktur der Checklisten.

Url: /{identifier}/reportdata

HTTP-Methode: GET

Beispiel:

Anfrage:

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

Antwort (gekürzt: jede Zeile enthält mehr Felder als hier gezeigt, siehe Tabelle unten):

{
  "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
}

Die wichtigsten Felder einer Zeile:

Name	Beschreibung
inspectionId, inspectionName, inspectorName	Die Inspektion, zu der die Antwort gehört, ihr Titel und der Benutzer, der sie erstellt hat
createdDate, closedDate, sentDate	Wann die Inspektion erstellt, abgeschlossen und gesendet wurde
taskId	Die ID der Aufgabe der Inspektion oder null, wenn die Inspektion keine Aufgabe hat
workbookId, workbookTemplate, workbookVersion	Das Workbook, mit dem die Inspektion durchgeführt wurde
checklist, checklistName, checklistId	Titel, Name und ID der Checkliste
groupLevel1 … groupLevel3	Die Titel der Gruppen (z.B. Kapitel und Überschrift), in denen sich die Frage befindet. groupLevelXName und groupLevelXId enthalten deren Namen und IDs
question, questionName, questionId, questionType	Titel, Name, ID und Typ der Frage
answer	Die Antwort als Text. Bei Katalog- und Inhaltselement-Fragen ist dies der Anzeigetext des ausgewählten Elements
answerRaw	Der Rohwert der Antwort
isSelectedAnswer	Ob diese Antwort ausgewählt wurde (bei Fragen mit auswählbaren Antworten)
path	Der Scope-Pfad der Antwort innerhalb wiederholter Abschnitte (siehe die Erklärung des scopePath beim Endpunkt für Rohdaten)
scopeName1 … scopeName3, scopeIndex1 … scopeIndex3	Die Namen und Indizes der wiederholten Abschnitte, in denen sich die Antwort befindet
order	Die Position der Zeile innerhalb ihrer Checkliste
language	Die Sprache, in der die Checklistendaten geliefert werden

Können die Checklistendaten der Inspektion nicht geladen werden (z.B. weil die Inspektion mit einem alten Datenformat erstellt wurde oder ihr Workbook nicht verfügbar ist), antwortet der Server mit 400 Bad Request.

5. Abrufen der Berichtsdaten in einer bestimmten Sprache

Wie der Endpunkt für Berichtsdaten, liefert die Checklistendaten aber in der angegebenen Sprache.

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

HTTP-Methode: GET

Name	Typ	Erforderlich?	Beschreibung
language	string	Erforderlich	Eine Sprache des Workbooks (z.B. en oder fr) oder user, um die Daten in der Sprache zu erhalten, die der Inspektor beim Starten der Inspektion gewählt hat. Wird die Sprache nicht gefunden, wird die Standardsprache des Workbooks verwendet.

Beispiel:

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

Das Feld language jeder Zeile gibt an, welche Sprache tatsächlich verwendet wurde.

6. Abrufen der inspizierten Elemente

Liefert die Liste der (Inhalts-)Elemente, die in einer Inspektion inspiziert wurden (oder hätten inspiziert werden sollen).

Url: /{identifier}/inspecteditems

HTTP-Methode: GET

Beispiel:

Anfrage:

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

Antwort:

{
  "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	Typ	Beschreibung
inspectionId	string	Die eindeutige ID der Inspektion
contentItemId	string	Die eindeutige ID des Inhaltselements
title	string	Der Titel des Inhaltselements
externalId	string	Die externe ID des Inhaltselements
contentTypeDefinitionId	string	Die eindeutige ID des Inhaltstyps des Elements
contentTypeName	string	Der Name des Inhaltstyps des Elements
wasInspected	boolean	true, wenn das Element tatsächlich inspiziert wurde, false, wenn es hätte inspiziert werden sollen, aber nicht inspiziert wurde

7. Abrufen der Werte der Inhaltselemente einer Inspektion

Liest alle Informationen (Eigenschaften) der Inhaltselemente aus den Checklisten einer Inspektion aus, d.h. die Werte der Eigenschaften der Inhaltselemente, wie sie der App-Benutzer während der Inspektion eingegeben hat.

Hinweis

Es werden nur Eigenschaftswerte geliefert, die tatsächlich in der Checkliste gesetzt wurden. Wurde ein Feld eines Inhaltselements keinem Checklistenfeld zugeordnet und daher nicht geändert, wird es nicht geliefert. Leere Werte werden ebenfalls nicht geliefert.

Url: /{identifier}/contentitems

HTTP-Methode: GET

Beispiel:

Anfrage:

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

Antwort:

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

Das Ergebnis ist ein Objekt mit einem Eintrag pro Name eines Inhaltstyps. Jeder Eintrag ist eine Liste der Inhaltselemente dieses Typs, die in den Checklisten verwendet wurden, mit ihren Eigenschaftswerten und ihrer eindeutigen id.