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

1. Abfrage von Aufgaben

Url: /getall HTTP-Methode: GET Beispiel:

``http 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:

```http
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.

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	Type	Required?	Description
externalId	string	required	Muss ein eindeutiger Bezeichner sein, der von der externen Anwendung bereitgestellt wird.
title	string	required	Der Titel der Aufgabe
teamName	string	erforderlich	Der Name des Teams, mit dem die Aufgabe verknüpft werden soll. Damit dies funktioniert, müssen die Teamnamen eindeutig sein.
workbookName	string	required	der Name der Arbeitsmappe, die zu dieser Aufgabe gehört. Damit dies funktioniert, müssen die Namen der Arbeitsmappen eindeutig sein.
assignedUserName	string	required	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.
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		Eine optionale Datumsangabe 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
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)
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 boolen Werte angegeben werden Beispiel: { "istrue" : true }

Bemerkungen:

• Alle Aufgaben, die über diese Schnittstelle hinzugefügt werden, 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 "Kategorie" im folgenden Beispiel)

POST https://dev.iclportal.com/api/services/custom/externaltask/Post HTTP/1.1
Authorization: Bearer ..the auth_token..

Wenn alles gut geht, wird der Server eine 200 OK Antwort zurückgeben, wie z.B.:

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

{"success":true,"error":null,"unAuthorizedRequest":false}

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, sendet er eine 200 OK-Antwort zusammen mit 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 200 OK
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}

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
Access-Control-Allow-Origin: http://localhost
Access-Control-Allow-Credentials: true
Authorization: Bearer ..the auth_token...

{"success":true,"result”: {"externalId":"<ID_PROVIDED_BY_EXTERNAL_APPLICATION>", “inspectionId”:”<some uuid>”,”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",state:”new”,"category":"severe_defects", “itemsToInspect”:[“building01”]}
,"error":null,"unAuthorizedRequest":false}

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 Status der Aufgabe. Dieser kann entweder sein: "Neu", "Zugewiesen", "Aktiv", "Geschlossen" oder "Abgebrochen" Beachten Sie jedoch, dass der Dienst derzeit nur die Erstellung von Aufgaben mit einem gültigen Benutzer erlaubt, sodass der Status "Neu" niemals zurückgegeben werden sollte. (Sobald für eine "Neue" Aufgabe ein Benutzer angegeben wird, geht sie in den Status "Zugewiesen" über).
inspectionId	string	Wenn ein Benutzer die Aufgabe tatsächlich ausführt, wird eine Inspektion erstellt, der alle gesammelten Daten (Antworten, Bilder, Berichte, ...) zugeordnet werden.

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. Siehe 3.1

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”]}

5. Löschen einer Aufgabe

Ermöglicht das Löschen aller Aufgaben, die noch darauf warten, ausgeführt zu werden. Sobald ein Benutzer mit der Ausführung einer bestimmten Aufgabe beginnt, kann diese nicht mehr gelöscht werden.

Url: /delete

HTTP-Methode: DELETE

Beispiel:

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

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

das deleteTaskRequest Objekt

Name	Type	Required?	Description
externalTaskIds	array	Required, min-length: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.

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.

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...

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

Das deleteTaskRequest Objekt

Name	Type	Required?	Description
externalTaskIds	array	Required, min-length: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.

7. Neustart einer Aufgabe

Wenn eine Aufgabe abgebrochen wurde, gibt es nur eine Möglichkeit, sie wieder zu aktivieren. Dies geschieht durch einen Neustart dieser Aufgabe. (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.

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: /neustart

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...

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

Das deleteTaskRequest Objekt:

Name	Type	Required?	Description
externalTaskIds	array	Required, min-length: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

Beispielhafte Anfrage und Antwort

Anfrage:

POST http://dev.iclportal.com/api/services/custom/externalTask/post HTTP/1.1
Host: dev.iclportal.com
Connection: keep-alive
Accept: application/json, text/plain, */*
Authorization: Bearer ..the auth_token...
Content-Type: application/json;charset=UTF-8
Content-Length: 256

{
  "externalId" : "20160201_EN_1223",
  "title" : "Inspection Report",
  "teamName" : "Vienna",
  "workbookName" : "EN-ContainerInspection",
  "assignedUserName" : "inspector_vienna",
  "description" : "",
  "startDate" : "",
  "dueDate" : ""
}

Antwort:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 204
Content-Type: application/json; charset=utf-8
Expires: -1
Server: Microsoft-IIS/8.0
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Set-Cookie: ARRAffinity=e5d47670de5ad1288df9014426822f51f791b2950adeeaad1f1233637a362b8e;Path=/;Domain=dev.iclportal.com
Date: Mon, 25 Jan 2016 11:23:53 GMT

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

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.

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.

{
    "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/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.