Task app

Introduction

In this topic, you will find general information about the task API, the scope of functions as well as the knowledge which is helpful when programming functions and adjustments.

Function range of the task app

The task app handles features in the context of tasks. This includes creating tasks, editing tasks and the integration of forms and processes.

Technical background information

The task app provides public API functions using an HTTP interface which is available via the base address of HTTP Gateway app. To use this function, you need an authentication with the identity provider app in most cases.

Using the API functions

This chapter provides you with information on how to use the functions of Task API.

See also:

• Creating a task
• Retrieving a task
• Completing a task
• Searching for tasks
• Opening predefined user interfaces
• Deleting a task
• Changing a task
• Reading the number of tasks
• Displaying the tasks of all responsibility rules of a user
• Editing context rules

Note

Regarding all functions, if a formally invalid JSON object is transferred to an HTTP interface, the HTTP status code 400 is returned with the following response object:

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

A JSON object is also invalid if an optionally specified date does not correspond to the norm RFC3339.

Limit of number of calls

The number of calls within a certain time scope is limited for all interfaces. If these limits are surpassed, the status code 429 is returned.

Creating a task

This HTTP interface allows you to create a task.

• URI: /task/tasks
• Method: POST

To create a task, proceed as follows:

Request

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

{
    "subject" : "MyTask",
    "description" : "My descriptive text",
    "assignees" : ["someUser","someOtherUser","someGroup"],
    "correlationKey" : "someUniqueKey",
    "priority" : 80,
    "receiveDate" : "2018-06-10T10:00:00.000+02:00",
    "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"]
    }
}

Notes on the content

Metadata

• key: Unique key within these metadata consisting of only alphanumeric characters (1-255 character). Please make sure to use a distinct key for your tasks so that they do not collide with metadata of other task sources.
• caption: Label of the metadata field (1-255 character).
• type: Data type of the metadata (String, Number, Money, Date). Default is String.
• values: Value of the metadata field. Currently, only one value is allowed per metadata field. null is not allowed. Depending on the data type, you need to consider the correct value format (see section Data types of the metadata). You can only use metadate of the type String for delegate rules or responsibility rules. Pay attention to leading or trailing spaces. These spaces will be considered for the rules.

Data types of the metadata

• String: Free text with 0 to 255 characters.
• Number: JSON Number between -1e16 (exklusive) and 1e16 (exklusive) with a maximum of 5 decimals. The precision is 15 digits.
• Money: The same as Number but only 2 decimals are allowed.
• Date: Text in the format 'yyyy-MM-dd' (ISO-8601).

Special links

• form: This URI provides an editing dialog for the task. You can find further details in the section Adding editing dialogs.
• attachment: This URI is displayed as an action in the user interface to display additional information for the user.
• callback: This URI is called on completion of a task via the method POST.
• process: This URI represents the process by which the task was initiated. The process is displayed in the user interface as a separate perspective for the task. To display completed tasks, the resource has to implement a HEAD request, if the resource is behind the same base address.
• changeCallback: This URI is called in case of updates to the task via the method POST.

Configuration for actions in the user interface

The scope of an action in the user interface is an array and can contain the following values:

• details: The action can only be performed in the task view, provided it is not prevented by the form.
• list: The action can be performed in the multiple selection. An empty array means that the action cannot be performed in the user interface.

You can configure the following actions:

• complete: Finish task If the scope of this action does not contain the value details, a form must be configured.
• forward: Forward task
• claim: Adopt or return task.

If an action is not configured, the single scope details is always valid.

Return values

• 201: The task was created or has already been created before (using a correlation key with otherwise identical metadata). The Location header contains the URI of the task.
• 400: The task is invalid.
• 401: The user is not authenticated.
• 403: The user is not eligible to create the task. This is the case, if the parameter sender is applied and the user is no system user.
• 409: The request is in conflict with a parallel request. Repeat the request.
• 415: An incorrect type was passed in the Content-Type header.
• 500: Server error.

