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

Erstellen einer Aufgabe

Mit dieser HTTP-Schnittstelle kannst du eine Aufgabe erstellen.

  • URI: /task/tasks
  • Methode: POST


Du kannst eine Aufgabe folgendermaßen erstellen:

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 Erstellung 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 erstellt wird. Ist schon eine Aufgabe mit dem übergebenen Schlüssel vorhanden, wird keine neue Aufgabe erstellt und trotzdem der Code 201 übermittelt.

Wichtig

Die neu zu erstellende 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 einen Bearbeitungsdialog für die Aufgabe bereit. Nähere Information findest du im Abschnitt Bearbeitungsdialoge.
  • attachment: Diese URI wird als Kontextaktion 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 auf 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 erstellt oder war (unter Verwendung eines correlationKeys und ansonsten identischen Metadaten) bereits erstellt.
  • 400: Die Aufgabe ist ungültig.
  • 401: Der Benutzer ist nicht authentifiziert.
  • 403: Der Benutzer ist nicht berechtigt, die Aufgabe zu erstellen. Dies ist der Fall, wenn der Parameter sender verwendet wird und der Benutzer kein Systembenutzer ist.
  • 500: Serverfehler.

Validierung der Parameter

Vor der Erstellung 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 erstellt 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 Identity provider 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
}

Bearbeitungsdialoge

Beim Erstellen einer Aufgabe kannst du optional einen externen Bearbeitungsdialog hinzufügen.

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

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.

Beim Öffnen der Aufgabe in der Benutzeroberfläche wird der Bearbeitungsdialog angezeigt.

Das JSON kann dann zum Beispiel wie folgt aussehen:

   {
	...
	"_links" : {
		"form" : {
			"href" : "https://example.com/form"
		}
	}
}

Wichtig

Um zu überprüfen, dass der Bearbeitungsdialog 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 der Bearbeitungsdialog korrekt angezeigt. Der Bearbeitungsdialog muss daher auf HEAD-Anforderungen mit dem HTTP-Status-Code 200 antworten.

Hinweis

Bearbeitungsdialoge, die durch andere Server bereitgestellt werden, werden von der Task-App in einer IFrame-Sandbox mit den Attributen allow-scripts und allow-forms betrieben.


Aufgabenabschluss aus einem externen Dialog

Um eine Aufgabe direkt durch eine Aktion in einem Bearbeitungsdialog 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 des Dialogs keinerlei Logik oder Benutzerinteraktion mehr ausgeführt werden.

Kontextaktion "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">

Kontextaktion "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 deinem Bearbeitungsdialog die Datei dapi.js mindestens in der Version 2.13.1 mit.
Innerhalb des Bearbeitungsdialogs können Funktionen der Shell eingeschränkt verwendet werden. Die folgenden Funktionen werden erlaubt:

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

Kontextaktionen werden unterhalb der Kontextaktionen von der Task-App hinzugefügt.

Rückmeldung bei Aufgabenabschluss

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

Der übergebene URI wird dabei mit der HTTP POST-Methode 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 der Erstellung einer Aufgabe der Link changeCallback übergeben wurde, wird bei Änderung der Aufgabe eine Rückmeldung durchgeführt.

Der übergebene URI wird dabei mit der HTTP POST-Methode 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.

Erstellen einer Aufgabe (UI)

Verwende diese Funktion, um einen Dialog zum Erstellen einer Aufgabe durch eine andere App anzuzeigen. Der Dialog 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-Kontextaktion von der Task-App.

Wichtig

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

Entfernen einer Aufgabe

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

Übergabewerte

  • URI: Location einer zuvor erstellten 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 erstellten 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 Erstellen einer Aufgabe 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 dieselben Regeln wie für die Funktion Erstellen einer Aufgabe.

Berechtigungen

Der aufrufende Benutzer muss in der Rolle technischer Administrator sein.