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.

 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:

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

SchlüsselBeschreibungErforderlichEinschränkung
subjectDer Betreff der Aufgabe.JaMaximal 255 Zeichen.
descriptionEine textuelle Beschreibung der Aufgabe.NeinMaximal 500 Zeichen.
assigneesDie Empfänger der Aufgabe. Du kannst sowohl Einzelnutzer als auch Gruppen mithilfe von IDs der Identityprovider-App angeben. Beim Erstellen der Aufgabe werden die IDs automatisch aufgelöst. Du musst mindestens einen Empfänger angeben.Ja
correlationKeyDer 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.

Die neu zu erstellende Aufgabe muss zu einer bereits unter demselben Korrelationsschlüssel existierenden Aufgabe inhaltlich identisch sein.
JaMaximal 255 Zeichen.
dueDateFälligkeitsdatum. Format nach RFC3339. Wenn du ein Datum ohne Zeitstempel übergibst, gilt für das Fälligkeitsdatum das übergebene Datum um 00:00:00 Uhr.

Alternativ kannst du auch eine Angabe in Millisekunden seit dem 1. Januar 1970 um 00:00:00 UTC übergeben. Diese Angabe wird aber in einer zukünftigen Version nicht mehr unterstützt.
Nein
priorityPriorität zwischen 0 (niedrig) und 100 (hoch)Nein
reminderDateErinnerungsdatum. Format nach RFC3339. Wenn du ein Datum ohne Zeitstempel übergibst, gilt für das Erinnerungsdatum das übergebene Datum um 00:00:00 Uhr.

Alternativ kannst du auch eine Angabe in Millisekunden seit dem 1. Januar 1970 um 00:00:00 UTC übergeben. Diese Angabe wird aber in einer zukünftigen Version nicht mehr unterstützt.
Nein
retentionTimeMithilfe dieser Eigenschaft kannst du bestimmen, wie lange die Aufgabendetails nach Erledigung der Aufgabe aufbewahrt werden. Gültige Werte liegen zwischen 0 und 365 Tagen. Nach Ablauf dieser Zeitspanne werden die Aufgabendetails automatisch gelöscht.

Die Angabe erfolgt als Zeitspanne nach ISO-8601 in Tagen, z.B. P30D für 30 Tage.
Gib die Zeitspanne P0D an, wenn die Aufgabendetails direkt nach dem Erledigen gelöscht werden sollen.
Wenn du keine Angabe machst, werden automatisch 30 Tage angenommen.
Nein
contextDer 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.
  • NeinMaximal 255 Zeichen.
    metadataMetadaten zur Aufgabe.Nein
    dmsReferencesID des DMS-Objektes sowie des entsprechenden DMS-Repositorys, das die Aufgabe referenziert. Hier ist maximal eine Referenz möglich.Nein
    senderÜberschreibt den Absender der Aufgabe mit einem anderen Benutzer. Bei diesem Parameter musst du die ID des Benutzers der Identityprovider-App angeben.
    Dieser Parameter darf nur verwendet werden, wenn der authentifizierte Benutzer die Benutzerrolle 'Servicebenutzer' hat.
    Nein
    _linksLinks zu der Aufgabe. Die URL muss jeweils unter dem Attribut href gespeichert werden.claim, completion, contextPermission, disclaim, events, forward, read und self sind nicht gültig
    sendCreationNotificationGibt an, ob beim Erstellen der Aufgabe eine Benachrichtigung verschickt werden soll. Der Standard ist true.Nein
    sendCompletionNotificationGibt an, ob beim Erledigen der Aufgabe eine Benachrichtigung an den Ersteller verschickt werden soll. Der Standard ist false.Nein
    sendDueDateNotificationGibt an, ob beim Überschreiten der Fälligkeit eine Benachrichtigung an den Ersteller verschickt werden soll. Diese Option ist nur möglich, wenn auch ein dueDate angegeben wurde. Der Standard ist false.Nein
    actionScopesKonfiguration für die Verwendung von Aktionen in der BenutzeroberflächeNeinTyp: claim, complete, forward / Scope (Array): details, list

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

    Wichtig

    Um zu überprüfen, ob der Bearbeitungsdialog erreichbar ist, führt die Task-App eine HTTP-HEAD-Anforderung auf den URI aus. Der Bearbeitungsdialog wird nur korrekt angezeigt, wenn der HTTP-Status-Code 200 zurückkommt. Der Bearbeitungsdialog muss daher auf HEAD-Anforderungen mit dem HTTP-Status-Code 200 antworten.

    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.

    Wichtig

    Nach dem erfolgreichen Abschluss einer Aufgabe in der Task-App darf innerhalb des Dialogs keinerlei Logik oder Benutzerinteraktion mehr ausgefü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.

    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.

     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.

    SchlüsselBeschreibungEinschränkung
    ruleEnthält die Definition der Kontextegel.
    rule.idDie ID der Kontextregel.Wird automatisch generiert.
    rule.nameDer Anzeigename der Kontextregel.Maximal 100 Zeichen.
    rule.statementsDie Bedingungen dieser Kontextregel.Mindestens eine Regel muss vorhanden sein.
    rule.statements.fieldDas Feld für diese Bedingung.
    rule.statements.field.fieldTypeDie Art des Feldes.DEFAULT oder METADATA.
    rule.statements.field.nameDer Name des Feldes.Bei METADATA der Schlüssel eines Metadatums (1-255 alphanumerische Zeichen), bei DEFAULT nur contextKey.
    rule.statements.expectedDer Vergleichswert für diese Bedingung.Maximal 255 Zeichen.
    permissionsDie berechtigten Personen und Gruppen für diese Kontextregel.
    permissions.idDie ID eines Benutzers oder einer Gruppe aus dem identity provider.Der Benutzer oder die Gruppe muss vorhanden sein.
    permissions.grouptrue, wenn es sich um eine Gruppe handelt, false wenn es sich um einen Benutzer handelttrue oder false. Wenn du den Wert nicht angibst, wird false angenommen.
    _linksVerknüpfungen zur Kontextregel.
    _links.selfLink zu dieser Kontextregel für die Verwendung weiterer Funktionen.

     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.