Zum Hauptinhalt springen

1. Einfacher Einstieg

Für das Walkthrough stellen wir die folgende Arbeitsmappe zur Verfügung: 💾 building masterdata v1. Es handelt sich um ein fiktives Beispiel einer Arbeitsmappe, die zur Erfassung einiger Metadaten über ein Gebäude verwendet wird.

Beachten Sie, dass für alle Felder die Option assignable from task aktiviert ist, was es uns ermöglicht, Werte für diese Felder über Aufgaben-Metadaten bereitzustellen

Visual Studio Code REST API verwenden

Um das Walkthrough zu erleichtern, empfehlen wir die Verwendung von Visual Studio Code mit dem REST Client Plugin.

Laden Sie dann 💾 diese .http-Datei herunter und folgen Sie ihr

Zur Vorbereitung des Walkthroughs haben wir

  • ein Team Tasks Walkthrough erstellt und die Arbeitsmappe hochgeladen
  • einen Benutzer "gadget" erstellt und ihn der Gruppe inspectors des Teams hinzugefügt
  • einen Dienstbenutzer erstellt, um sich bei der API zu authentifizieren

1. Authentifizierung mit dem iCL Portal​

Da wir uns mit iCL Portal integrieren, werden wir ein Dienstkonto und den OAuth 2.0 Client Credentials Flow zur Authentifizierung verwenden. Bitte lesen Sie hier, wie man Client Credentials erhält.

POST https://dev.iclportal.com/token HTTP/1.1
Host: dev.iclportal.com

grant_type=client_credentials&client_id=fd52e53d-9b5f-405c-8084-052c8dfe08ac&client_secret=cjfdRtrCHKYaLALOvHV/JFhSpId/gtksoSLw1XPkkAo=

Damit erhalten wir unser access_token, um zukünftige Anfragen zu authentifizieren.

2. Eine Aufgabe erstellen​

Nun können wir eine Aufgabe erstellen, um die Überprüfung mit der Arbeitsmappe "building masterdata" durchzuführen.

Die Ausführung der folgenden Abfrage über den Query Tasks Endpoint zeigt, dass es noch keine Aufgabe gibt, indem alle Aufgaben des Teams "Task Walkthrough" abgefragt werden.

GET https://dev.iclportal.com/api/services/custom/externaltask/getall?$filter=WorkAreaTitle+eq+%27Task+Walkthrough%27
Authorization: asdfBASDF...

Dies ergibt ein leeres JSON-Array

HTTP/1.1 200 OK
Cache-Control: no-store, must-revalidate, no-cache, max-age=0
Content-Length: 26
Content-Type: application/json; charset=utf-8

{
  "results": [],
  "__count": 0
}

Jetzt können wir über den tasks POST endpoint eine Aufgabe erstellen, um die Prüfung anhand der Arbeitsmappe "building masterdata" durchzuführen.

POST https://dev.iclportal.com/api/services/custom/externaltask/Post
Authorization: asdfBASDF...

{
  "externalId": "2023-OQ-HQ",
  "title": "Inspect OQ-HQ",
  "teamName": "Task Walkthrough",
  "workbookName": "Building master data",
  "isSelfAssignable": false,
  "assignedUserName":"gadget",
  "description": "Some additional information displayed to the user when opening the task",
  "isPublished": false,
  "startDate": "2023-04-05T09:30:44.376Z",
  "dueDate": "2023-04-06T09:30:44.376Z" ,
  "address":"Landstraßer Hauptstraße 101, 1030 Vienna",
  "construction": "1983-02-06T00:00:00.000Z",
  "building_type":"office_building,shopping_centre",
  "age":10
}

Neben den Pflichtfeldern können Sie zusätzliche Werte angeben, die zum Ausfüllen der Felder in der Arbeitsmappe verwendet werden. In diesem Fall haben wir

  • etwas Text (Adresse),
  • ein Datum Errichtung, das gemäß ISO8601 formatiert werden muss
  • eine Zahl Alter
  • und für die Kontrollkästchen eine durch Komma getrennte Liste von Werten (Gebäude_Typ)

Weitere Informationen finden Sie in der Dokumentation des tasks POST endpoint

Wenn Sie alle erforderlichen Informationen angegeben haben, wird der Server mit der Identität der Aufgabe antworten:

HTTP/1.1 200 OK

{
  "result": {
    "id": "7cddb148-c113-4b23-9263-25cc479c88d8"
  },
  "targetUrl": null,
  "success": true,
  "error": null,
  "unAuthorizedRequest": false,
  "__abp": true
}
Verwenden Sie die externe ID zur Identifizierung von Aufgaben

Obwohl Sie nun diese interne oder iCL-Portal-spezifische Identität der Aufgabe in Ihrem System speichern könnten, um sie später zu identifizieren, empfehlen wir, die externeId zu verwenden, die Sie beim Erstellen der Aufgabe angegeben haben. Dies kann eine beliebige Zeichenkette sein, die aber für jede Aufgabe eindeutig sein muss.

Führen Sie nun den ersten Befehl erneut aus, um zu sehen, dass die Aufgabe erstellt wurde:

Führen Sie die folgende Abfrage aus:

GET https://dev.iclportal.com/api/services/custom/externaltask/getall?$filter=WorkAreaTitle+eq+%27Task+Walkthrough%27
Authorization: asdfBASDF...

