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:

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

SchlüsselBeschreibungErforderlichEinschränkung
subjectDer Betreff der Aufgabe.JaMaximal 255 Zeichen.
descriptionEine textuelle Beschreibung der Aufgabe.NeinMaximal 255 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 dueDate 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 reminderDate 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
    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 'Technischer Administrator' hat.
    Nein
    _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). 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).
    • values: Wert des Metadatums. (0-255 Zeichen). Aktuell ist pro Metadatum nur ein Wert erlaubt. Wenn du diese Werte für Vertretungs- oder Verantwortungsregeln benutzt, achte auf führende oder abschließende Leerzeichen. Diese werden in den Regeln berücksichtigt.

    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 Kontextaktion 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.
    • 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-key", "context-type" und "context-name" maximal 255 Zeichen lang?
    • Sind alle "assignees" im identity provider entweder als Benutzer oder als Gruppe bekannt?
    • Falls ein "dueDate" angegeben ist: Liegt es nach dem 01.01.1970?
    • Falls eine "priority" angegeben ist: Ist diese eine Ganzzahl?
    • Falls ein "reminderDate" angegeben ist: Liegt es nach dem 01.01.1970?
    • Falls eine "retentionTime" angegeben ist: Liegt sie zwischen 0 und 365 Tagen?
    • Falls "_links" angegeben sind: Haben diese jeweils eine "href"?
    • Falls "metadata" angegeben sind: Entsprechen die Metadaten den Vorgaben (z.B.: Eindeutigkeit des Keys, Länge und Gültigkeit der Parameter etc.)

    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
    }
    

    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.
    • invalidRetentionTime: true, falls eine "retentionTime" 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 "correlationKey" bereits eine Aufgabe gibt, die sich jedoch inhaltlich von der neu zu erstellenden 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-key", "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-Objekt formal ungültig ist, sieht das Response-Objekt folgendermaßen aus:

    
    {
        "invalidJson": true
    }
    

    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",
                "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
        }
    });
    

    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 Kontextaktion "Abschließen"

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

    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
    • activateSingleResourceMode
    • deactivateSingleResourceMode
    • setResourceVisibilityChangedCallback

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

     Erledigen einer Aufgabe

    Mit dieser HTTP-Schnittstelle kannst du eine Aufgabe erledigen.

    Ü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 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.
    • 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-Kontextaktion 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 "Technischer Administrator" 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.
    • 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 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 - _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.

     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.

    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.
    • 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.
    • 500: Serverfehler.

    Berechtigungen

    Der aufrufende Benutzer muss angemeldet sein.

     Vorfiltern der Aufgabenliste anhand von Metadaten

    Du kannst die Aufgabenliste anhand von Metadaten filtern, indem du einen Filter per Anfrageparameter mitsendest.

    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.