Validation of the parameters

Before creating the task, a validation of the passed JSON object takes place. The following validations are applied:

• Is a subject specified?
• Does the subject have a maximum length of 255 characters?
• Is at least one assignee specified?
• Is the user specified under "sender" known in the identity provider?
• Is a correlation key specified?
• Does the correlation key have a maximum length of 255 characters?
• Do the context key, the context type and the context name consist of a maximum of 255 characters?
• Are all assignees known in the identity provider either as users or groups?
• If a priority is specified: Does it consist of a maximum of 500 characters ?
• If a due date is specified: Is it after 01/01/1970?
• If a priority is specified: Is this an integer value?
• If a reminder date is specified: Is it after 01/01/1970?
• If a delivery date is specified: Is it in the past or the future?
• If a retention time is specified: Is it between 0 and 365 days?
• If links are specified: Do they each have a respective href attribute?
• If metadata are specified: Do the metadata comply with the specifications (e.g. is the key unique, length and validity of the parameters etc.)
• If DMS references are specified: Is it a maximum of one reference? Are repository and object ID available?
• If actions were configured: Were the actions configured validly? Does a form exist, if finishing the task was disabled?

If the validation fails, the task is not created and the HTTP status code 400 is returned. In this case, the response body contains a JSON object with the reason for the failure. This JSON object may for example look like this:

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"],
    "invalidReceiveDate": false
}

Notes on the content

• invalidTaskDefinition: true, if no JSON was specified. Else false.
• missingSubject: true, if no subject was specified. Else false.
• invalidSubject: true, if the subject exceeds 255 characters. Else false.
• invalidDescription: true, if the description exceeds 500 characters. Else false.
• missingAssignees: true, if not at least one assignee was specified. Else false.
• invalidSender: true, if the user specified under “sender” is not known in the identity provider. Else false.
• invalidAssigneeIds: Array containing the assignees not known in the identity provider. If all are known, this array is empty.
• invalidDueDate: true, if a due date was specified which lies before the 01/01/1970. false, if no due date was specified or if the date lies after the 01/01/1970.
• invalidPriority: true, if a priority was specified which does not correspond to an integer.
• invalidDueDate: true, if a reminder date was specified which lies before the 01/01/1970. false, if no reminder date was specified or if the date lies after the 01/01/1970.
• invalidRetentionTime: true, if a retention time was specified which is not between 0 and 365 days. Else false.
• invalidHrefs: Array containing the keys of the links being invalid.
• invalidCorrelationKey: true, if a task already exists for the specified correlationKey which, however, differs in content from the task to be newly created or if the correlationKey exceeds 255 characters.
• missingCorrelationKey: true, if no correlationKey was specified. Else false.
• invalidContext: true, if the context key, the context type or the context name exceeds 255 characters. Else false.
• invalidMetadata: true, if the information for the metadata is invalid.
• invalidOptions: Array which contains all invalid options. The array only contains invalid options which have not been handled by another field.
• invalidDmsReferences: true if the specified DMS references are invalid.
• invalidActionScopes: Array which contains the names of invalid configurations of the actions.
• invalidReceiveDate: true, if an invalid delivery date was specified. Else false.

Adding localized captions for metadata

You can optionally add localized metadata to captions. To add localized captions, you can extent the JSON object when creating a task:

Request

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

If you have specified localized metadata, the validation includes the following additional checks:

• The language abbreviations must comply with the ISO-639-1 standard.
• The localized captions must meet the same conditions as the default caption (1-255 characters).

Adding editing dialogs

When creating a task, you can optionally add an external editing dialog. For this effect, you add a link relation with the key form and the URI of the editing dialog to the JSON representation. You can specify the URI either as absolute or as relative to the base address. When creating the form, you should make sure not to implement a navigation within the form. This could otherwise lead to misleading situations when used in the task app. When opening the task in the user interface, the editing dialog is now displayed. The JSON may then look like this:

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

