Aufgaben

In iCL können Sie immer dann, wenn Sie einen Benutzer darüber informieren müssen, dass er eine Inspektion/Prüfung/Tätigkeit durchführen muss, eine Aufgabe erstellen. Eine Aufgabe legt fest, welcher Benutzer (oder welches Team) zugewiesen wird, welche Arbeitsmappe zu verwenden ist und kann benutzerdefinierte Daten enthalten. Sollte eine Arbeitsmappe der Inspektion ein Feld mit dem gleichen Namen und einem geeigneten Typ enthalten, werden die benutzerdefinierten Daten verwendet, um es auszufüllen, sobald die Inspektion beginnt. Aufgaben sind also eine leistungsstarke Möglichkeit, die Aktivitäten Ihres Teams zu planen.

• Eine ausführliche Erläuterung von Aufgaben finden Sie in der Dokumentation.
• Eine erste Schritt-für-Schritt-Anleitung zur Verwendung der Aufgaben-API finden Sie hier

Um eine Aufgabe in iCL Portal zu erstellen, zu aktualisieren oder zu löschen, kann der folgende REST-Dienst verwendet werden. Endpunkt: /api/services/custom/externaltask

Zustände einer Aufgabe

Während ihres Lebenszyklus durchläuft eine Aufgabe verschiedene Zustände (siehe Lebenszyklus einer Aufgabe). Die Endpunkte /get und /getall / /getchanges geben den Zustand unterschiedlich zurück:

Zustand	state von /get	state von /getall und /getchanges
Neu (noch kein Benutzer zugewiesen)	"New"	0
Zugewiesen	"Assigned"	1
Aktiv (der Benutzer hat die Inspektion gestartet)	"Active"	2
Abgeschlossen	"Closed"	3
Abgebrochen	"Canceled"	4
Entfernt	"Removed"	5

1. Abfrage von Aufgaben

Url: /getall HTTP-Methode: GET Beispiel:

GET https://dev.iclportal.com/api/services/custom/externaltask/getall HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...

Beispiel 2: Abfrage aller Aufgaben, die seit einem bestimmten Zeitpunkt geändert wurden, sortiert nach ihrer Änderung und gibt nur die ersten 20 davon zurück:

GET https://dev.iclportal.com/api/services/custom/externaltask/getall?$filter=LastModificationTime+ge+datetime%272016-06-19T01:00:00%27&$inlinecount=allpages&$orderby=LastModificationTime+desc&$top=20 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...

Parameter: Dies ist ein ODATA 3.0 Endpunkt, mit dem Sie die Aufgaben im System abfragen können.

Die Antwort ist nicht in ein result-Objekt eingebettet. Sie enthält die Aufgaben in results, die Gesamtzahl der passenden Aufgaben in __count und, nur wenn es weitere Aufgaben gibt, einen Link auf die nächste Seite in __next. Eine Seite enthält höchstens 500 Aufgaben.

{
  "results": [
    {
      "id": "7cddb148-c113-4b23-9263-25cc479c88d8",
      "externalId": "<ID_PROVIDED_BY_EXTERNAL_APPLICATION>",
      "title": "New Task",
      "workbookId": "6f9df8f3-1f69-4258-99ad-c1144219bc7c",
      "workbookTemplateId": "0d5b2a7e-3c55-4f1b-9a8e-2f6f1c0f4b11",
      "workbookTitle": "physical_inspection",
      "workbookVersionCode": 1,
      "assignedUserId": 4,
      "assignedUserName": "Alexander Marek",
      "description": "Description",
      "startDate": "2015-12-28T23:00:00Z",
      "dueDate": "2015-12-29T23:00:00Z",
      "state": 1,
      "isSelfAssignable": false,
      "workAreaId": "58b6081a-1154-4ec2-a5a8-271a245eb4e0",
      "workAreaTitle": "team01",
      "isPublished": true,
      "actualStart": null,
      "actualEnd": null,
      "sentDate": null,
      "hasTask": true,
      "inspectionId": null,
      "lastModificationTime": "2016-06-19T09:42:18.93Z",
      "inspectedItems": null,
      "category": "severe_defects"
    }
  ],
  "__count": 1
}

• state wird als Zahl zurückgegeben (siehe Zustände einer Aufgabe).
• assignedUserName enthält den Anzeigenamen (Vor- und Nachname) des zugewiesenen Benutzers, während /get den Benutzernamen zurückgibt.
• Das Ergebnis enthält nur die Aufgaben, die Sie sehen dürfen: veröffentlichte Aufgaben mit der Berechtigung Tasks.View, zusätzlich unveröffentlichte Aufgaben mit Tasks.ViewUnpublished sowie die veröffentlichten Aufgaben, die Ihnen zugewiesen oder (mit Tasks.ViewAssigned) in Ihrem Team selbst zuweisbar sind.

Tipp

