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.

 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 IdentityProvider-App notwendig.

 Verwenden der API-Funktionen

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

Siehe auch:

• Erstellen einer Aufgabe
• Erledigen einer Aufgabe
• Aufrufen vordefinierter Benutzeroberflächen
• Löschen einer Aufgabe
• Ändern einer Aufgabe
• Auslesen der Anzahl der Aufgaben
• Anzeigen der Aufgaben aller Verantwortungsregeln eines Benutzers
• Bearbeiten von Kontextregeln

Hinweis

Für alle Funktionen gilt, wenn an einer HTTP-Schnittstelle ein formal ungültiges JSON-Objekt übergeben wird, wird der HTTP-Status-Code 400 mit folgendem Response-Objekt zurückgegeben:

{
    "invalidJson": true,
    "message" : "for example some json parse exception text"
}

Ein JSON-Objekt ist auch dann ungültig, wenn ein ggf. angegebenes Datum nicht der Norm RFC3339 entspricht.

Limitierung von Aufrufzahlen

Für alle Schnittstellen gelten Begrenzungen hinsichtlich der Aufrufzahlen innerhalb von bestimmten Zeitbereichen. Beim Überschreiten dieser Begrenzungen wird der HTTP-Status-Code 429 zurückgegeben.

 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",
    "retentionTime" : "P30D",
    "context" : {
        "key" : "myContextKey",
        "type" : "bpm",
        "name" : "my context name"
    },
    "metadata" : [
        {
            "key" : "invoiceNumber",
            "caption" : "Invoice Number",
            "type" : "String",
            "values" : ["INV123489"]
        }, 
        {
            "key" : "amount",
            "caption" : "Amount",
            "type" : "Number",
            "values" : [125.75]
        }, 
        {
            "key" : "date",
            "caption" : "Date",
            "type" : "Date",
            "values" : ["2021-02-10"]
        }
    ],
    "dmsReferences" : [
        {
            "repoId" : "dms-repository-id",
            "objectId" : "dms-object-id"
        }
    ],
    "_links" : {
        "form" : { "href": "/myapp/form" },
        "callback" : { "href" : "/myapp/callback" },
        "attachment" : { "href" : "/myapp/example" },
        "process" : { "href" : "/process/example" },
        "changeCallback" : { "href" : "/myapp/changeCallback" }
    },
    "sendCreationNotification" : true,
    "sendCompletionNotification" : true,
    "sendDueDateNotification" : true,
    "actionScopes" : {
        "complete" : ["details"],
        "claim" : [],
        "forward" : ["details", "list"]
    }
}

Hinweise zum Inhalt

Metadaten

• key: Innerhalb dieser Metadaten eindeutiger Schlüssel aus ausschließlich alphanumerischen Zeichen (1-255 Zeichen). Verwende einen möglichst eindeutigen Schlüssel für deine Aufgaben, damit die Metadaten nicht mit Metadaten anderer Aufgabenquellen kollidieren.
• caption: Beschriftung des Metadatums (1-255 Zeichen).
• type: Datentyp des Metadatums (String, Number, Money, Date). Der Standard ist String.
• values: Wert des Metadatums. Aktuell ist pro Metadatum nur ein Wert erlaubt. null ist nicht erlaubt. Je nach Datentyp musst du das richtige Format der Werte beachten (siehe Abschnitt Datentypen der Metadaten). Für Vertretungsregeln oder Verantwortungsregeln kannst du nur Metadaten vom Typ String verwenden. Achte dabei auf führende oder abschließende Leerzeichen. Diese Leerzeichen werden in den Regeln berücksichtigt.

Datentypen der Metadaten

• String: Freitext mit 0 bis 255 Zeichen.
• Number: JSON Number zwischen -1e16 (exklusive) und 1e16 (exklusive) mit maximal 5 Dezimalstellen. Die Genauigkeit liegt bei 15 Stellen.
• Money: Wie Number, nur dass maximal 2 Dezimalstellen erlaubt sind.
• Date: Text im Format 'yyyy-MM-dd' (ISO-8601).

Besondere Links

