Task-APP

Task-App

Einleitung

In diesem Thema findest du allgemeine Informationen zur task API, dem Funktionsumfang sowie zu den Kenntnissen, die hilfreich beim Programmieren von Funktionen und Anpassungen sind.


Über die Task-API

In dieser Dokumentation erfährst du, wie du die Programmierschnittstelle der Task-App für eigene Entwicklungen nutzen kannst.

Die Task-App stellt Funktionalitäten rund um das Thema Aufgaben bereit. JSON-Objekte, URLs und Abfrageparameter (Query) können jederzeit erweitert werden, ohne dass die API ihre Gültigkeit verliert. Es sind ausschließlich die in dieser Dokumentation beschriebenen Eigenschaften, Objekte und Parameter für die API-Programmierung freigegeben.

Weitere Informationen zur Funktionsweise und zur Konfiguration der Task-App findest du im Handbuch der Task-App.

Funktionsumfang der Task-App

Die Task-App behandelt die Fachlichkeiten rund um Aufgaben.

Dazu gehören das Anlegen von Aufgaben, die Bearbeitung von Aufgaben und die Integration von Formularen und Prozessen.

Technische Hintergrundinformationen

Die Task-App verwendet für die Bereitstellung öffentlicher API-Funktionen eine HTTP-Schnittstelle, die über die Basisadresse der HTTPGateway-App verfügbar ist.

Für die Verwendung dieser Funktionen ist in den meisten Fällen eine Authentifizierung mit der Identity provider-App notwendig.

Verwenden der API-Funktionen

In diesem Kapitel findest du Informationen dazu, wie du die einzelnen Funktionen der Task API anwendest.

Siehe auch:

Authentifizierung

Einige Schnittstellen der Task-App benötigen eine gültige Authentifizierung der Identity provider-App.

Wie eine solche Authentifizierung erlangt werden kann, kannst du der API-Dokumentation der Identity provider-App entnehmen.

Anlegen einer Aufgabe

Mit dieser HTTP-Schnittstelle kannst du eine Aufgabe anlegen.

  • URI: /task/tasks
  • Methode: POST


Du kannst eine Aufgabe folgendermaßen anlegen:

Request
   POST /task/tasks
Content-Type: application/hal+json

{
    "subject" : "MyTask",
	"description" : "My descriptive text",
    "assignees" : ["someUser","someOtherUser","someGroup"],
	"correlationKey" : "someUniqueKey",
	"priority" : 80,
	"reminderDate" : "2018-07-31T20:16:17.000+02:00",
	"dueDate" : "2018-08-15T20:16:17.000+02:00",
	"context" : {
		"key"  : "myContextKey",
		"type" : "bpm",
		"name" : "my context name"
	},
	"metadata" : [
		{
			"key" : "invoiceNumber",
 			"caption" : "Invoice Number",
    		"values" : ["INV123489"]
		}
	],
    "_links" : {
		"form" : { "href": "/myapp/form" },
		"callback" : { "href" : "/myapp/callback" },
		"attachment" : { "href" : "/myapp/example" },
		"process" : { "href" : "/process/example" },
        "changeCallback" : { "href" : "/myapp/changeCallback" }
	}
}

Hinweise zum Inhalt

subjectDer Betreff der Aufgabe.Pflichtmax. 255 Zeichen
descriptionEine textuelle Beschreibung der Aufgabe.Optionalmax. 500 Zeichen
assignees

Die Empfänger der Aufgabe. Hier können sowohl Einzelnutzer als auch Gruppen angegeben werden. Dies müssen IDs der Identity provider-App sein.
Bei der Anlage der Aufgabe werden diese automatisch aufgelöst. Es muss mindestens ein Empfänger angegeben werden.

Pflicht
correlationKey

Der Korrelationsschlüssel stellt sicher, dass zu diesem eindeutigen Schlüssel nur eine Aufgabe angelegt wird. Ist schon eine Aufgabe mit dem übergebenen Schlüssel vorhanden, wird keine neue Aufgabe angelegt und trotzdem der Code 201 übermittelt.

Wichtig

Die neu anzulegende Aufgabe muss zu einer bereits unter demselben correlationKey existierenden Aufgabe inhaltlich identisch sein.