gibt jetzt zurück

{
  "results": [
    {
      "id": "7cddb148-c113-4b23-9263-25cc479c88d8",
      "externalId": "2023-OQ-HQ",
      "title": "Inspect OQ-HQ",
      "workbookId": "6f9df8f3-1f69-4258-99ad-c1144219bc7c",
      "workbookTitle": "Building master data",
      "workbookVersionCode": 1,
      "assignedUserId": 4,
      "assignedUserName": "Antoine Gadget",
      "description": "Some additional information displayed to the user when opening the task",
      "startDate": "2023-04-05T09:30:44.377Z",
      "dueDate": "2023-04-06T09:30:44.377Z",
      "state": 1, // 1... zugewiesen
      "isSelfAssignable": false,
      "workAreaId": "58b6081a-1154-4ec2-a5a8-271a245eb4e0",
      "workAreaTitle": "Task Walkthrough",
      "isPublished": true,
      "actualStart": null, // sobald der Benutzer die Aufgabe startet, wird dies eingestellt
      "actualEnd": null, // sobald der Benutzer die Aufgabe erledigt hat, wird dies eingestellt
      "sentDate": null, // Sobald der Vorgang abgeschlossen ist und alle erforderlichen Berichte erstellt wurden, wird dies eingestellt.
      "hasTask": true, // Dies zeigt an, dass es eine Aufgabe für diese Inspektion gibt (die json-Datei repräsentiert beides: die Prüfung und die Aufgabe)
      "inspectionId": null, // sobald der Benutzer die Aufgabe startet, wird eine Inspektion erstellt und hier eingestellt
      "lastModificationTime": "2023-04-03T09:42:18.93Z",
      "inspectedItems": null
    }
  ],
  "__count": 1
}
Aufgabenzustände

Zustand 1 bedeutet zugewiesen. Lesen Sie hier, um die vollständige Liste der Aufgabenstatus zu sehen.

3. Abrufen von Aufgabeninformationen​

Sie können die externalId verwenden, die Sie bei der Erstellung der Aufgabe angegeben haben, um ihre aktuellen Daten mithilfe des tasks GET Endpoint abzurufen.

POST https://dev.iclportal.com/api/services/custom/externaltask/GET
Content-Type: application/json
Authorization: asdfBASDF

{
    "externalId": "2023-OQ-HQ"
}

Dies gibt die aktuellen Aufgabendetails zurück

{
  "result": {
    "externalId": "2023-OQ-HQ",
    "title": "Inspect OQ-HQ",
    "teamName": "Task Walkthrough",
    "workbookName": "Building master data",
    "assignedUserName": "gadget",
    "description": "Some additional information displayed to the user when opening the task",
    "startDate": "2023-04-05T09:30:44.377Z",
    "dueDate": "2023-04-06T09:30:44.377Z",
    "completedDate": null,
    "sentDate": null,
    "state": "Assigned",
    "inspectionId": null,
    "itemsToInspect": [],
    "address": "Landstraßer Hauptstraße 101, 1030 Vienna",
    "construction": "",
    "building_type": "office_building,shopping_centre",
    "age": 10
  },
  "targetUrl": null,
  "success": true,
  "error": null,
  "unAuthorizedRequest": false,
  "__abp": true
}

4. Abbrechen einer Aufgabe​

Nehmen wir nun an, dass eine Aufgabe nicht ausgeführt werden kann, da die angegebenen Daten unvollständig waren. Sie können die Aufgabe aktualisieren, solange sie nicht gestartet ist (d.h. neu oder zugeordnet) - andernfalls wird das iCL Portal mit einem Fehler reagieren. Was aber, wenn die Aufgabe bereits aktiv war?

In diesem Fall können Sie die Aufgabe abbrechen

POST https://dev.iclportal.com/api/services/custom/externaltask/Cancel
Content-Type: application/json
Authorization: asdfBASDF

{
    "externalIds": ["2023-OQ-HQ"]
}
Mehrere Aufgaben abbrechen

Sie können mehrere Aufgaben auf einmal abbrechen, indem Sie alle ihre externen IDs im Array angeben.

5. Eine Aufgabe zuweisen/neu zuweisen​

Sobald die Aufgabe abgebrochen wurde, können Sie sie nicht mehr aktualisieren. Weisen Sie die Aufgabe einem Benutzer zu (es kann auch derselbe Benutzer sein), um sie wieder auf zugewiesen zu setzen, wo sie schließlich bearbeitet werden kann.

POST https://dev.iclportal.com//api/services/custom/externaltask/Cancel
Content-Type: application/json
Authorization: asdfBASDF
{
  "externalId": "2023-OQ-HQ",
  "assignedUserName": "gadget"
}
Verwenden Sie "zuweisen", um aktive Aufgaben an einen anderen Benutzer zu delegieren

In manchen Fällen kann es notwendig sein, eine aktive Aufgabe an einen anderen Benutzer zu delegieren. Nehmen wir an, der Inspektor, der an einer Aufgabe gearbeitet hat, ist krank geworden. In diesem Fall können Sie den Endpunkt "Zuweisen" verwenden, um die Aufgabe einem anderen Benutzer neu zuzuweisen.

**Vergewissern Sie sich jedoch, dass der ursprüngliche Inspektor alle letzten Änderungen synchronisiert hat, damit der neue Inspektor die Aufgabe weiter bearbeiten kann.