• form: Diese URI stellt einen Bearbeitungsdialog für die Aufgabe bereit. Nähere Information findest du im Abschnitt Hinzufügen von Bearbeitungsdialogen.
• attachment: Diese URI wird als Aktion auf der Oberfläche angeboten, um dem Bearbeiter Zusatzinformationen anzuzeigen.
• callback: Diese URI wird bei Erledigung 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. Für die Anzeige bei erledigten Aufgaben muss die Ressource einen HEAD-Request implementieren, wenn die Ressource hinter derselben Basisadresse ist.
• changeCallback: Diese URI wird bei Änderungen an der Aufgabe mit der Methode POST aufgerufen.

Konfiguration von Aktionen in der Benutzeroberfläche

Der Scope einer Aktion in der Benutzeroberfläche ist ein Array und kann folgende Werte beinhalten: - details: Die Aktion kann nur in der geöffneten Aufgabenansicht durchgeführt werden, sofern dies nicht durch das Formular unterbunden wird. - list: Die Aktion kann in der Mehrfachauswahl durchgeführt werden. Ein leeres Array sagt aus, dass die Aktion in der Benutzeroberfläche nicht durchgeführt werden kann.

Du kannst folgende Aktionen konfigurieren: - complete: Aufgabe abschließen. Wenn der Scope dieser Aktion nicht den Wert details enthält, muss ein Formular konfiguriert werden. - forward: Aufgabe weiterleiten - claim: Aufgabe übernehmen oder zurückgeben.

Ist eine Aktion nicht konfiguriert, so gilt immer der einzelne Scope details.

Rückgabewerte

• 201: Die Aufgabe wurde erstellt oder war (unter Verwendung eines correlationKeys und ansonsten identischen Metadaten) bereits erstellt. Der Location-Header enthält den URI zur Aufgabe.
• 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.
• 409: Die Anfrage steht in Konflikt mit einer parallelen Anfrage. Wiederhole die Anfrage.
• 415: Es wurde ein falscher Typ im Content-Type-Header übergeben.
• 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 Betreff angegeben?
• Ist der Betreff maximal 255 Zeichen lang?
• Ist mindestens ein Bearbeiter angegeben?
• Ist der unter Absender eingetragene Benutzer im identity provider bekannt?
• Ist ein Korrelationsschlüssel angegeben?
• Ist der Korrelationsschlüssel maximal 255 Zeichen lang?
• Sind Kontextschlüssel, Kontexttyp und Kontextname maximal 255 Zeichen lang?
• Sind alle Bearbeiter im identity provider entweder als Benutzer oder als Gruppe bekannt?
• Falls eine Beschreibung angegeben ist: Ist diese maximal 500 Zeichen lang?
• Falls ein Fälligkeitsdatum angegeben ist: Liegt es nach dem 01.01.1970?
• Falls eine Priorität angegeben ist: Ist diese eine Ganzzahl?
• Falls ein Erinnerungsdatum angegeben ist: Liegt es nach dem 01.01.1970?
• Falls eine Aufbewahrungsdauer angegeben ist: Liegt sie zwischen 0 und 365 Tagen?
• Falls Links angegeben sind: Haben diese jeweils ein href-Attribut?
• Falls Metadaten angegeben sind: Entsprechen die Metadaten den Vorgaben (z.B.: Eindeutigkeit des Keys, Länge und Gültigkeit der Parameter etc.)
• Falls DMS-Referenzen angegeben sind: Handelt es sich um maximal eine Referenz? Sind Repository- und Objekt-ID vorhanden?
• Falls Aktionen konfiguriert werden: Wurden die Aktionen gültig konfiguriert? Gibt es ein Formular, falls das Abschließen von Aufgaben deaktiviert wurde?

Wenn die Validierung fehlschlägt, 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 JSON-Objekt 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,
    "invalidRetentionTime" : false,
    "invalidHrefs" : ["invalidHrefKey", "otherInvalidHrefKey"],
    "invalidCorrelationKey" : false,
    "missingCorrelationKey" : false,
    "invalidContext" : false,
    "invalidMetadata" : false,
    "invalidOptions" : ["sendDueDateNotification"],
    "invalidDmsReferences" : false,
    "invalidActionScopes" : ["CLAIM"]
}

Hinweise zum Inhalt