Pflichtmax. 255 Zeichen
dueDate

Fälligkeitsdatum. Format nach RFC3339. Wird ein Datum ohne Zeitstempel übergeben, so gilt für das dueDate das übergebene Datum um 00:00:00 Uhr.

Alternativ kann auch eine Angabe in Millisekunden seit dem 1. Januar 1970 um 00:00:00 UTC erfolgen. Diese wird aber in einer zukünftigen Version nicht mehr unterstützt.

Optional
priorityPriorität zwischen 0 (niedrig) und 100 (hoch)Optional
reminderDateErinnerungsdatum. Format nach RFC3339. Wird ein Datum ohne Zeitstempel übergeben, so gilt für das reminderDate das übergebene Datum um 00:00:00 Uhr.

Alternativ kann auch eine Angabe in Millisekunden seit dem 1. Januar 1970 um 00:00:00 UTC erfolgen. Diese wird aber in einer zukünftigen Version nicht mehr unterstützt.

Optional
context

Der Kontext der Aufgabe. Besteht aus folgenden Eigenschaften:

  • key: Ein technischer Bezeichner für diesen Kontext.
  • type: Ein technischer Bezeichner für die Art des Kontexts.
  • name: Ein Anzeigename.
Optionalmax. 255 Zeichen
metadataMetadaten zur Aufgabe.Optional
sender

Überschreibt den Absender der Aufgabe mit einem anderen Benutzer. Bei diesem Parameter muss die identity provider ID des Benutzers angegeben werden.
Dieser Parameter darf nur verwendet werden, wenn der authentifizierte Benutzer die Benutzerrolle 'Technischer Administrator' hat.

Optional
_linksLinks zu der Aufgabe. Die URL muss jeweils unter dem Attribut "href" gespeichert werden.


Metadaten

  • key: Innerhalb dieser Metadaten eindeutiger Schlüssel aus ausschließlich alphanumerischen Zeichen (1-255 Zeichen).
  • caption: Beschriftung des Metadatums (1-255 Zeichen).
  • values: Wert des Metadatums. (0-255 Zeichen). Aktuell ist pro Metadatum nur ein Wert erlaubt.


Besondere Links

  • form: Diese URI stellt eine Bearbeitungsmaske für die Aufgabe bereit. Nähere Information findest du im Abschnitt Bearbeitungsmasken.
  • attachment: Diese URI wird als Kontext-Aktion in der Oberfläche angeboten, um dem Bearbeiter Zusatzinformationen anzuzeigen.
  • callback: Diese URI wird bei Abschluss einer Aufgabe mit der Methode POST aufgerufen.
  • process: Diese URI stellt den Prozess dar, durch den die Aufgabe initiiert wurde. Der Prozess wird in der Oberfläche als separate Perspektive auf die Aufgabe angezeigt.
  • changeCallback: Diese URI wird bei Änderungen an der Aufgabe mit der Methode POST aufgerufen.

Rückgabewerte

  • 201: Die Aufgabe wurde angelegt oder war (unter Verwendung eines correlationKeys und ansonsten identischen Metadaten) bereits angelegt.
  • 400: Die Aufgabe ist ungültig.
  • 401: Der Benutzer ist nicht authentifiziert.
  • 403: Der Benutzer ist nicht berechtigt, die Aufgabe anzulegen. Dies ist der Fall, wenn der Parameter sender verwendet wird und der Benutzer kein Systembenutzer ist.
  • 500: Serverfehler.

Validierung der Parameter

Vor der Anlage der Aufgabe findet eine Validierung des übergebenen JSON-Objektes statt. Folgende Überprüfungen werden durchgeführt:

  • Ist ein "subject" angegeben?
  • Ist das "subject" maximal 255 Zeichen lang?
  • Ist mindestens ein "assignee" angegeben?
  • Ist der unter "sender" eingetragene Benutzer im identity provider bekannt?
  • Ist ein "correlationKey" angegeben?
  • Ist der "correlationKey" maximal 255 Zeichen lang?
  • Sind "context-type" und "context-name" maximal 255 Zeichen lang?
  • Sind alle "assignees" im IdentityProvider entweder als Benutzer oder als Gruppe bekannt?
  • Falls ein "dueDate" angegeben ist: Liegt es in der Zukunft?
  • Falls eine "priority" angegeben ist: Ist diese eine Ganzzahl?
  • Falls ein "reminderDate" angegeben ist: Liegt es in der Zukunft?
  • Falls "_links" angegeben sind: Haben diese jeweils eine "href"?
  • Falls "metadata" angegeben sind: Entsprechen die Metadaten den Vorgaben (z.B.: Eindeutigkeit des Key, Länge und Gültigkeit der Parameter etc.)