Sie können alle Attribute der zurückgegebenen json-Objekte verwenden, um eine Abfrage zu erstellen. Aufgrund der ODATA-Spezifikation müssen Sie diese in der Abfrage jedoch in Großbuchstaben schreiben. Da dies eine Konvention in JSON und der JavaScript-Welt ist, werden unsere Ergebnisse mit den Attributnamen in Kleinbuchstaben zurückgegeben.

Beispiel: Sie erhalten eine Aufgabe wie:

{"externalId":"<ID_PROVIDED_BY_EXTERNAL_APPLICATION>", "title": "Neue Aufgabe", ...}

Wie Sie sehen können, beginnt das Attribut "externalId" mit einem Kleinbuchstaben. Wenn Sie jedoch den ODATA-Endpunkt mit "externalId" abfragen, müssen Sie den ersten Buchstaben in Großbuchstaben schreiben:

/getall?$filter=ExternalId+eq+....

Hinweis

Dynamische Eigenschaften sind in dieser Schnittstelle nicht verfügbar.

2. Erstellen einer neuen Aufgabe

Url: /post HTTP-Methode: POST

Beispiel:

POST https://dev.iclportal.com/api/services/custom/externaltask/Post HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...

{"externalId":"<ID_PROVIDED_BY_EXTERNAL_APPLICATION>","title":"New Task","teamName":"team01","workbookName":"physical_inspection","assignedUserName":"alexander.marek","description":"Description","startDate":"2015-12-28T23:00:00.000Z","dueDate":"2015-12-29T23:00:00.000Z","category":"severe_defects", "itemsToInspect":["<ID_OR_EXTERNALID_OF_EXISTING_ITEM>"]}

Parameter: Die Parameter werden im Body der HTTP-Anfrage über ein JSON-Objekt bereitgestellt.

Das externalTask-Objekt hat die folgenden Felder:

Name	Typ	Erforderlich?	Beschreibung
externalId	string	erforderlich	Muss ein eindeutiger Bezeichner sein, der von der externen Anwendung bereitgestellt wird (max. 200 Zeichen).
title	string	erforderlich	Der Titel der Aufgabe (max. 200 Zeichen)
teamName	string		Der Name (oder die Id) des Teams, mit dem die Aufgabe verknüpft werden soll. Damit dies funktioniert, müssen die Teamnamen eindeutig sein. Fehlt der Wert, wird das Team anhand der Arbeitsmappe ermittelt: Gehört die Arbeitsmappe zu genau einem Team, wird dieses verwendet. Andernfalls werden die Teams berücksichtigt, in denen der zugewiesene Benutzer Inspektor ist, und schließlich das Standardteam des zugewiesenen Benutzers. Kann kein eindeutiges Team ermittelt werden, schlägt die Anfrage fehl.
workbookName	string	erforderlich	Der Name oder Titel der Arbeitsmappe, die zu dieser Aufgabe gehört. Damit dies funktioniert, müssen die Namen der Arbeitsmappen eindeutig sein. Die Arbeitsmappe muss dem Team zugeordnet sein.
assignedUserName	string	erforderlich, außer isSelfAssignable ist true	Der eindeutige Benutzername des Benutzers, der diese Aufgabe ausführen muss. (d.h. der Benutzername des Inspektors) Sie können auch die E-Mail-Adresse des Inspektors angeben. Der Benutzer muss Inspektor des Teams sein.
isSelfAssignable	boolean		Standard: false. Bei true benötigt die Aufgabe keinen zugewiesenen Benutzer: Jeder Inspektor des Teams kann sie starten.
isPublished	boolean		Standard: true. Bei false wird die Aufgabe unveröffentlicht erstellt und ist für den zugewiesenen Benutzer erst sichtbar, wenn sie veröffentlicht wird.
description	string		Eine optionale Beschreibung der Aufgabe.
startDate	string		Ein optionales Startdatum für die Aufgabe. Hinweis: Datumsangaben müssen als UTC und als gültige ISO 8601 Datumszeichenfolge angegeben werden. Format: jjjj-MM-ddTHH:mm:ss.fffZ Beispiel: 2015-12-29T23:00:00.000Z
dueDate	string		Ein optionales Fälligkeitsdatum für die Aufgabe. Darf nicht vor startDate liegen. Hinweis: Datumsangaben müssen als UTC und als gültige ISO 8601 Datumszeichenfolge angegeben werden. Format: jjjj-MM-ddTHH:mm:ss.fffZ Beispiel: 2015-12-29T23:00:00.000Z
itemsToInspect	string[]		Wenn eine Arbeitsmappe erstellt wird, um einen bestimmten Inhaltstyp (z.B. ein Gebäude) zu inspizieren, dann können Sie die Aufgabe angeben, welches Gebäude inspiziert werden muss. Geben Sie ein Array von Strings an, wobei jeder Wert entweder die externalid eines Inhaltselements oder seine interne contentitemid sein kann (die id, die Sie von der api/content/<contenttypename> api erhalten)
itemToInspect	string		Alternative zu itemsToInspect für genau ein Element. Geben Sie entweder itemToInspect oder itemsToInspect an, nicht beides.
jede weitere Eigenschaft	string/number/boolean		Wenn ein Feld keinem der zuvor definierten Namen entspricht, wird es als benutzerdefinierte Eigenschaft der Aufgabe betrachtet und in iCL Portal gespeichert (siehe Feld "category" im folgenden Beispiel). Hinweis: 1) Datumsangaben müssen als UTC und als gültige ISO 8601 Datumszeichenfolge angegeben werden. Format: yyyy-MM-ddTHH:mm:ss.fffZ Beispiel: 2015-12-29T23:00:00.000Z 2) Zahlen müssen als gültige JSON-Zahlen angegeben werden: Beispiel: { "numberfield":33.2 } 3) Booleans müssen als gültige JSON boolean Werte angegeben werden Beispiel: { "istrue" : true }