• invalidTaskDefinition: true, wenn kein JSON angegeben worden ist. Sonst false.
• missingSubject: true, wenn kein Betreff angegeben worden ist. Sonst false.
• invalidSubject: true, wenn der Betreff mehr als 255 Zeichen lang ist. Sonst false.
• invalidDescription: true, wenn die Beschreibung mehr als 500 Zeichen lang ist. Sonst false.
• missingAssignees: true, wenn nicht mindestens ein Bearbeiter angegeben worden ist. Sonst false.
• invalidSender: true, wenn der unter Absender angegebene Benutzer im identity provider nicht bekannt ist. Sonst false.
• invalidAssigneeIds: Array, das die Bearbeiter enthält, welche im identity provider unbekannt sind. Wenn alle bekannt sind, ist dieses Array leer.
• invalidDueDate: true, falls ein Fälligkeitsdatum angegeben worden ist, das vor dem 01.01.1970 liegt. false, wenn kein Fälligkeitsdatum angegeben worden ist oder wenn das Datum nach dem 01.01.1970 liegt.
• invalidPriority: true, falls eine Priorität angegeben wurde, die keiner Ganzzahl entspricht.
• invalidReminderDate: true, falls ein Erinnerungsdatum angegeben worden ist, das vor dem 01.01.1970 liegt. false, wenn kein Erinnerungsdatum angegeben worden ist oder wenn das Datum nach dem 01.01.1970 liegt.
• invalidRetentionTime: true, falls eine Aufbewahrungsdauer angegeben worden ist, die nicht zwischen 0 und 365 Tagen liegt. Sonst false.
• invalidHrefs: Array, das die Keys der Links enthält, die ungültig sind.
• invalidCorrelationKey: true, falls es zum angegebenen Korrelationsschlüssel bereits eine Aufgabe gibt, die sich jedoch inhaltlich von der neu zu erstellenden Aufgabe unterscheidet oder der Korrelationsschlüssel mehr als 255 Zeichen lang ist.
• missingCorrelationKey: true, wenn kein Korrelationsschlüssel angegeben wurde. Sonst false.
• invalidContext: true, wenn der Kontextschlüssel, der Kontexttyp oder der Kontextname länger als 255 Zeichen ist. Sonst false.
• invalidMetadata: true, wenn die Angaben zu den Metadaten ungültig sind.
• invalidOptions: Array, das die Namen von ungültigen Optionen enthält. Das Array enthält nur die ungültigen Optionen, die noch nicht durch ein anderes Feld behandelt wurden.
• invalidDmsReferences: true, wenn die angegebenen DMS-Referenzen ungültig sind.
• invalidActionScopes: Array, das die Namen von ungültigen Konfigurationen der Aktionen enthält.

Hinzufügen von lokalisierten Beschriftungen für Metadaten

Optional kannst du den Metadaten lokalisierte Beschriftungen hinzufügen. Zum Hinzufügen der lokalisierten Beschriftungen kannst du das JSON-Objekt bei der Erstellung einer Aufgabe folgendermaßen erweitern:

Request

{
    "metadata" : [
        {
            "key" : "invoiceNumber",
            "caption" : "Invoice Number",
            "type":"String",
            "values" : ["INV123489"],
            "i18n" : {
                "caption" : {
                    "de" : "Rechnungsnummer",
                    "it" : "Numero di fattura"
                }
            }
        }
    ]
}

Wenn du lokalisierte Beschriftungen angegeben hast, werden bei der Validierung folgende zusätzliche Überprüfungen durchgeführt: - Die Sprachkürzel müssen dem Standard ISO-639-1 entsprechen. - Die lokalisierten Beschriftungen unterliegen denselben Bedingungen wie die standardmäßige Beschriftung (1-255 Zeichen).

 Hinzufügen von Bearbeitungsdialogen

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 dem URI des Bearbeitungsdialogs hinzu. Du kannst den URI wahlweise absolut oder relativ zur Basisadresse angeben. Beim Erstellen 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"
        }
    }
}

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.

Abschließen einer Aufgabe 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
    }
});

Ausblenden von Aktionen in der geöffneten Aufgabenansicht

Das Ausblenden von Aktionen durch das Formular bezieht sich ausschließlich auf die geöffnete Aufgabenansicht. Bei Aufgaben, für die diese Aktion mit dem Scope list konfiguriert wurde, kann die Aktion in der Mehrfachauswahl weiterhin durchgeführt werden.

Ausblenden der Aktion "Erledigen"

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

<meta name="TaskApp.disableCompleteAction">

Ausblenden der Aktion "Weiterleiten"

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