Sollte die Validierung fehlschlagen, wird die Aufgabe nicht angelegt und es wird der HTTP-Status-Code 400 zurückgegeben. Der Response-Body enthält in diesem Fall ein JSON-Objekt, welches den Grund für das Fehlschlagen enthält. Dieses sieht beispielsweise wie folgt aus:

Response
   {
	"invalidTaskDefinition": false,
	"missingSubject": true,
	"invalidSubject": false,
    "invalidDescription": false,
	"missingAssignees": false,
    "invalidSender": false,
	"invalidAssigneeIDs": ["invalidAssignee", "otherInvalidAssignee"],
	"invalidDueDate": false,
	"invalidPriority" : false,
	"invalidReminderDate" : false,
	"invalidHrefs" : ["invalidHrefKey", "otherInvalidHrefKey"],
	"invalidCorrelationKey" : false,
	"missingCorrelationKey" : false,
	"invalidContext" : false,
	"invalidMetadata" : false
}

Hinweise zum Inhalt

  • invalidTaskDefinition: true, wenn kein JSON angegeben worden ist. Sonst false.
  • missingSubject: true, wenn kein "subject" angegeben worden ist. Sonst false.
  • invalidSubject: true, wenn das "subject" mehr als 255 Zeichen lang ist. Sonst false.
  • invalidDescription: true, wenn die Description mehr als 500 Zeichen lang ist. Sonst false.
  • missingAssignees: true, wenn nicht mindestens ein "assignee" angegeben worden ist. Sonst false.
  • invalidSender: true, wenn der unter "sender" angegebene Benutzer im identity provider nicht bekannt ist. Sonst false.
  • invalidAssigneeIds: Array, das die "assignees" enthält, welche im IdentityProvider unbekannt sind. Wenn alle bekannt sind, ist dieses Array leer.
  • invalidDueDate: true, falls ein "dueDate" angegeben worden ist, das in der Vergangenheit liegt. false, wenn keins angegeben worden ist oder es in der Zukunft liegt.
  • invalidPriority: true, falls eine "priority" angegeben wurde, die keiner Ganzzahl entspricht.
  • invalidReminderDate: true, falls ein "reminderDate" angegeben worden ist, das in der Vergangenheit liegt. false, wenn keins angegeben worden ist oder es in der Zukunft liegt.
  • invalidHrefs: Array, das die Keys der Links enthält, die ungültig sind.
  • invalidCorrelationKey: true, falls es zu dem angegebenen "correlationKey" bereits eine Aufgabe gibt, die sich jedoch inhaltlich von der neu anzulegenden Aufgabe unterscheidet oder der "correlationKey" mehr als 255 Zeichen lang ist.
  • missingCorrelationKey: true, wenn kein "correlationKey" angegeben wurde. Sonst false.
  • invalidContext: true, wenn der "context-type" oder "context-name" mehr als 255 Zeichen lang ist. Sonst false.
  • invalidMetadata: true, wenn die Angaben zu den Metadaten ungültig sind.


Für den Fall, dass das JSON formal ungültig ist, sieht das Response-Objekt folgendermaßen aus:

   {
	"invalidJson": true
}

Bearbeitungsmasken

Bei der Anlage einer Aufgabe kannst du optional eine externe Bearbeitungsmaske hinzufügen.

Dazu fügst du der JSON-Repräsentation eine Linkrelation mit dem Schlüssel form und der URI der Bearbeitungsmaske hinzu. Der URI kann wahlweise absolut oder relativ zur Basisadresse angegeben werden.

Beim Öffnen der Aufgabe in der Benutzeroberfläche wird nun die Bearbeitungsmaske angezeigt.

Das JSON kann dann zum Beispiel wie folgt aussehen:

JSON für eine Aufgabe mit Bearbeitungsmaske
   {
	...
	"_links" : {
		"form" : {
			"href" : "https://example.com/form"
		}
	}
}

Wichtig

Um zu überprüfen, dass die Bearbeitungsmaske erreichbar ist, führt die Task-App einen HTTP-HEAD-Anforderung auf den URI aus. Nur in dem Fall, dass hierbei der HTTP-Status-Code 200 zurückkommt, wird die Bearbeitungsmaske korrekt angezeigt. Die Bearbeitungsmaske muss daher auf HEAD-Anforderungen mit dem HTTP-Status-Code 200 antworten.

Wichtig

Bei der Erstellung des Formulars solltest du darauf achten, keine Navigation innerhalb des Formulars zu implementieren. Dies würde sonst bei der anschließenden Verwendung in der Task-App ggf. zu irreführenden Situationen führen.

Aufgabenabschluss aus einer externen Maske

Um eine Aufgabe direkt durch eine Aktion in einer Bearbeitungsmaske abzuschließen, kannst du folgenden JavaScript-Code verwenden:

   parent.postMessage("TaskApp.completeTask", location.origin);

Um auf einen möglicherweise nicht erfolgreichen Abschluss einer Aufgabe zu reagieren, kannst du folgenden JavaScript-Code einsetzen:

   window.addEventListener("message", function(event) {
	if (event.data === "TaskApp.taskCompleteFailure") {
		// Handle error case
	}
});

Wichtig

Nach dem erfolgreichen Abschluss einer Aufgabe in der Task-App darf innerhalb der Maske keinerlei Logik oder Benutzerinteraktion mehr ausgeführt werden.

Kontext-Aktion "Abschließen" ausblenden

Um den Abschluss einer Aufgabe durch die Kontextaktion in der Task-App zu verhindern, musst du dem Formular folgenden Meta-Tag hinzufügen:

   <meta name="TaskApp.disableCompleteAction">

Kontext-Aktion "Weiterleiten" ausblenden

Das Weiterleiten einer Aufgabe kannst du durch ein Meta-Tag im Formular verhindern:

   <meta name="TaskApp.disableForwardAction">

Verwendung von Shell-Funktionen

Wenn du Shell-Funktionen verwenden möchtest, liefere in deiner Bearbeitungsmaske die Datei dapi.js mindestens in der Version 2.13.1 mit.
Innerhalb der Bearbeitungsmaske können Funktionen der Shell eingeschränkt verwendet werden. Die folgenden Funktionen werden erlaubt:

  • navigate
  • setContextActions
  • publishTitle
  • addResourceEventListener
  • activateSingleResourceMode
  • deactivateSingleResourceMode
  • setResourceVisibilityChangedCallback

Kontext-Aktionen werden unterhalb der Kontext-Aktionen von der Task-App hinzugefügt.

Rückmeldung bei Aufgabenabschluss

Wenn bei Anlage einer Aufgabe der Link callback übergeben wurde, wird bei Abschluss der Aufgabe eine Rückmeldung durchgeführt.

Der übergebene URI wird dabei per HTTP POST aufgerufen. Liegt die Zieladresse hinter der Basisadresse, wird die Authentifizierung des Systembenutzers von der Task-App mit übertragen.

Im Body werden die folgenden Daten übertragen:

   {
	"event" : "COMPLETE",
    "timestamp" : "2022-05-13T20:16:17.000+02:00",
    "task": {
    	"subject": "MyTask",
    	"assignedUsers": ["someUser", "someOtherUser"],
   		"assignedGroups": ["someGroup"],
	    "editor": "someUser",
    	"correlationKey": "someUniqueKey",
	    "priority": 80,
    	"reminderDate": "2018-07-31T20:16:17.000+02:00",
	    "dueDate": "2018-08-31T20:16:17.000+02:00",
	    "context": {
	        "type": "Process",
	        "name": "contextName"
	    },
	    "metadata": [
	        {
	            "key": "invoiceNumber",
	            "caption": "Invoice Number",
	            "values": ["INV123489"]
	        }
	    ],
	    "_links": {
	        "form": {"href": "/myapp/form"},
	        "callback": {"href": "/myapp/callback"},
	        "attachment": {"href": "/myapp/example"},
    	    "process": {"href": "/process/example"},
	        "changeCallback": {"href": "/myapp/changeCallback"}
	    }
	}
}

