Zum Hauptinhalt springen

2. Abrufen geänderter Aufgaben

In vielen Fällen werden Sie die neuesten Informationen über iCL Portal-Aufgaben und Inspektionen in Ihrem Legacy-System abrufen wollen. Ein naiver Ansatz wäre, den task get endpoint zu verwenden, um nach Änderungen jeder Aufgabe zu suchen, die in Ihrem System noch nicht als erledigt oder abgebrochen markiert ist.

Das mag zwar technisch funktionieren, ist aber nicht gut skalierbar. Stellen Sie sich vor, wie viele unnötige Anfragen Sie an die iCL Portal API stellen müssten, um die neuesten Informationen über alle Ihre Aufgaben zu erhalten.

Stattdessen können Sie den task changes endpoint verwenden, um eine Liste aller Aufgaben zu erhalten, die seit einem bestimmten Zeitstempel geändert wurden.

Diese API ist speziell für inkrementelle Aktualisierungen gedacht. Dafür müssen Sie jedes Mal, wenn Sie sie nach Änderungen fragen, einen changeToken angeben.

1. Abrufen der ersten Seite von Aufgaben/Inspektionen​

Wenn Sie diesen Endpunkt zum ersten Mal aufrufen, haben Sie noch keinen changeToken. In diesem Fall erhalten Sie alle Aufgaben/Inspektionen seit Tag 1.

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

Um die Datenbank nicht zu überlasten, werden jedoch jeweils nur 500 Änderungen zurückgegeben. Um die nächsten 500 Änderungen zu erhalten, müssen Sie den "NextChangeToken" angeben, den Sie in der Antwort erhalten haben.

Die Antwort liefert uns die Aufgaben (wie erwartet), enthält aber einen "NextChangeToken" und "NextLink".

{
    "result": {
        "results": [
            {
                "id": "5bb89fe4-25dd-4014-b00e-c3ed05c15213",
                "inspectionId": null,
                "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": 1,
                "isSelfAssignable": true,
                "workAreaId": "6058f602-f55b-45b2-90b2-9081869f7774",
                "workAreaTitle": "test",
                "isPublished": true,
                "actualStart": null,
                "actualEnd": null,
                "sentDate": null,
                "hasTask": true,
                "lastModificationTime": "2022-10-21T13:16:23.583Z",
                "inspectedItems": null,
                "isDeleted": false // <-- Sie erhalten auch gelöschte Aufgaben/In
            },
            ... 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
}

```:::note Dieser Endpunkt gibt auch gelöschte Aufgaben zurück
Da dieser Endpunkt dazu dient, alle inkrementellen Änderungen zu erhalten, gibt er auch gelöschte Aufgaben zurück, sodass Sie diese entsprechend aus Ihrem System entfernen können.
:::


## 2. Abrufen der nächsten Seite mit geänderten Aufgaben/Inspektionen

Für die Abfrage der nächsten Änderungen wird einfach das Änderungs-Token verwendet, das in der vorherigen Antwort angegeben wurde.

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

... which gives us the next page.

{
  "result": {
    "results": [
      {
        "id": "71c8fc87-31da-4989-9662-3faf95ce893b",
        "inspectionId": null,
        "externalId": "TSK___000501",
        "title": "Task 000010",
        "workbookId": "baf7b34d-825a-443b-bf5e-928ff83d9c2e",
        "workbookTitle": "test iWorkbook",
        "workbookVersionCode": 52,
        "assignedUserId": 4,
        "assignedUserName": "antoine gadget",
        "description": null,
        "startDate": null,
        "dueDate": null,
        "state": 1,
        "isSelfAssignable": true,
        "workAreaId": "6058f602-f55b-45b2-90b2-9081869f7774",
        "workAreaTitle": "test",
        "isPublished": true,
        "actualStart": null,
        "actualEnd": null,
        "sentDate": null,
        "hasTask": true,
        "lastModificationTime": "2022-10-21T13:16:23.593Z",
        "inspectedItems": null,
        "isDeleted": false // <-- Sie erhalten auch gelöschte Aufgaben/Inspektionen!
      },
      {
        "id": "fcb40e9c-1ee2-4c94-af49-7978e0f23214",
        "inspectionId": null,
        "externalId": "TSK___000502",
        "title": "Task 000011",
        "workbookId": "baf7b34d-825a-443b-bf5e-928ff83d9c2e",
        "workbookTitle": "test iWorkbook",
        "workbookVersionCode": 52,
        "assignedUserId": 4,
        "assignedUserName": "antoine gadget",
        "description": null,
        "startDate": null,
        "dueDate": null,
        "state": 1,
        "isSelfAssignable": true,
        "workAreaId": "6058f602-f55b-45b2-90b2-9081869f7774",
        "workAreaTitle": "test",
        "isPublished": true,
        "actualStart": null,
        "actualEnd": null,
        "sentDate": null,
        "hasTask": true,
        "lastModificationTime": "2022-10-21T13:16:23.593Z",
        "inspectedItems": null,
        "isDeleted": false // <-- Sie erhalten auch gelöschte Aufgaben/Inspektionen!
      }
    ],
    "nextChangeToken": "AAAAAAAFpYg",
    "nextLink": "https://dev.iclportal.com/api/services/custom/externalTask/GetChanges?changeToken=AAAAAAAFpYg"
  },
  "targetUrl": null,
  "success": true,
  "error": null,
  "unAuthorizedRequest": false,
  "__abp": true
}

Dieses Mal gibt es nur 2 Ergebnisse - also nicht die volle Seitengröße von 500. Das deutet bereits darauf hin, dass dies die letzte Seite ist (d.h. es gibt keine weiteren Änderungen)

3. Erkennung der letzten Seite (keine weiteren geänderten Inspektionen/Aufgaben)​

Wir können jedoch immer noch eine Abfrage mit dem letzten changeToken AAAAAAAFpYg durchführen

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

... was uns ein leeres Ergebnisfeld in der Antwort liefern wird

{
  "result": {
    "results": [],
    "nextChangeToken": "AAAAAAAFpYg",
    "nextLink": "https://dev.iclportal.com/api/services/custom/externalTask/GetChanges?changeToken=AAAAAAAFpYg"
  },
  "targetUrl": null,
  "success": true,
  "error": null,
  "unAuthorizedRequest": false,
  "__abp": true
}
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 jedoch diesen Mechanismus nutzen, um direkt zur letzten Seite der geänderten Inspektionen/Aufgaben zu gelangen, indem Sie den höchstmöglichen Änderungs-Token __________8 verwenden. Dies ist praktisch, wenn Sie nur die Änderungen von jetzt abrufen wollen und nicht alle historischen Änderungen durchgehen wollen.