<meta name="TaskApp.disableForwardAction">

Ausblenden der Aktionen "Übernehmen" und "Zurückgeben"

Um das Übernehmen und Zurückgeben einer Aufgabe durch die Aktionen in der Task-App zu verhindern, musst du dem Formular folgenden Meta-Tag hinzufügen:

<meta name="TaskApp.disableClaimAction">

Verwenden der Shell-App-Funktionen

Wenn du Funktionen der Shell-App 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-App eingeschränkt verwendet werden. Die folgenden Funktionen werden erlaubt:

• navigate
• setContextActions
• publishTitle
• addResourceEventListener
• setClosable
• setInterruptNavigationCallback
• openInnerSupply
• closeInnerSupply

Neue Kontextaktionen werden zusätzlich zu den Kontextaktionen der Task-App angezeigt.

 Rückmeldung bei Erledigung einer Aufgabe

Wenn bei der Erstellung einer Aufgabe der Link callback an die Task-App übergeben wird, wird bei Erledigung der Aufgabe eine Rückmeldung durchgeführt. Der übergebene URI wird von der Task-App mit der HTTP-POST-Methode aufgerufen. Liegt die Zieladresse hinter der Basisadresse, erfolgt der Aufruf authentifiziert. Die Task-App verwendet hierfür den App-User "task@app.idp.d-velop.local". Im Body werden die folgenden Daten übertragen:

{
    "event" : "COMPLETE",
    "timestamp" : "2022-05-13T20:16:17.000+02:00",
    "permission" : "NORMAL",
    "user" : "someUser",
    "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": "2018-08-31T20:16:17.000+02:00",
        "context": {
            "key":"myContextKey",
            "type": "Process",
            "name": "contextName"
        },
        "metadata": [
            {
                "key": "invoiceNumber",
                "caption": "Invoice Number",
                "type":"String",
                "values": ["INV123489"]
            }
        ],
        "dmsReferences" : [
            {
                "repoId" : "dms-repository-id",
                "objectId" : "dms-object-id"
            }
        ],
        "_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. Die Beschreibung kann in diesem Fall nur COMPLETE sein.
• timestamp: Zeitpunkt, zu dem die Aufgabe erledigt wurde.
• user: Benutzer, der die Aufgabe erledigt hat.
• permission: Berechtigung, mit der der Benutzer die Aufgabe erledigt hat (NORMAL, DEPUTY, SHARED). -- NORMAL: Der Benutzer war Bearbeiter der Aufgabe. -- DEPUTY: Der Benutzer hat die Aufgabe als Vertreter des Bearbeiters erledigt. -- SHARED: Der Benutzer hat die Aufgabe aus einer freigegebenen Aufgabenliste heraus erledigt.
• task: Die Daten der Aufgabe nach Erledigung.

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, erfolgt der Aufruf authentifiziert. Die Task-App verwendet hierfür den App-User "task@app.idp.d-velop.local". Im Body werden die folgenden Daten übertragen:

{
    "event" : "FORWARD",
    "timestamp" : "2022-05-13T20:16:17.000+02:00",
    "user" : "someUser",
    "permission" : "NORMAL",
    "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": {
            "key":"myContextKey",
            "type": "Process",
            "name": "contextName"
        },
        "metadata": [
            {
                "key": "invoiceNumber",
                "caption": "Invoice Number",
                "type":"String",
                "values": ["INV123489"]
            }
        ],
        "dmsReferences" : [
            {
                "repoId" : "dms-repository-id",
                "objectId" : "dms-object-id"
            }
        ],
        "_links": {
            "form": {"href": "/myapp/form"},
            "callback": {"href": "/myapp/callback"},
            "attachment": {"href": "/myapp/example"},
            "process": {"href": "/process/example"},
            "changeCallback": {"href": "/myapp/changeCallback"}
        },
        "actionScopes" : {
            "complete" : ["details"],
            "claim" : [],
            "forward" : ["details", "list"]
        }
    }
}

Hinweise zum Inhalt