warning: To check that the editing dialog is available, the task app performs an HTTP HEAD request on the URI. The editing dialog is only displayed correctly, if the returned HTTP status code is 200. Thus, the editing dialog must respond to HEAD requests with the HTTP status code 200.

Editing dialogs provided by other servers are operated by the task app in an IFrame sandbox with the attributes allow-scripts and allow-forms.

Completing a task from an external editing dialog

To directly complete a task with an action from within the editing dialog, you can use the following JavaScript code:

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

To respond to a possible failed completion of a task, you can use the following JavaScript code:

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

Hiding actions in the open task view

Hiding actions via the form refers exclusively to the open task view. The action can still be performed in the multiple selection for tasks which have been configured with the scope list.

warning: Having successfully completed a task in the task app, no further logic or user interaction may be executed in the dialog.

Hiding the action "Complete"

To prevent the completion of a task via the action in the task app, you need to add the following meta tag to the form:

<meta name="TaskApp.disableCompleteAction">

Hiding the action "Forward"

To prevent the forwarding of a task via the action in the task app, you need to add the following meta tag to the form:

<meta name="TaskApp.disableForwardAction">

Hiding the actions "Adopt" and "Return"

To prevent the adoption and return of a task via the actions in the task app, you need to add the following meta tag to the form:

<meta name="TaskApp.disableClaimAction">

Using the shell app functions

If you want to use shell app functions, include at least version 2.13.1 of the file dapi.js in your editing dialog. Shell app functions can be used within the editing dialog to a limited extent. The following functions are allowed:

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

New context actions are displayed in addition to the context actions of the task app.

Callback upon task completion

If the link callback was passed to the task app when creating a task, a callback is performed upon task completion. The passed URI is then called via the HTTP POST method by the task app. If the target address lies beyond the base address, the call is authenticated. The task app uses the app user "task@app.idp.d-velop.local". The following information is passed in the body:

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

Notes on the content

• event: Description of the trigger. In this case, the description can only be COMPLETE.
• timestamp: Time at which the task was completed.
• user: User who completed the task.
• permissions: Permission with which the user completed the task (NORMAL, DEPUTY, SHARED). -- NORMAL: The user was the assignee of the task. -- DEPUTY: The user completed the task as delegate of the assignee. -- SHARED: The user completed the task from a shared task list.
• task: The task data after the completion.

The call must be answered with the status code 200. If this is not the case, the call is attempted again later.

Callback upon task update

If the link changeCallback was passed when creating a task, a callback is performed upon changing a task. The passed URI is then called via the HTTP POST method. If the target address lies beyond the base address, the call is authenticated. The task app uses the app user "task@app.idp.d-velop.local". The following information is passed in the body:

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

Notes on the content

• event: Description of the trigger (FORWARD or CHANGE)
• timestamp: Time of the change.
• user: User who performed the change.
• permissions: Permission with which the user edited the task (NORMAL, DEPUTY, SHARED, CONTEXT or ADMIN). -- NORMAL: The user was the assignee of the task. -- DEPUTY: The user performed the change as delegate of the assignee. -- SHARED: The user performed the change from a shared task list. -- CONTEXT: The user performed the change as part of a context responsibility. -- ADMIN: The user performed the change as administrator.
• task: The task data after the change.

The call must be answered with the status code 200. If this is not the case, the call is attempted again later. This renewed attempt also takes place, if the task has meanwhile been completed.

Retrieving a task

This HTTP interface allows you to retrieve a task in JSON format.

Parameters

• URI: /task/tasks/{id}. The placeholder {id} is the ID of your task.
• Method: GET
• Accept: application/hal+json, application/json

Response