Bemerkungen:

• Sofern Sie isPublished nicht auf false setzen, werden alle Aufgaben, die über diese Schnittstelle hinzugefügt werden, automatisch veröffentlicht.
• Das json-Objekt kann jedes andere Feld enthalten, das von iCL Portal als benutzerdefinierte Eigenschaft der jeweiligen Aufgabe gespeichert wird. (siehe Feld "category" im obigen Beispiel)
• Eine Aufgabe mit derselben externalId darf noch nicht existieren. Verwenden Sie /put, um eine bestehende Aufgabe zu ändern.
• Erforderliche Berechtigung: Tasks.Create für das Team der Aufgabe.

Wenn alles gut geht, gibt der Server eine 200 OK Antwort mit der Id der neuen Aufgabe zurück:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8

{"result":{"id":"7cddb148-c113-4b23-9263-25cc479c88d8"},"targetUrl":null,"success":true,"error":null,"unAuthorizedRequest":false,"__abp":true}

Das Ergebnisobjekt

Name	Typ	Beschreibung
success	boolean	Sagt aus, ob die Anfrage erfolgreich war. Wenn "false" zurückgegeben wird, ist ein Fehler aufgetreten.
result	string/number/boolean/object	Enthält ein beliebiges Ergebnisobjekt, wenn der Dienst ein beliebiges Ergebnis zurückgibt.
error	object	Wenn ein Fehler aufgetreten ist, z.B. ein Validierungsfehler, zeigt das Erfolgsfeld "false" an und das Fehlerfeld enthält ein JSON-Objekt mit weiteren Details.
unAuthorizedRequest	Boolean	Gibt "true" zurück, wenn der Benutzer nicht genügend Berechtigungen hatte, um die Dienstmethode auszuführen.

Wenn die Aufgabe nicht gültig ist, antwortet der Server mit 400 Bad Request und einem Fehlerobjekt, das als JSON im Antwortkörper kodiert ist. In diesem Beispiel beschwert sich der Server, dass für die Aufgabe kein Titel angegeben wurde, obwohl dies ein Pflichtfeld ist:

HTTP/1.1 400 Bad Request
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1

{"success":false,"result":null,"error":{"code":0,"message":"Your request is not valid!","details":"The following errors were detected during validation.\r\n - 'Title' should not be empty.\r\n","validationErrors":[{"message":"'Title' should not be empty.","members":["title"]}]},"unAuthorizedRequest":false}

Andere Fehler, etwa eine Arbeitsmappe, ein Team oder ein Benutzer, die nicht gefunden werden, oder eine bereits existierende Aufgabe mit derselben externalId, werden mit HTTP-Status 500 und einem Fehlerobjekt mit einer Meldung zurückgegeben:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8

{"success":false,"result":null,"error":{"code":0,"message":"No workbook with the name or title 'EN-ContainerInspection' could be found","details":null,"validationErrors":null},"unAuthorizedRequest":false}

Fehlt Ihnen die erforderliche Berechtigung, antwortet der Server mit 403 Forbidden (401 Unauthorized, wenn das Access Token fehlt oder ungültig ist).

Das Fehlerobjekt

Name	Typ	Beschreibung
code	number	Für zukünftige Verwendung
message	string	Ein allgemeiner, vom Benutzer lesbarer Titel der Fehlermeldung
details	string	Eine allgemeine, vom Benutzer lesbare Fehlermeldung
validationErrors	array	Enthält validationError-Objekte für jedes ungültige Feld.

Das validationError-Objekt

Name	Typ	Beschreibung
code	number	Für zukünftige Verwendung
message	string	Eine vom Benutzer lesbare Nachricht, die erklärt, warum ein Feld nicht gültig war.
members	string	Eine Liste der Felder, zu denen diese Fehlermeldung gehört.

3. Lesen einer Aufgabe

Url: /get

HTTP-Methode: POST

Beispiel:

POST https://dev.iclportal.com/api/services/custom/externaltask/get HTTP/1.1
Accept: application/json, text/plain, */*
Authorization: Bearer ..the auth_token...

{"externalId":"<ID_PROVIDED_BY_EXTERNAL_APPLICATION>"}

Der Server antwortet mit einem 200 OK, das ein Ergebnisobjekt im Antwortkörper enthält:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"result":{"externalId":"<ID_PROVIDED_BY_EXTERNAL_APPLICATION>","title":"New Task","teamName":"team01","workbookName":"physical_inspection","workbookVersionCode":1,"workbookTemplateId":"0d5b2a7e-3c55-4f1b-9a8e-2f6f1c0f4b11","assignedUserName":"alexander.marek","description":"Description","startDate":"2015-12-28T23:00:00Z","dueDate":"2015-12-29T23:00:00Z","completedDate":null,"sentDate":null,"finalReportCount":null,"state":"Active","inspectionId":"<some uuid>","itemsToInspect":["building01"],"category":"severe_defects"},"targetUrl":null,"success":true,"error":null,"unAuthorizedRequest":false,"__abp":true}

Die zurückgegebenen Felder sind die gleichen, die beim Erstellen oder Aktualisieren einer Aufgabe gesendet werden, mit diesen Ausnahmen:

Name	Typ	Beschreibung
state	string	Der aktuelle Zustand der Aufgabe. Dieser kann sein: "New", "Assigned", "Active", "Closed", "Canceled" oder "Removed". Eine Aufgabe ist "New", solange sie keinen zugewiesenen Benutzer hat (z.B. eine selbst zuweisbare Aufgabe), und "Assigned", sobald ein Benutzer zugewiesen ist. Siehe Zustände einer Aufgabe.
inspectionId	string	Wenn ein Benutzer die Aufgabe tatsächlich ausführt, wird eine Inspektion erstellt, der alle gesammelten Daten (Antworten, Bilder, Berichte, ...) zugeordnet werden.
workbookVersionCode	number	Die Version der Arbeitsmappe, die von der Aufgabe verwendet wird.
workbookTemplateId	string	Die Id der Arbeitsmappen-Vorlage (für alle Versionen einer Arbeitsmappe gleich).
completedDate	string	Das Datum, an dem die Inspektion abgeschlossen wurde. null, solange sie nicht abgeschlossen ist.
sentDate	string	Das Datum, an dem die Inspektion gesendet wurde, d.h. abgeschlossen und alle ihre finalen Berichte erstellt wurden. null, solange sie nicht gesendet wurde.
finalReportCount	number	Die Anzahl der finalen (nicht als Entwurf markierten und nicht gelöschten) Berichte, die zum Zeitpunkt des Sendens der Inspektion vorhanden waren. Solange die Inspektion kein sentDate hat (also noch nicht gesendet wurde), ist der Wert null. Verwenden Sie ihn als Vollständigkeitsprüfung beim Abrufen der finalen Berichte einer gesendeten Inspektion.

assignedUserName enthält den Benutzernamen des zugewiesenen Benutzers.

Erforderliche Berechtigung: Tasks.View (Tasks.ViewUnpublished für unveröffentlichte Aufgaben) für das Team der Aufgabe. Existiert keine Aufgabe mit der angegebenen externalId, antwortet der Server mit HTTP-Status 500 und einem Fehlerobjekt.

4. Bearbeiten einer Aufgabe

Url: /put

HTTP-Methode: PUT

Die Bearbeitung einer Aufgabe funktioniert auf die gleiche Weise wie das Erstellen einer Aufgabe. Nur die HTTP-Methode und die URL unterscheiden sich. Die Aufgabe wird anhand ihrer externalId identifiziert.

Beachten Sie die folgenden Unterschiede:

• teamName ist erforderlich.
• Eine Aufgabe kann nur bearbeitet werden, solange ihr Zustand "New" oder "Assigned" ist. Andernfalls antwortet der Server mit einem Fehler.
• Die Anfrage ersetzt die Aufgabe: Felder, die Sie weglassen, werden zurückgesetzt. Beispielsweise wird eine fehlende description oder ein fehlendes dueDate geleert, fehlende benutzerdefinierte Eigenschaften und zu inspizierende Elemente werden entfernt und ein fehlendes isPublished wird auf true gesetzt. Senden Sie daher immer alle Felder der Aufgabe.
• Erforderliche Berechtigung: Tasks.Edit für das Team der Aufgabe.

Beispiel:

PUT https://dev.iclportal.com/api/services/custom/externaltask/Put HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/json, text/plain, */*
Accept-Encoding: gzip, deflate
Authorization: Bearer ..the auth_token...

{"externalId":"<ID_PROVIDED_BY_EXTERNAL_APPLICATION>","title":"New Task","teamName":"team01","workbookName":"physical_inspection","assignedUserName":"alexander.marek","description":"Description","startDate":"2015-12-28T23:00:00.000Z","dueDate":"2015-12-29T23:00:00.000Z","category":"severe_defects", "itemsToInspect":["building01"]}

Der Server antwortet mit einem 200 OK, das ein leeres Ergebnisobjekt ("result":{}) enthält.

5. Löschen einer Aufgabe