Der Aufruf muss mit dem Statuscode 200 beantwortet werden. Ist dies nicht der Fall, wird der Aufruf zu einem späteren Zeitpunkt erneut versucht.

Rückmeldung bei Aufgabenänderung

Wenn bei Anlage einer Aufgabe der Link changeCallback übergeben wurde, wird bei Änderung der Aufgabe eine Rückmeldung durchgeführt.

Der übergebene URI wird dabei per HTTP POST aufgerufen. Liegt die Zieladresse hinter der Basisadresse, wird die Authentifizierung des Systembenutzers von der Task-App mit übertragen.

Im Body werden die folgenden Daten übertragen:

   {
	"event" : "FORWARD",
    "timestamp" : "2022-05-13T20:16:17.000+02:00",
    "task" : {
    	"subject": "MyTask",
        "description" : "My descriptive text",
    	"assignedUsers": ["someUser", "someOtherUser"],
   		"assignedGroups": ["someGroup"],
	    "editor": "someUser",
    	"correlationKey": "someUniqueKey",
	    "priority": 80,
    	"reminderDate": "2018-07-31T20:16:17.000+02:00",
	    "dueDate": "2019-06-10T20:16:17.000+02:00",
	    "context": {
	        "type": "Process",
	        "name": "contextName"
	    },
	    "metadata": [
	        {
	            "key": "invoiceNumber",
	            "caption": "Invoice Number",
	            "values": ["INV123489"]
	        }
	    ],
	    "_links": {
	        "form": {"href": "/myapp/form"},
	        "callback": {"href": "/myapp/callback"},
	        "attachment": {"href": "/myapp/example"},
    	    "process": {"href": "/process/example"},
	        "changeCallback": {"href": "/myapp/changeCallback"}
	    }
	}
}

Hinweise zum Inhalt

  • event: Beschreibung des Auslösers (FORWARD oder CHANGE).
  • timestamp: Zeitpunkt der Änderung.
  • task: Die Daten der Aufgabe nach Änderung.

Der Aufruf muss mit dem Statuscode 200 beantwortet werden. Ist dies nicht der Fall, wird der Aufruf zu einem späteren Zeitpunkt erneut versucht. Dieser erneute Versuch findet auch statt, wenn die Aufgabe bereits abgeschlossen wurde.

Abschließen einer Aufgabe

Über folgende HTTP-Schnittstelle wird eine Aufgabe abgeschlossen.

Übergabewerte

  • URI: /task/tasks/{id}/completionState. Der Platzhalter {id} ist die ID der Aufgabe.
  • Method: POST.
  • Content:

       {
       "complete" : true
    }
    
  • Content-Type: application/json


Rückgabewerte

  • 401: Der Benutzer hat nicht das Recht, diese Aufgabe abzuschließen.
  • 404: Die Aufgabe existiert nicht.
  • 500: Serverfehler.


Aufrufen vordefinierter Benutzeroberflächen

Die Task-App bietet anderen Apps die Möglichkeit, Funktionalitäten durch vordefinierte Benutzeroberflächen einzubinden.

Anlegen einer Aufgabe (UI)

Verwende diese Funktion, um eine Maske zum Anlegen einer Aufgabe durch eine andere App anzuzeigen. Die Maske wird bereits mit Werten vorgefüllt.

Request
   GET /task/tasks/create?subject=My%20Subject&context=My%20Context
Accept: text/html

Folgende Parameter können der URI optional hinzugefügt werden:

  • subject: Betreff der Aufgabe.
  • context: Kontext der Aufgabe.
  • dueDate: Fälligkeitsdatum. Format nach RFC3339. Alternativ kannst du auch eine Angabe in Millisekunden seit dem 1. Januar 1970 um 00:00:00 UTC verwenden. Dies wird in einer zukünftigen Version nicht mehr unterstützt.
  • reminderDate: Erinnerungsdatum. Format nach RFC3339. Alternativ kannst du auch eine Angabe in Millisekunden seit dem 1. Januar 1970 um 00:00:00 UTC verwenden. Dies wird in einer zukünftigen Version nicht mehr unterstützt.
  • links.form: URI des Formulars der Aufgabe.
  • links.attachment: URI zur Navigation in der Attachment-Kontext-Action von der Task-App.