{
    "id" : "7pu5jtq6im5bfadhb579hoa4p7",
    "subject" : "MyTask",
    "description" : "My descriptive text",
    "assignees" : ["someUser", "someOtherUser", "someGroup"],
    "editor" : "someOtherUser",
    "sender" : "someUser",
    "state" : "COMPLETED",
    "correlationKey" : "someUniqueKey",
    "priority" : 80,
    "receiveDate" : "2018-07-15T20:16:17.000+02:00",
    "reminderDate" : "2018-07-31T20:16:17.000+02:00",
    "dueDate" : "2018-08-15T20:16:17.000+02:00",
    "retentionTime" : "P30D",
    "completionUser" : "someUser",
    "completionDate" : "2020-02-03T12:44:42.000+02:00",
    "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" : {
        "self" : { "href": "/task/tasks/7pu5jtq6im5bfadhb579hoa4p7" },
        "form" : { "href": "/myapp/form" },
        "attachment" : { "href" : "/myapp/example" }
    }
}

Notes on the content

The fields are the same as those for creating a task. The following additional fields are also included:

Return values

• 200: The task has been retrieved successfully.
• 401: The user is not authenticated.
• 403: The user is not permitted to retrieve the task.
• 406: An incorrect type was passed in the Accept header.
• 429: The request has been denied because the request was made more frequently than is permitted.
• 500: Server error.

Permissions

The user retrieving the task must be logged in and meet one of the following conditions:

• The task is assigned to the user attempting to retrieve the task, either directly or as part of a group.
• The user retrieving the task is the delegate of the person to whom the task is assigned.
• The person to whom the task is assigned has released the task to the user attempting to retrieve the task.
• The user retrieving the task has the role “Administrator” or “Service user.”

Completing a task

This HTTP interface allows you to complete a task. You can only complete the task if you are the current task assignee. A call within the context of other authorizations, such as delegation, is not possible.

Parameters

• URI: /task/tasks/{id}/completionState. The placeholder {id} is the ID of your task.
• Method: POST

{
    "complete" : true,
    "completionUser" : "someUser"
}

You can complete a task in the name of another user with the optional specification of "completionUser". You need to be a service user to do this.

• Content-Type: application/json

Return values

• 401: The user is not authenticated.
• 403: The user does not have the permission to complete this task e.g. because it is a group task the user has not adopted.
• 404: The task does not exist.
• 415: An incorrect type was passed in the Content-Type header.
• 409: The request is in conflict with a parallel request or the task is scheduled for the future. Repeat the request again later if necessary.
• 410: This task was already completed.
• 500: Server error.

Searching for tasks

This HTTP interface allows you to search for tasks. You can search for tasks that you have received or completed. Users with the role “Service user” can search for all tasks. Tasks scheduled for a future delivery are not searched through.

Parameters

• URI: /task/api/tasks/search
• Method: POST

{
    "pageSize" : 10,
    "orderBy" : "received",
    "orderDirection" : "ASC",
    "filter" : {
        "subject" : ["My subject"],
        "assignee" : ["assigneeIdpId"],
        "sender" : ["senderIdpId"],
        "state" : ["COMPLETED"],
        "contextKey" : ["contextKey"],
        "contextName" : ["My context"],
        "contextType" : ["contextType"],
        "dmsRepoId" : ["repoId"],
        "dmsObjectId" : ["P00000001"],
        "attachment" : ["/link/to/attachment"],
        "completionUser" : ["completionUserIdpId"],
        "priority" : [50],
        "received" : ["[2024-03-01T00:00:00Z..2024-04-01T00:00:00Z]"],
        "dueDate" : ["[..2024-04-01T00:00:00Z]"],
        "reminderDate" : ["[2024-03-01T00:00:00Z..]"],
        "completionDate" : ["[2024-03-01T00:00:00Z..]"],
        "metadata" : {
            "myMetadata" : ["my value"]
        }
    }
}

• Content-Type: application/json

Notes on the content

