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:

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

API key	Description	Required	Restriction
subject	The subject of the task.	Yes	Max. 255 characters.
description	A descriptive text of the task.	No	Max. 500 characters.
assignees	The recipients of the task. You can specify individual users as well as groups using IDs of the identity provider app. The IDs are automatically resolved when creating a task. Specify at least one recipient.	Yes
correlationKey	The correlation key ensures that only one task is created for this unique key. If a task already exists with the passed key, a new task will not be created and the code 201 is returned nevertheless. The new task to be created must be identical in content to a task already existing under this correlationKey.	Yes	Max. 255 characters.
dueDate	Due date. Format according to RFC3339. If you transfer a date without a timestamp, the due date is the transferred date at 00:00:00. Alternatively, you can also specify it in milliseconds since January 1, 1970 at 00:00:00 UTC. However, this will no longer be possible with a future version.	No
priority	Priority between 0 (low) and 100 (high)	No
reminderDate	Reminder date. Format according to RFC3339. If you transfer a date without a timestamp, the reminder date is the transferred date at 00:00:00. Alternatively, you can also specify it in milliseconds since January 1, 1970 at 00:00:00 UTC. However, this will no longer be possible with a future version.	No
retentionTime	Using this property allows you to specify how long the task details should be kept after completing the task. Valid values are between 0 and 365 days. After this time has passed, the task details will be deleted automatically. The information is specified as a time span in days according to ISO-8601, e.g. P30D for 30 days. Specify the time span P0D if the task details should be deleted immediately after the task is completed. If you make no specification, 30 days are automatically assumed.	No
context	The context of a task. It consists of the following properties: key: A technical identifier for this context. type: A technical identifier for the type of context. name: A display name.	No	Max. 255 characters.
metadata	Metadata for the task.	No
dmsReferences	ID of the DMS object and the respective DMS repository that references the task. A maximum of one reference is possible here.	No
sender	Overwrites the sender of the task with another user. For this parameter, you must specify the identity provider ID of the user. This parameter may only be used if the authenticated user has the role ‘Service user’.	No
_links	Links to the task. The URL must be stored under the respective property href.		claim, completion, contextPermission, disclaim, events, forward, read and self are not valid
sendCreationNotification	Specifies if a notification should be sent to the task creator when the task is created. Default is true.	No
sendCompletionNotification	Specifies if a notification should be sent to the task creator when the task is completed. Default is false.	No
sendDueDateNotification	Specifies if a notification should be sent to the task creator when the due date is exceeded. This option is only available if a dueDate is specified. Default is false.	No
actionScopes	Configuration for the usage of actions in the user interface	No	Type: claim, complete, forward / Scope (Array): details, list

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

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.

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

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:

API key	Description	Remarks
id	ID of the task.
sender	ID of the user who created the task or most recently forwarded it.
receiveDate	Date on which the task was created or most recently forwarded.	Format: RFC3339
state	State of the task: “OPEN” or “COMPLETED”.
editor	Person currently editing the task.
completionUser	User who completed the task.	Only present if the task is completed.
completionDate	Date on which the task was completed.	Only present if the task is completed.

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. Repeat the request.
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.

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. Only one value can be entered for each value in the search filter. The search is not case-sensitive, unless you have a Microsoft SQL Server database with case-sensitive collation.

Numerical values and dates can also be restricted 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.

API key	Description	Default value	Restriction
pageSize	Number of tasks per page in the results.	10	Maximum 100.
orderBy	Value used to sort the results.	received	The values “received”, “subject”, “priority” and “dueDate” are allowed.
orderDir	Specified sort order.	ASC	“ASC” (for ascending) and “DESC” (for decending) are allowed.
filter.subject	Subject you are searching for.	-	Minimum 1 character, maximum 255.
filter.assignee	Assignee you are searching for.	-	Minimum 1 character, maximum 255.
filter.sender	Sender you are searching for.	-	Minimum 1 character, maximum 255.
filter.state	State you are searching for.	-	The allowed values are “OPEN” and “COMPLETED”.
filter.contextKey	Context key you are searching for.	-	Max. 255 characters.
filter.contextName	Context name you are searching for.	-	Max. 255 characters.
filter.contextType	Context type you are searching for.	-	Max. 255 characters.
filter.dmsObjectId	DMS object ID you are searching for.	-	Minimum 1 character, maximum 100.
filter.dmsRepoId	DMS repository ID you are searching for.	-	Minimum 1 character, maximum 100.
filter.attachment	Attachment you are searching for.	-	Minimum 1 character, maximum 1000.
filter.completionUser	User who completed the task.	-	Minimum 1 character, maximum 255.
filter.priority	Priority you are searching for.	-	Between 0 and 100. You can search for individual numbers (e.g. `[50]`) or a range (e.g. `["[5..50]"]`).
filter.received	Receipt date you are searching for.	-	Date format according to RFC3339. You can only search for a range.
filter.dueDate	Due date you are searching for.	-	Date format according to RFC3339. You can only search for a range.
filter.reminderDate	Reminder date you are searching for.	-	Date format according to RFC3339. You can only search for a range.
filter.completionDate	Completion date you are searching for.	-	Date format according to RFC3339. You can only search for a range.
filter.metadata	Metadata you are searching for.	-	Can contain any quantity of metadata. You can only use metadata of the type “STRING” for the search.
filter.metadata.xxx	Search entry for an individual piece of metadata.	-	Minimum 1 character, maximum 255. The key contains a minimum of 1 character, maximum 255.

Response

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

API key	Description
tasks	Tasks found. The structure is the same as the API for retrieving a task.
_links.next	Link to the next results page. There is no link if this is the last page.

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 passed 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

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 role 'Service user'.

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.

API key	Description	Restriction
rule	Contains the definition of the context rule.
rule.id	The context rule ID.	Is automatically generated.
rule.name	The display name of the context rule.	Max. 100 characters.
rule.statements	The conditions of this context rule.	At least one rule must exist.
rule.statements.field	The field for the condition.
rule.statements.field.fieldType	The field type.	DEFAULT or METADATA.
rule.statements.field.name	The field name.	For METADATA the key of a metadata (1-255 alphanumeric characters), for DEFAULT only contextKey.
rule.statements.expected	The comparative value for this condition.	Max. 255 characters.
permissions	The authorized persons and groups for this context rule.
permissions.id	The ID of a user or a group of the identity provider.	The user or the group must exist.
permissions.group	true, if it is a group, false, if it is a user.	true or false. If you don't specify a value, false is assumed.
_links	Links to the context rule.
_links.self	Link to the context rule for using further functions.

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.