• event: Beschreibung des Auslösers (FORWARD oder CHANGE).
• timestamp: Zeitpunkt der Änderung.
• user: Benutzer, der die Änderung durchgeführt hat.
• permission: Berechtigung, mit der der Benutzer die Aufgabe bearbeitet hat (NORMAL, DEPUTY, SHARED, CONTEXT oder ADMIN). -- NORMAL: Der Benutzer war Bearbeiter der Aufgabe. -- DEPUTY: Der Benutzer hat die Änderung als Vertreter des Bearbeiters durchgeführt. -- SHARED: Der Benutzer hat die Änderung aus einer freigegebenen Aufgabenliste heraus durchgeführt. -- CONTEXT: Der Benutzer hat die Änderung im Rahmen einer Kontextverantwortung durchgeführt. -- ADMIN: Der Benutzer hat die Änderung als Administrator durchgeführt.
• task: Die Daten der Aufgabe nach der Ä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.

 Erledigen einer Aufgabe

Mit dieser HTTP-Schnittstelle kannst du eine Aufgabe erledigen. Du kannst die Aufgabe nur erledigen, wenn du der aktuelle Bearbeiter der Aufgabe bist. Ein Aufruf im Rahmen anderer Berechtigungen, wie z.B. Vertretung, ist nicht möglich.

Übergabewerte

• URI: /task/tasks/{id}/completionState. Der Platzhalter {id} ist die ID der Aufgabe.
• Method: POST.
• Content: { "complete" : true, "completionUser" : "someUser" }

Durch die optionale Angabe von "completionUser" kannst du eine Aufgabe im Namen eines anderen Benutzers abschließen. Hierfür musst du ein Servicebenutzer sein.

• Content-Type: application/json

Rückgabewerte

• 401: Der Benutzer ist nicht authentifiziert.
• 403: Der Benutzer hat nicht das Recht, diese Aufgabe zu erledigen, beispielsweise weil es sich um eine Gruppenaufgabe handelt, die der Benutzer nicht übernommen hat.
• 404: Die Aufgabe existiert nicht.
• 415: Es wurde ein falscher Typ im Content-Type-Header übergeben.
• 409: Die Anfrage steht in Konflikt mit einer parallelen Anfrage. Wiederhole die Anfrage.
• 410: Die Aufgabe wurde bereits erledigt.
• 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

Du kannst optional folgende Parameter zur URI hinzufügen:

• 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. Diese Angabe 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. Diese Angabe 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-Aktion der Task-App.

 Löschen 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 sie auch erstellt hat. Ein Benutzer mit der Rolle "Servicebenutzer" darf jede Aufgabe löschen.

Übergabewerte

• URI: Location einer zuvor erstellten Aufgabe.
• Method: DELETE. Verwende zum Löschen einer Aufgabe folgende Anforderung: 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.
• 409: Die Anfrage steht in Konflikt mit einer parallelen Anfrage. Wiederhole die Anfrage.
• 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",
            "type":"String",
            "values" : ["INV123489"]
        }
    ],
    "dmsReferences" : [
        {
            "repoId" : "dms-repository-id",
            "objectId" : "dms-object-id"
        }
    ],
    "_links" : {
        "form" : { "href": "/myapp/form" },
        "callback" : { "href" : "/myapp/callback" },
        "attachment" : { "href" : "/myapp/example" },
        "process" : { "href" : "/process/example" },
        "changeCallback" : { "href" : "/myapp/changeCallback" }
    },
    "actionScopes" : {
        "complete" : ["details"],
        "claim" : [],
        "forward" : ["details", "list"]
    }
}

Hinweise zum Inhalt

Bei der Verwendung dieser Funktion kannst du ein Delta zur aktuellen Aufgabe angeben. 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 kannst du aktualisieren:

• subject: Betreff
• description: Beschreibungstext
• assignees: Empfänger
• priority: Priorität
• dueDate: Fälligkeitsdatum
• reminderDate: Erinnerungsdatum
• context: Kontext
• metadata: Metadaten
• dmsReferences: DMS-Referenzen
• _links: Verknüpfungen
• actionScopes: Konfiguration von Aktionen in der Benutzeroberfläche

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.
• 409: Die Anfrage steht in Konflikt mit einer parallelen Anfrage. Wiederhole die Anfrage.
• 410: Die Aufgabe wurde bereits erledigt.
• 415: Es wurde ein falscher Typ im Content-Type-Header übergeben.
• 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 'Servicebenutzer' sein.

 Auslesen der Anzahl der Aufgaben