Entries in the content are optional. You are only permitted to specify one value for each value in the search filter. The search is not case-sensitive (uppercase and lowercase letters are ignored), unless you have a Microsoft SQL Server database with case-sensitive collation (uppercase and lowercase letters are taken into acccount).

You can also restrict numerical values and date values using a range search. You can enter a range search as follows (example):

[5..25]
(2024-01-02T00:00:00Z..2025-01-02T12:00:00Z)

Square brackets search for the range including the boundary values, while round brackets exclude the boundary values.

Response

{
    "tasks" : [{
        "id" : "123",
        ...
    },
    ...
    ],
    "_links" : {
        "next" : {
            "href" : "/task/api/tasks/search?..."
        }
    }
}

To load the next search results page, send the exact same content from the search request to the link from the “next” link relation.

Return values

• 400: The search request is invalid.
• 401: The user is not authenticated.
• 415: An incorrect type was transferred in the Content-Type header.
• 500: Server error.

Opening predefined user interfaces

The task app allows other apps to integrate features with predefined user interfaces

Creating a task (UI)

Use this function to display a dialog for creating a task with a different app. The dialog is already prefilled with values.

Request

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

You can optionally add the following parameters to the URI:

• subject: Subject of the task.
• context: Context of the task.
• dueDate: Due date. Format according to RFC3339. Alternatively, you can also use a specification in milliseconds since January 1, 1970 at 00:00:00 UTC. However, this will no longer be possible with a future version.
• reminderDate: Reminder date. Format according to RFC3339. Alternatively, you can also use a specification in milliseconds since January 1, 1970 at 00:00:00 UTC. However, this will no longer be possible with a future version.
• links.form: URI of the task form
• links.attachment: URI for navigation in the attachment action of the task app.

warning: The values of links.form and links.attachment are not displayed in the user interface for the creation of a task. However, they are considered when creating the task and are passed to the task app.

Deleting a task

You can use this API function to remove a previously created task. You can find the URI in the Location header when creating the task. A task can only be deleted by the user who created it. A user with the role "Service user" can delete any task.

Parameters

• URI: Location of a previously created task.
• Method: DELETE. Use the following request to delete a task:

DELETE /task/...

Return values

• 200: The task was removed.
• 401: The user is not authenticated.
• 403: The user does not have the permission to delete this task.
• 404: The task does not exist.
• 409: The request is in conflict with a parallel request. Repeat the request.
• 500: Server error.

Changing a task

This HTTP interface allows you to change a task.

Parameters

• URI: Location of a previously created task.
• Method: PATCH.

To change a task, proceed as follows:

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

Notes on the content

When using this, you can specify a delta to the current task. All fields in the JSON content are optional. Only the fields you use will be updated. Make sure to always specify all components for the fields context and metadata, if you want to update them. You can update these fields:

• subject: Subject
• description: Description text
• assignees: Recipients
• priority: Priority
• dueDate: Due date
• reminderDate: Reminder date
• context: Context
• metadata: Metadata
• dmsReferences: DMS references
• _links: Links
• actionScopes: Configuration of actions in the user interface

The delivery date (receiveDate) for a task cannot be changed.

You can find information on the validation in the function Creating a task.

In order to remove date values, you can transfer the number 0.

If you want to remove a link, you can pass the respective key with the value null. For example, to remove the form link, pass the following:

"_links" : {
    "form" : null
}

If you want to remove metadata, you can pass the respective key with the value null. For example, to remove the invoiceNumber metadata, pass the following:

"metadata" : [
    {
        "key" : "invoiceNumber",
        "values" : null
    }
]

Return values

• 200: The task was updated.
• 400: One or more fields are invalid.
• 401: The user is not authenticated.
• 403: The user is not eligible to update the task.
• 409: The request is in conflict with a parallel request. Repeat the request.
• 410: This task was already completed.
• 415: An incorrect type was passed in the Content-Type header.
• 500: Server error.

Validation of the parameters

Here, the same rules apply as for the function Creating a task.

Permissions

