Zum Hauptinhalt springen

3. Abrufen der neuesten Berichte

Ein typisches Integrationsszenario ist, dass Sie alle Abschlussberichte von Inspektionen abrufen müssen, um sie z.B. in einem speziellen Dokumentenmanagementsystem zu speichern. Dies kann sogar eine gesetzliche Anforderung sein. Hierfür gibt es zwei Ansätze.

  1. Sie können die Änderungen von Aufgaben abfragen, bis eine Aufgabe als erledigt markiert ist und ein Sendedatum hat. Zu diesem Zeitpunkt können Sie alle Berichte zu dieser Aufgabe/Inspektion abfragen und jede Datei einzeln herunterladen.
  2. Der einfachere Ansatz ist, die Änderungen der Berichte selbst abzufragen.

In jedem Fall müssen Sie überprüfen, ob es sich bei dem Bericht nicht um einen Entwurf handelt und ob er erfolgreich erstellt worden ist. Dies kann durch die Überprüfung der Eigenschaften "isDraft" und "reportState" des Berichts erfolgen.

  • Ein Bericht, bei dem isDraft auf true gesetzt ist, ist nur ein Berichtsentwurf, der vom Benutzer während der Prüfung erstellt wurde, um zu sehen, wie der Bericht aussehen wird.
  • Jeder andere reportState als 3 bedeutet, dass der Bericht nicht erfolgreich erstellt wurde und Sie ihn nicht herunterladen sollten.
Berichtszustände

Berichte haben ihre eigene Reihe von Zuständen.

  • 0... bedeutet in Bearbeitung oder in Erwartung der Erstellung
  • 1... sobald das Portal mit der Erstellung des Berichts beginnt, wird der Status auf 1 gesetzt, was in Erstellung bedeutet
  • 2... falls etwas schiefgeht - z.B. ein Fehler in der Berichtsvorlage - wird der Status auf 2 gesetzt, was Fehler bedeutet
  • 3... oder wenn alles gut geht und der Bericht erfolgreich erstellt wurde, wird der Status auf 3 gesetzt, was erstellt bedeutet

1. Ansatz: Herunterladen von Berichten über abgeschlossene Aufgaben/Inspektionen​

Dieser erste Ansatz ist ratsam, wenn Sie zusätzlich einige Metadaten zu den Aufgaben in Ihrem Altsystem aktualisieren müssen. Während Sie bereits die Änderungen von Aufgaben abfragen, können Sie auch prüfen, ob die Aufgabe abgeschlossen ist und ein Sendedatum hat, um festzustellen, ob es Berichte zum Herunterladen gibt.

Als Erstes sollten Sie die zuletzt geänderten Aufgaben abfragen.

task changes walkthrough

Um ein tieferes Verständnis dieser API zu erhalten, lesen Sie bitte diese Anleitung.

GET https://dev.iclportal.com/api/services/custom/externalTask/GetChanges?changeToken=AAAAAAAFpYA HTTP/1.1
Accept: application/json
Authorization: Bearer HwBUGEn1p9S5BJi6iM.....
Hinweis

AAAAAAAFpYA ist ein fiktiver Änderungs-Token. Sie müssen es durch den letzten Änderungs-Token ersetzen, den Sie vom vorherigen Aufruf erhalten haben, oder den Token weglassen

So erhalten Sie die zuletzt geänderten Aufgaben. Nehmen wir nun an, dass eine der Aufgaben den Status abgeschlossen und ein Absendedatum hat: 

{
    "result": {
        "results": [
            {
                "id": "5bb89fe4-25dd-4014-b00e-c3ed05c15213",
                "inspectionId": "6603837e-2d0d-4b3b-9264-99867c4151a8",
                "externalId": "TSK___000001",
                "title": "Task 000000",
                "workbookId": "baf7b34d-825a-443b-bf5e-928ff83d9c2e",
                "workbookTitle": "test iWorkbook",
                "workbookVersionCode": 52,
                "assignedUserId": 4,
                "assignedUserName": "antoine gadget",
                "description": null,
                "startDate": null,
                "dueDate": null,
                "state": 3, // das ist der Status "erstellt"
                "isSelfAssignable": true,
                "workAreaId": "6058f602-f55b-45b2-90b2-9081869f7774",
                "workAreaTitle": "test",
                "isPublished": true,
                "actualStart": "2022-10-18T13:16:23.583Z",
                "actualEnd": "2022-10-18T14:15:23.583Z", // der Inspektor hat diese Aufgabe erfüllt
                "sentDate": "2022-10-18T16:20:00.583Z", //  und das Sendedatum ist gesetzt, was bedeutet, dass alle erforderlichen Berichte erstellt wurden
                "hasTask": true,
                "lastModificationTime": "2022-10-21T13:16:23.583Z",
                "inspectedItems": null,
                "isDeleted": false
            },
            ... many many more... (500 total)
        ],
        "nextChangeToken": "AAAAAAAFpYA",
        "nextLink": "https://dev.iclportal.com/api/services/custom/externalTask/GetChanges?changeToken=AAAAAAAFpYA"
    },
    "targetUrl": null,
    "success": true,
    "error": null,
    "unAuthorizedRequest": false,
    "__abp": true
}