Mit dieser HTTP-Schnittstelle kannst du die Anzahl deiner Aufgaben auslesen. Dabei handelt es sich um alle Aufgaben, die dir unter Meine Aufgaben in der Aufgabenliste angezeigt werden.

Übergabewerte

• URI: /task/count/all
• Methode: GET.
• Accept: application/json

Du erhältst folgende Antwort:

Response

GET /task/count/all
Content-Type: application/json
{
    "count" : 54
}

Hinweise zum Inhalt

• count: Anzahl der Aufgaben.

Rückgabewerte

• 200: Die Anzahl konnte erfolgreich gelesen werden.
• 401: Der Benutzer ist nicht authentifiziert.
• 406: Es wurde ein falscher Typ im Accept-Header übergeben.
• 500: Serverfehler.

Berechtigungen

Der aufrufende Benutzer muss angemeldet sein.

 Anzeigen der Aufgaben aller Verantwortungsregeln eines Benutzers

Mit dieser HTTP-Schnittstelle kannst du die Aufgaben aller Verantwortungsregeln anzeigen, die dir zugeordnet sind.

Übergabewerte

• URI: /task/tasks/contexts
• Method: GET.
• Accept: text/html

Response Du erhältst als Antwort die Aufgabenliste als HTML.

Rückgabewerte

• 200: Die HTML-Seite konnte erfolgreich erstellt werden.
• 401: Der Benutzer ist nicht authentifiziert.
• 406: Es wurde ein falscher Typ im Accept-Header übergeben.
• 500: Serverfehler.

Berechtigungen

Der aufrufende Benutzer muss angemeldet sein.

 Vorfiltern der Liste mit verantworteten Aufgaben anhand von Metadaten

Du kannst die Aufgabenliste mit den Aufgaben aller Verantwortungsregeln anhand von Metadaten filtern, indem du einen Filter per Anfrageparameter mitsendest. Es werden hier nur Metadaten vom Typ String berücksichtigt.

Parameter

• m:key=value

Dabei entspricht das Schlüsselwort key dem Key und das Schlüsselwort value dem Wert des Metadatums, auf dem der Filter basiert. Mehrere Anfrageparameter werden mit einem logischen ODER verknüpft.

Beispiel: /task/tasks/contexts?m:region=germany&m:region=uk

In diesem Beispiel wird die Aufgabenliste nach allen Aufgaben gefiltert, deren Metadatum region entweder den Wert germany oder uk hat.

 Neuladen der Aufgabenliste mit einem komplexen Filter

Du kannst die HTML-Seite zunächst auch ohne Daten laden. Im Anschluss kannst du einen komplexen Filter senden, der die Liste mit den Aufgaben füllt, die dem Filter entsprechen.

Parameter

• waitForData=true

Sobald das HTML der Seite erfolgreich geladen wurde, wird ein dapi-Event vom Typ changed auf der aufgerufenen URI versendet. Ab diesem Moment kann die Seite den komplexen Filter empfangen.

Du kannst den Filter per Message Event an die Taskliste senden.

targetWindow.postMessage({
    name: 'TaskApp.filterTasks', 
    filter: {
        metadata: {
            region: ["germany", "uk"]
            ...
        }
    }
}, location.origin);

Hinweise zum Inhalt

• name: Für diesen String musst du immer den Wert 'TaskApp.filterTasks' übergeben.
• filter: Dieses Objekt enthält das Metadaten-Objekt, welches die Filterkriterien für die Aufgabenliste beinhaltet. Es werden hier nur Metadaten vom Typ String berücksichtigt.

 Bearbeiten von Kontextregeln

Mit diesen Funktionen kannst du Regeln und Verantwortliche für Aufgabenkontexte definieren und bearbeiten. Es gibt diese Funktionen:

• Abfragen aller Kontextregeln
• Hinzufügen mehrerer Kontextregeln
• Ändern einer Kontextregel
• Löschen einer Kontextregel

Zum Verwenden der Funktionen musst du einen Benutzer in der Rolle Administrator oder Servicebenutzer verwenden.

 Abfragen aller Kontextregeln

Mit dieser HTTP-Schnittstelle kannst du alle vorhandenen Kontextregeln abfragen.

Request

GET /task/config/contextPermissions
Accept: application/hal+json

Response