Ermöglicht das Löschen von Aufgaben im Zustand "New", "Assigned" oder "Canceled". Sobald ein Benutzer mit der Ausführung einer bestimmten Aufgabe beginnt ("Active"), kann diese nicht mehr gelöscht werden. Wird eine Aufgabe gelöscht, wird auch ihre Inspektion (falls vorhanden) gelöscht.

Url: /delete

HTTP-Methode: DELETE

Beispiel:

DELETE https://dev.iclportal.com/api/services/custom/externaltask/delete  HTTP/1.1
Accept: application/json, text/plain, */*
Authorization: Bearer ..the auth_token...

{"externalIds": ["<ID_PROVIDED_BY_EXTERNAL_APPLICATION>"] }

das deleteTaskRequest Objekt

Name	Typ	Erforderlich?	Beschreibung
externalIds	array	Erforderlich, min. Länge: 1	Enthält die externen IDs der Aufgaben, die gelöscht werden sollen.

Der Server antwortet mit einem 200 OK, das ein Ergebnisobjekt im Antwortkörper enthält. Es listet die externen IDs der gelöschten Aufgaben auf:

{"result":{"externalTaskIds":["<ID_PROVIDED_BY_EXTERNAL_APPLICATION>"]},"targetUrl":null,"success":true,"error":null,"unAuthorizedRequest":false,"__abp":true}

Erforderliche Berechtigung: Tasks.Delete für das Team der Aufgabe. Wird keine der Aufgaben gefunden (oder fehlt Ihnen die Berechtigung), antwortet der Server mit 403 Forbidden. Befindet sich eine der Aufgaben in einem Zustand, der das Löschen nicht erlaubt, antwortet der Server mit HTTP-Status 500 und es wird keine Aufgabe gelöscht.

6. Abbrechen einer Aufgabe

Wenn ein Benutzer bereits mit der Ausführung einer Aufgabe begonnen hat, geht diese in den Zustand "Aktiv" über und kann nicht mehr gelöscht werden. Stattdessen muss sie abgebrochen werden.

Nur Aufgaben im Zustand "Active" können abgebrochen werden. Eine Aufgabe, die noch "New" oder "Assigned" ist, kann stattdessen bearbeitet oder gelöscht werden.

Url: /cancel

HTTP-Methode: POST

Beispiel:

POST https://dev.iclportal.com/api/services/custom/externaltask/cancel HTTP/1.1
Accept: application/json, text/plain, */*
Authorization: Bearer ..the auth_token...

{"externalIds": ["<ID_PROVIDED_BY_EXTERNAL_APPLICATION>"] }

Das cancelTaskRequest Objekt

Name	Typ	Erforderlich?	Beschreibung
externalIds	array	Erforderlich, min. Länge: 1	Enthält die externen IDs der Aufgaben, die abgebrochen werden sollen.

Der Server antwortet mit einem 200 OK, das ein Ergebnisobjekt im Antwortkörper enthält. Es listet die externen IDs der abgebrochenen Aufgaben in externalTaskIds auf.

Erforderliche Berechtigung: Tasks.Edit für das Team der Aufgabe. Wird keine der Aufgaben gefunden (oder fehlt Ihnen die Berechtigung), antwortet der Server mit 403 Forbidden. Ist eine der Aufgaben nicht "Active", antwortet der Server mit HTTP-Status 500 und es wird keine Aufgabe abgebrochen.

7. Neustart einer Aufgabe

Wenn eine Aufgabe abgebrochen wurde, können Sie sie durch einen Neustart wieder aktivieren. (in iCL Portal nennen wir das "neu veröffentlichen")

Hinweis: Sie können nur eine "abgebrochene" Aufgabe neu starten, sonst gibt der Server einen Fehler zurück. Um bei einer abgebrochenen Aufgabe auch den zugewiesenen Benutzer zu ändern, verwenden Sie stattdessen /assign.

Sobald eine Aufgabe "neu gestartet" wurde, geht sie von "abgebrochen" in den Status "zugewiesen" über. In diesem Zustand kann die Aufgabe geändert und gelöscht werden.

Url: /restart

HTTP-Methode: POST

Beispiel:

POST https://dev.iclportal.com/api/services/custom/externaltask/restart HTTP/1.1
Accept: application/json, text/plain, */*
Authorization: Bearer ..the auth_token...

{"externalIds": ["<ID_PROVIDED_BY_EXTERNAL_APPLICATION>"] }

Das restartTaskRequest Objekt:

Name	Typ	Erforderlich?	Beschreibung
externalIds	array	Erforderlich, min. Länge: 1	Enthält die externen IDs der Aufgaben, die neu gestartet werden sollen.

Der Server antwortet mit einem 200 OK, das ein Ergebnisobjekt im Antwortkörper enthält

Erforderliche Berechtigung: Tasks.Publish für das Team der Aufgabe. Wird keine der Aufgaben gefunden (oder fehlt Ihnen die Berechtigung), antwortet der Server mit 403 Forbidden. Ist eine der Aufgaben nicht abgebrochen, antwortet der Server mit HTTP-Status 500 und es wird keine Aufgabe neu gestartet.

Beispielhafte Anfrage und Antwort

Anfrage:

POST https://dev.iclportal.com/api/services/custom/externalTask/restart HTTP/1.1
Accept: application/json, text/plain, */*
Authorization: Bearer ..the auth_token...
Content-Type: application/json;charset=UTF-8