The calling user must be in the “Service user” role.

Reading the number of tasks

This HTTP interface allows you to read the number of your tasks. This number includes all tasks that are displayed in your task list under My tasks.

Parameters

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

You receive the following response:

Response

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

Notes on the content

• count: Number of tasks.

Return values

• 200: The number could be read successfully.
• 401: The user is not authenticated.
• 406: An incorrect type was passed in the Accept header.
• 500: Server error.

Permissions

The calling user must be logged in.

Displaying the tasks of all responsibility rules of a user

This HTTP interface allows you to display the tasks of all of responsibility rules which are assigned to you.

Parameters

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

Response You receive the task list as HTML as reponse.

Return values

• 200: The HTML page could be created successfully.
• 401: The user is not authenticated.
• 406: An incorrect type was passed in the Accept header.
• 500: Server error.

Permissions

The calling user must be logged in.

Prefiltering the task list of tasks in one's area of responsibility based on metadata

You can filter the task list with the tasks in one's area of responsibility based on metadata by including a filter in a request parameter. Only metadata of type String are considered.

Parameter

• m:key=value

The key word key is the key and the key word value is the value of the metadata on which the filter is based. Multiple request parameters are connected with a logical OR.

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

In this example, the task list if filtered by tasks with the metadata region containing the value germany or uk.

Reloading the task list with a complex filter

You can load the HTML page without data at first. Afterwards, you can send a complex filter which fills the task list with tasks corresponding to this filter.

Parameter

• waitForData=true

As soon as the HTML of the page was loaded successfully, a changed dapi event type is sent to the called URI. From this point on, the page can receive the complex filter.

You can send the filter to the task list using a Message event.

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

Notes on the content

• name: You must always specify the value 'TaskApp.filterTasks' for this string.
• filter: This object contains the metadata object containing the filter criteria for the task list. Only metadata of type String are considered.

Editing context rules

Using these functions, you can define and edit rules and responsible persons for task contexts. These functions are available:

• Querying all context rules
• Adding multiple context rules
• Editing a context rule
• Deleting a context rule

To use these functions, you must use a user in the role Administrator or Service user.

Querying all context rules

This HTTP interface allows you to query all existing context rules.

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

Return values

• 200: The context rules were queried.
• 401: The user is not authenticated.
• 403: The user does not have the permission to edit context rules.
• 406: An incorrect type was passed in the Accept header.

Notes on the content of a context rule

The restrictions are applicable for the functions to add and to edit context rules.

Adding multiple context rules

This HTTP interface allows you to create multiple context rules.

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
                }
            ]
        }
    ],
    ...
}

When creating new context rules, new IDs are automatically generated.

Return values

• 200: The context rules were successfully created.
• 400: At least one context rule is invalid syntactically or with regards to content.
• 401: The user is not authenticated.
• 403: The user does not have the permission to edit context rules.
• 415: An incorrect type was passed in the Content-Type header.

Response

The response contains all newly created context rules, including the links to the new context rules in the same order as you transferred them.

If at least one context rule is invalid, you receive an error message in the response:

{
    "message" : "..."
}

Editing a context rule

This HTTP interface allows you to edit a context rule. Determine the URL for the context rule you want to edit using the function querying all context rules.

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

You always need to transfer the complete context rule, the entire content is overwritten.

Return values

• 200: The context rule was successfully changed.
• 400: The context rule is invalid syntactically or with regards to content.
• 401: The user is not authenticated.
• 403: The user does not have the permission to edit context rules.
• 415: An incorrect type was passed in the Content-Type header.

Deleting a context rule

This HTTP interface allows you to delete a context rule. Determine the URL for the context rule you want to delete using the function querying all context rules.

Request

DELETE {URL der Kontextregel}

Return values

• 200: The context rule was successfully deleted.
• 401: The user is not authenticated.
• 403: The user does not have the permission to edit context rules.
• 404: The context rule does not exist.