{
    "entries": [
        {
            "rule": {
                "id": "qo4qj16j1",
                "name": "My rule",
                "statements": [
                    {
                        "field": {
                            "fieldType": "DEFAULT",
                            "name": "contextKey"
                        },
                        "expected": "mycontext"
                    }
                ]
            },
            "permissions": [
                {
                    "id": "856ce635-3131-4157-9d70-0ca32c75665e",
                    "group": false
                }
            ],
            "_links": {
                "self": {
                    "href": "/task/config/contextPermissions/entry/qo4qj16j1"
                }
            }
        }
    ],
    ...
}

Rückgabewerte - 200: Die Kontextregeln wurden abgefragt. - 401: Der Benutzer ist nicht authentifiziert. - 403: Der Benutzer hat nicht die Berechtigung, Kontextregeln zu bearbeiten. - 406: Es wurde ein falscher Typ im Accept-Header übergeben.

Hinweise zum Inhalt einer Kontextregel

Die Einschränkungen gelten für die Funktionen zum Hinzufügen und Ändern von Kontextregeln.

 Hinzufügen mehrerer Kontextregeln

Mit dieser HTTP-Schnittstelle kannst du mehrere Kontextegeln erstellen.

Request

POST /task/config/contextPermissions
Content-Type: application/json

{
    "entries": [
        {
            "rule": {
                "name": "My rule",
                "statements": [
                    {
                        "field": {
                            "fieldType": "DEFAULT",
                            "name": "contextKey"
                        },
                        "expected": "mycontext"
                    }
                ]
            },
            "permissions": [
                {
                    "id": "856ce635-3131-4157-9d70-0ca32c75665e",
                    "group": false
                }
            ]
        }
    ],
    ...
}

Bei der Erstellung neuer Kontextegeln werden automatisch neue IDs erzeugt.

Rückgabewerte

• 200: Die Kontextregeln wurden erfolgreich erstellt.
• 400: Eine oder mehrere Kontextregeln sind syntaktisch oder inhaltlich ungültig.
• 401: Der Benutzer ist nicht authentifiziert.
• 403: Der Benutzer hat nicht die Berechtigung, Kontextregeln zu bearbeiten.
• 415: Es wurde ein falscher Typ im Content-Type-Header übergeben.

Response

Die Antwort enthält alle neu hinzugefügten Kontextregeln, inklusive der Links auf die neuen Kontextregeln, in derselben Reihenfolge, in der du sie übergeben hast.

Wenn eine oder mehrere Kontextregeln ungültig sind, erhältst du in der Antwort eine Fehlermeldung:

{
    "message" : "..."
}

 Ändern einer Kontextregel

Mit dieser HTTP-Schnittstelle kannst du eine Kontextregel ändern. Ermittle zunächst die URL für die Kontextregel, die du ändern möchtest, mit der Funktion Abfragen aller Kontextregeln.

Request

PUT {URL der Kontextregel}
Content-Type: application/json

{
    "rule": {
        "name": "My rule",
        "statements": [
            {
                "field": {
                    "fieldType": "DEFAULT",
                    "name": "contextKey"
                },
                "expected": "mycontext"
            }
        ]
    },
    "permissions": [
        {
            "id": "856ce635-3131-4157-9d70-0ca32c75665e",
            "group": false
        }
    ]
}

Du musst immer die komplette Kontextregel übergeben, der gesamte Inhalt wird überschrieben.

Rückgabewerte

• 200: Die Kontextregel wurde erfolgreich geändert.
• 400: Die Kontextregel ist syntaktisch oder inhaltlich ungültig.
• 401: Der Benutzer ist nicht authentifiziert.
• 403: Der Benutzer hat nicht die Berechtigung, Kontextregeln zu bearbeiten.
• 415: Es wurde ein falscher Typ im Content-Type-Header übergeben.

 Löschen einer Kontextregel

Mit dieser HTTP-Schnittstelle kannst du eine Kontextregel löschen. Ermittle zunächst die URL für die Kontextregel, die du löschen möchtest, mit der Funktion Abfragen aller Kontextregeln.

Request

DELETE {URL der Kontextregel}

Rückgabewerte - 200: Die Kontextregel wurde erfolgreich gelöscht. - 401: Der Benutzer ist nicht authentifiziert. - 403: Der Benutzer hat nicht die Berechtigung, Kontextregeln zu bearbeiten. - 404: Die Kontextregel existiert nicht.