Sie wissen nun, dass Sie die Berichte dieser Aufgabe abfragen können. Dazu müssen Sie zunächst alle Berichte zu dieser Aufgabe/Inspektion abrufen:

GET https://dev.iclportal.com/api/services/app/reports/getofinspection?inspectionId=6603837e-2d0d-4b3b-9264-99867c4151a8
Authorization: Bearer HwBUGEn1p9S5BJi6iM.....
use the inspectionid

Beachten Sie, dass Sie die inspectionid und nicht die externalid für diesen Endpunkt benötigen

So erhalten Sie eine Liste aller Berichte zu dieser Aufgabe/Inspektion

{
    "result": {
        "results": [
            {
                "id": "5576222e-6936-41e5-adc2-468ee5022e35",
                "isDraft": false, // dieser Bericht ist ein Abschlussbericht
                "reportState": 3, // 3 bedeutet "erfolgreich erstellt"
                "fileName": "003ZP1332-2022-3_WORD.docx",
                "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
                "recipients": null,
                "error": null,
                "created": "2022-10-18T13:28:09.48Z",
                "workAreaId": "f46628b0-8eb2-4db3-b142-e77c23572400"
            },
            {
                "id": "472ec6d5-3a8f-45d0-812c-be801de8dd9a",
                "isDraft": false, // dieser Bericht ist ein Abschlussbericht
                "reportState": 3, // 3 bedeutet "erfolgreich erstellt"
                "fileName": "003ZP1332-2022-3.pdf",
                "mimeType": "application/pdf",
                "recipients": "optiqser@opti-q.com,office@democorp.com",
                "error": null,
                "created": "2022-10-18T13:27:48.997Z",
                "workAreaId": "f46628b0-8eb2-4db3-b142-e77c23572400"
            }
        ],
        "__count": 2
    },
    "targetUrl": null,
    "success": true,
    "error": null,
    "unAuthorizedRequest": false,
    "__abp": true
}

Wie Sie sehen können, geben die Ergebnisse Auskunft darüber, wann der Bericht erstellt wurde und was der Bericht ist (pdf, word, etc.). Wichtiger ist jedoch, dass der reportState 3 ist.

Der letzte Schritt besteht darin, jeden Bericht anhand seiner id über die reports get API herunterzuladen.

GET https://dev.iclportal.com/api/reports/get/5576222e-6936-41e5-adc2-468ee5022e35
Authorization: Bearer HwBUGEn1p9S5BJi6iM.....

Die Antwort ist die Datei mit einem Content-Disposition-Header, der auf attachment; filename="003ZP1332-2022-3_WORD.docx" gesetzt ist.

2. Ansatz: Herunterladen aller abgeschlossenen Berichte​

Dieser Ansatz verwendet die reports getchanges API. Beim ersten Aufruf können Sie den Parameter changeToken weglassen.

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

Die Antwort liefert uns die Berichte (wie erwartet), enthält aber einen "NextChangeToken" und einen "NextLink", mit denen wir die nächsten 500 geänderten Berichte abrufen können.

{
    "result": {
        "results": [
         {
         "id": "4b2c2e24-52b6-4f3f-8efa-3fd7b15c3e0c",
         "reportState": 3, // erfolgreich generiert
         "error": null,
         "isDraft": false, // kein Berichtsentwurf
         "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, // nicht gelöscht
         "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, // Sie erhalten auch gelöschte Berichte
         "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
}

Um also die nächsten 500 geänderten Berichte zu erhalten, können Sie entweder nur den Wert "NextLink" verwenden oder die API mit "NextChangeToken" wie folgt aufrufen:

GET https://dev.iclportal.com/api/services/custom/externalReports/GetChanges?changeToken=AAAAAAAFpYA HTTP/1.1
Accept: application/json
Authorization: Bearer HwBUGEn1p9S5BJi6iM.....
Direkt auf die letzte Seite gelangen

Da es keine weiteren Änderungen mehr gibt, gibt das System einfach die letzte verfügbare Änderung zurück, was in der Regel genau der gleiche Änderungs-Token ist, den wir gerade in der Anfrage verwendet haben.

Sie können diesen Mechanismus jedoch nutzen, um direkt zur letzten Seite der geänderten Berichte zu gelangen, indem Sie den höchstmöglichsten Änderungs-Token __________8 verwenden. Dies ist praktisch, wenn Sie nur die Änderungen von jetzt abrufen wollen und nicht alle historischen Änderungen durchgehen wollen.

Dann, für jeden Bericht, der

  • nicht gelöscht ist (d.h. isDeleted ist false)
  • erfolgreich erstellt wurde (d.h. reportState ist 3)
  • und kein Entwurfsbericht ist (d.h. isDraft ist false) können Sie den Bericht über die reports get API unter Verwendung seiner id herunterladen.
GET https://dev.iclportal.com/api/reports/get/4b2c2e24-52b6-4f3f-8efa-3fd7b15c3e0c
Authorization: Bearer HwBUGEn1p9S5BJi6iM.....

Die Antwort ist die Datei mit einem Content-Disposition-Header, der auf attachment; filename="003ZP1332-2022-3_WORD.docx" gesetzt ist.