Wichtig

Die Werte von links.form und links.attachment werden in der Oberfläche zum Anlegen der Aufgabe nicht angezeigt. Sie werden jedoch bei der Anlage der Aufgabe berücksichtigt und an die Task-App übergeben.

Entfernen einer Aufgabe

Du kannst diese API-Funktion verwenden, um zuvor angelegte Aufgaben wieder zu entfernen. Den URI findest du im Location-Header bei der Anlage der Aufgabe. Eine Aufgabe darf nur von dem Benutzer gelöscht werden, der diese auch angelegt hat. Ein Benutzer mit der Rolle "Technischer Administrator" darf jede Aufgabe löschen.

Übergabewerte

  • URI: Location einer zuvor angelegten Aufgabe.
  • Method: DELETE.

Verwende zum Löschen einer Aufgabe folgende Anforderung:

Request
   DELETE /task/...

Rückgabewerte

  • 200: Die Aufgabe wurde entfernt.
  • 401: Der Benutzer ist nicht authentifiziert.
  • 403: Der Benutzer hat nicht das Recht, die Aufgabe zu löschen.
  • 404: Die Aufgabe existiert nicht.
  • 500: Serverfehler.

Ändern einer Aufgabe

Mit dieser HTTP-Schnittstelle kannst du eine Aufgabe ändern.

Übergabewerte

  • URI: Location einer zuvor angelegten Aufgabe.
  • Methode: PATCH.

Du kannst eine Aufgabe folgendermaßen ändern:

Request
   PATCH /task/tasks/{id}
Content-Type: application/hal+json

{
    "subject" : "MyTask",
	"description" : "My descriptive text",
    "assignees" : ["someUser","someOtherUser","someGroup"],
	"priority" : 80,
	"reminderDate" : "2018-07-31T20:16:17.000+02:00",
	"dueDate" : "2018-07-31T20:16:17.000+02:00",
	"context" : {
		"type" : "Process",
		"name" : "contextName",
        "key" : "bpm"
	},
	"metadata" : [
        {
            "key" : "invoiceNumber",
            "caption" : "Invoice Number",
            "values" : ["INV123489"]
        }
    ],
    "_links" : {
		"form" : { "href": "/myapp/form" },
		"callback" : { "href" : "/myapp/callback" },
		"attachment" : { "href" : "/myapp/example" },
		"process" : { "href" : "/process/example" },
        "changeCallback" : { "href" : "/myapp/changeCallback" }
	}
}

Hinweise zum Inhalt:

Bei der Verwendung dieser Funktion kann ein Delta zur aktuellen Aufgabe angegeben werden.

Alle Felder im JSON-Inhalt sind optional. Es werden nur diejenigen Felder aktualisiert, die du auch verwendest. Achte aber darauf, bei den Feldern context und metadata immer alle Bestandteile anzugeben, sofern diese aktualisiert werden sollen.

Diese Felder können aktualisiert werden:

  • subject: Betreff
  • description: Beschreibungstext
  • assignees: Empfänger
  • priority: Priorität
  • dueDate: Fälligkeitsdatum
  • reminderDate: Erinnerungsdatum
  • context: Kontext
  • metadata: Metadaten
  • _links: Verknüpfungen


Informationen zur Validierung kannst du der Funktion Aufgabe anlegen entnehmen.

Wenn du eine Verknüpfung entfernen möchtest, kannst du den entsprechenden Schlüssel mit dem Wert null übergeben. Um z.B. die form-Verknüpfung zu entfernen, kannst du Folgendes übergeben:

   "_links" : {
	"form" : null
}


Rückgabewerte

  • 200: Die Aufgabe wurde aktualisiert.
  • 400: Ein oder mehrere Felder sind ungültig.
  • 401: Der Benutzer ist nicht authentifiziert.
  • 403: Der Benutzer ist nicht berechtigt, die Aufgabe zu ändern.
  • 500: Serverfehler.

Validierung der Parameter

Hier gelten die selben Regeln wie für die Funktion Anlegen einer Aufgabe.

Berechtigungen

Der aufrufende Benutzer muss in der Rolle technischer Administrator sein.