{
  "externalIds" : ["20160201_EN_1223"]
}

Antwort:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1

{"result":{"externalTaskIds":["20160201_EN_1223"]},"targetUrl":null,"success":true,"error":null,"unAuthorizedRequest":false,"__abp":true}

8. Änderungen von Aufgaben abrufen

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

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

Stattdessen können Sie mit diesem Endpunkt eine Liste aller Aufgaben abrufen, die sich seit einem bestimmten Zeitstempel geändert haben.

Ein ausführlicheres Beispiel finden Sie im incremental changes walkthrough.

Lassen Sie den Parameter changeToken weg (oder geben Sie 0 an), um die erste Seite abzurufen. Erforderliche Berechtigung: Tasks.View.

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

Die Antwort liefert uns die Aufgaben (wie erwartet), enthält aber einen nextChangeToken und einen nextLink, mit denen wir die nächsten 500 geänderten Aufgaben/Inspektionen abrufen können. Zusätzlich zu den Feldern von /getall enthält jeder Eintrag isDeleted, reopenCount (wie oft die Inspektion wiedereröffnet wurde), lastReopenDate und finalReportCount.

{
    "result": {
        "results": [
            {
                "id": "5bb89fe4-25dd-4014-b00e-c3ed05c15213",
                "inspectionId": null,
                "externalId": "TSK___000001",
                "title": "Task 000000",
                "workbookId": "baf7b34d-825a-443b-bf5e-928ff83d9c2e",
                "workbookTemplateId": "4b7c2e0a-5d1f-4f7e-8f63-1a2b3c4d5e6f",
                "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,
                "finalReportCount": null,
                "hasTask": true,
                "lastModificationTime": "2022-10-21T13:16:23.583Z",
                "inspectedItems": null,
                "reopenCount": 0,
                "lastReopenDate": null,
                "isDeleted": false // <-- Sie erhalten auch gelöschte Aufgaben/Inspektionen!
            },
            ... 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
}

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.

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.

9. Wiedereröffnen einer Aufgabe

Sobald eine Aufgabe abgeschlossen ist, kann der Benutzer die Inspektion mit all ihren Daten nicht mehr bearbeiten. Das Wiedereröffnen setzt den Zustand der Aufgabe zurück auf "Active", sodass der Benutzer den Inhalt der Inspektion wieder ändern kann.

Hinweis: Sie können nur abgeschlossene Aufgaben ("Closed") wiedereröffnen, sonst gibt der Server einen Fehler zurück. Beim Wiedereröffnen werden das Abschluss- und das Sendedatum geleert, die Berichte der Inspektion gelöscht (sie werden beim nächsten Abschließen der Inspektion erneut erstellt) und reopenCount erhöht.

Url: /reopen

HTTP-Methode: POST

Beispiel:

POST https://dev.iclportal.com/api/services/custom/externalTask/Reopen HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer ..the auth_token...

{"externalIds": ["<ID_PROVIDED_BY_EXTERNAL_APPLICATION>"] }

Das reopenTaskRequest Objekt

Name	Typ	Erforderlich?	Beschreibung
externalIds	array	Erforderlich, min. Länge: 1	Enthält die externen IDs der Aufgaben, die wiedereröffnet werden sollen.
skipReopenCountFieldEvaluation	boolean		Standard: false. Standardmäßig werden beim Wiedereröffnen die Felder der Arbeitsmappe, die die Wiedereröffnungen zählen, neu ausgewertet. Setzen Sie den Wert auf true, um diese Auswertung zu überspringen.

Der Server antwortet mit einem 200 OK, das ein Ergebnisobjekt enthält. Es listet die externen IDs der wiedereröffneten Aufgaben in externalTaskIds auf.

Erforderliche Berechtigung: Tasks.Reopen für das Team der Aufgabe. Wird keine der Aufgaben gefunden (oder fehlt Ihnen die Berechtigung), antwortet der Server mit 403 Forbidden. Ist eine der Aufgaben nicht abgeschlossen, antwortet der Server mit HTTP-Status 500 und es wird keine Aufgabe wiedereröffnet.

10. Zuweisen einer Aufgabe

Ermöglicht es, eine Aufgabe einem anderen Benutzer zuzuweisen oder sie in ein anderes Team zu verschieben. Anders als /put funktioniert dies auch für Aufgaben im Zustand "Active" und "Canceled". Das ist zum Beispiel nützlich, um eine aktive Aufgabe an einen anderen Inspektor zu delegieren.

Url: /assign

HTTP-Methode: POST

Beispiel:

POST https://dev.iclportal.com/api/services/custom/externalTask/Assign HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer ..the auth_token...

{"externalId": "<ID_PROVIDED_BY_EXTERNAL_APPLICATION>", "assignedUserName": "alexander.marek"}

Das assignTaskRequest Objekt

Name	Typ	Erforderlich?	Beschreibung
externalId	string	erforderlich	Die externe ID der Aufgabe.
assignedUserName	string	erforderlich, außer isSelfAssignable ist angegeben	Der Benutzername oder die E-Mail-Adresse des neuen zugewiesenen Benutzers. Der Benutzer muss Inspektor des (neuen) Teams sein.
isSelfAssignable	boolean	erforderlich, außer assignedUserName ist angegeben	Setzen Sie den Wert auf true, um die Aufgabe selbst zuweisbar zu machen, sodass jeder Inspektor des Teams sie starten kann. Geben Sie dabei nicht gleichzeitig assignedUserName an, wird der aktuell zugewiesene Benutzer entfernt (nicht möglich, sobald für die Aufgabe eine Inspektion gestartet wurde, z.B. bei Aufgaben im Zustand "Active").
teamName	string		Der Name des Teams, in das die Aufgabe verschoben werden soll. Die Arbeitsmappe der Aufgabe muss diesem Team zugeordnet sein. Fehlt der Wert, bleibt die Aufgabe in ihrem Team.

Bemerkungen:

• War die Aufgabe "Canceled", wird ihr Zustand zurück auf "Assigned" gesetzt (bzw. "New", wenn sie keinen zugewiesenen Benutzer hat). Der Zustand einer Aufgabe im Zustand "Active" ändert sich nicht.
• Eine veröffentlichte Aufgabe muss entweder einen zugewiesenen Benutzer haben oder selbst zuweisbar sein.
• Erforderliche Berechtigung: Tasks.Edit für das Team der Aufgabe. Wird die Aufgabe nicht gefunden (oder fehlt Ihnen die Berechtigung), antwortet der Server mit 403 Forbidden. Andere Fehler (z.B. eine abgeschlossene Aufgabe oder ein unbekannter Benutzer) werden mit HTTP-Status 500 zurückgegeben.

Der Server antwortet mit einem 200 OK, das die externe ID der Aufgabe enthält:

{"result":{"externalTaskId":"<ID_PROVIDED_BY_EXTERNAL_APPLICATION>"},"targetUrl":null,"success":true,"error":null,"unAuthorizedRequest":false,"__abp":true}

11. Veröffentlichen einer Aufgabe

Aufgaben, die mit isPublished gleich false erstellt wurden, sind für den zugewiesenen Benutzer nicht sichtbar. Durch das Veröffentlichen werden sie sichtbar.

Url: /publish

HTTP-Methode: POST

Beispiel:

POST https://dev.iclportal.com/api/services/custom/externalTask/Publish HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer ..the auth_token...

{"externalIds": ["<ID_PROVIDED_BY_EXTERNAL_APPLICATION>"] }

Das publishTaskRequest Objekt

Name	Typ	Erforderlich?	Beschreibung
externalIds	array	Erforderlich, min. Länge: 1	Enthält die externen IDs der Aufgaben, die veröffentlicht werden sollen.

Nur unveröffentlichte Aufgaben im Zustand "New" oder "Assigned" können veröffentlicht werden. Bereits veröffentlichte Aufgaben werden ignoriert. Der Server antwortet mit einem 200 OK, das ein Ergebnisobjekt enthält. Es listet die externen IDs der veröffentlichten Aufgaben in externalTaskIds auf.

Erforderliche Berechtigung: Tasks.Publish für das Team der Aufgabe. Wird keine der Aufgaben gefunden (oder fehlt Ihnen die Berechtigung), antwortet der Server mit 403 Forbidden. Ist eine der unveröffentlichten Aufgaben nicht "New" oder "Assigned", antwortet der Server mit HTTP-Status 500 und es wird keine Aufgabe veröffentlicht.

12. Veröffentlichung einer Aufgabe zurücknehmen

Wird die Veröffentlichung von Aufgaben zurückgenommen, sind sie für die zugewiesenen Benutzer nicht mehr sichtbar.

Url: /unpublish

HTTP-Methode: POST

Beispiel:

POST https://dev.iclportal.com/api/services/custom/externalTask/UnPublish HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer ..the auth_token...

{"externalIds": ["<ID_PROVIDED_BY_EXTERNAL_APPLICATION>"] }

Das unpublishTaskRequest Objekt

Name	Typ	Erforderlich?	Beschreibung
externalIds	array	Erforderlich, min. Länge: 1	Enthält die externen IDs der Aufgaben, deren Veröffentlichung zurückgenommen werden soll.

Nur veröffentlichte Aufgaben im Zustand "New" oder "Assigned" können zurückgenommen werden. Bereits unveröffentlichte Aufgaben werden ignoriert. Der Server antwortet mit einem 200 OK, das ein Ergebnisobjekt enthält. Es listet die externen IDs der betroffenen Aufgaben in externalTaskIds auf.

Erforderliche Berechtigung: Tasks.Publish für das Team der Aufgabe. Wird keine der Aufgaben gefunden (oder fehlt Ihnen die Berechtigung), antwortet der Server mit 403 Forbidden. Ist eine der veröffentlichten Aufgaben nicht "New" oder "Assigned", antwortet der Server mit HTTP-Status 500 und die Veröffentlichung keiner Aufgabe wird zurückgenommen.

13. Mehrere Aufgaben auf einmal hinzufügen/aktualisieren

Ermöglicht es, mehrere Aufgaben mit einer einzigen Anfrage hinzuzufügen oder zu aktualisieren. Die Aufgaben werden anhand ihrer externalId identifiziert: Existiert eine Aufgabe mit dieser externalId, wird sie aktualisiert (wie bei /put), andernfalls wird sie erstellt (wie bei /post).

Der gesamte Batch wird in einer einzigen Transaktion ausgeführt. Hat eine der Aufgaben einen Fehler, wird keine der Aufgaben hinzugefügt oder aktualisiert.

Url: /postbatch

HTTP-Methode: POST

Beispiel:

POST https://dev.iclportal.com/api/services/custom/externalTask/PostBatch HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer ..the auth_token...

[
  {"externalId":"TASK-001","title":"Inspect building 1","teamName":"team01","workbookName":"physical_inspection","assignedUserName":"alexander.marek"},
  {"externalId":"TASK-002","title":"Inspect building 2","teamName":"team01","workbookName":"physical_inspection","isSelfAssignable":true}
]

Der Body der Anfrage ist ein Array von Aufgaben-Objekten mit denselben Feldern wie bei /post. teamName ist jedoch erforderlich. Eine Aufgabe kann nur aktualisiert werden, solange ihr Zustand "New" oder "Assigned" ist, und wie bei /put wird die Aufgabe dabei ersetzt.

Wurden alle Aufgaben hinzugefügt oder aktualisiert, antwortet der Server mit 200 OK und listet die Aufgaben in Succeeded auf:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"Errored":[],"Succeeded":[{"ExternalId":"TASK-001","Id":"7cddb148-c113-4b23-9263-25cc479c88d8"},{"ExternalId":"TASK-002","Id":"0b7e6a3c-2d5f-4c1e-9a8b-3f4e5d6c7b8a"}]}

Hat eine Aufgabe einen Fehler, antwortet der Server mit 400 Bad Request und listet die fehlgeschlagenen Aufgaben zusammen mit der Fehlermeldung in Errored auf. Da keine Aufgabe gespeichert wurde, ist Succeeded leer. Zum Beispiel, wenn die zweite Aufgabe auf das Team team02 verweist, das nicht existiert:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{"Errored":[{"ExternalId":"TASK-002","Error":"The team 'team02' does not exist."}],"Succeeded":[]}

Hinweis

Anders als bei den anderen Endpunkten dieser API ist die Antwort dieses Endpunkts nicht in ein result-Objekt eingebettet und ihre Attributnamen beginnen mit einem Großbuchstaben.

Erforderliche Berechtigungen: Tasks.Create (neue Aufgaben) und Tasks.Edit (bestehende Aufgaben) für das Team der Aufgabe.

14. Mehrere Aufgaben auf einmal hinzufügen/aktualisieren und Fehler ignorieren

Funktioniert wie /postbatch, aber wenn eine oder mehrere Aufgaben einen Fehler haben, werden die gültigen Aufgaben trotzdem hinzugefügt oder aktualisiert.

Dieser Endpunkt ist für Integrationsszenarien mit Werkzeugen wie SSIS oder Azure Data Factory gedacht: Sie können zum Beispiel die Fehler der fehlgeschlagenen Aufgaben per E-Mail an den Benutzer im Quellsystem senden, damit er sie beheben kann.

Url: /postbatchforce

HTTP-Methode: POST

Beispiel:

POST https://dev.iclportal.com/api/services/custom/externalTask/PostBatchForce HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer ..the auth_token...

[
  {"externalId":"TASK-001","title":"Inspect building 1","teamName":"team01","workbookName":"physical_inspection","assignedUserName":"alexander.marek"},
  {"externalId":"TASK-002","title":"Inspect building 2","teamName":"team02","workbookName":"physical_inspection","isSelfAssignable":true}
]

Wurden alle Aufgaben hinzugefügt oder aktualisiert, antwortet der Server mit 200 OK und listet die Aufgaben in Succeeded auf. Hat eine Aufgabe einen Fehler, antwortet der Server mit 400 Bad Request. Succeeded listet die gespeicherten Aufgaben auf, Errored die fehlgeschlagenen:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{"Errored":[{"ExternalId":"TASK-002","Error":"The team 'team02' does not exist."}],"Succeeded":[{"ExternalId":"TASK-001","Id":"7cddb148-c113-4b23-9263-25cc479c88d8"}]}

Erforderliche Berechtigungen: Tasks.Create (neue Aufgaben) und Tasks.Edit (bestehende Aufgaben) für das Team der Aufgabe.