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

API keyDescriptionRequiredRestriction
subjectThe subject of the task.YesMax. 255 characters.
descriptionA descriptive text of the task.NoMax. 500 characters.
assigneesThe 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
correlationKeyThe correlation key ensures that only one task is created for this unique key. If a task already exists with the submitted key, a new task is not created and code 201 is returned regardless.

The new task to be created must be identical in content to a task that already exists under the same correlation key.
YesMax. 255 characters.
dueDateDue 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
priorityPriority between 0 (low) and 100 (high)No
receiveDateDelivery date in the future. Format according to RFC3339. If you transfer a date without a timestamp, the delivery date is the transferred date at 00:00:00.NoDate must be in the future.
reminderDateReminder 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
retentionTimeUsing 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
contextThe 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.
  • NoMax. 255 characters.
    metadataMetadata for the task.No
    dmsReferencesID of the DMS object and the respective DMS repository that references the task. A maximum of one reference is possible here.No
    senderOverwrites 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
    _linksLinks 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
    sendCreationNotificationSpecifies if a notification should be sent to the task creator when the task is created. Default is true.No
    sendCompletionNotificationSpecifies if a notification should be sent to the task creator when the task is completed. Default is false.No
    sendDueDateNotificationSpecifies 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
    actionScopesConfiguration for the usage of actions in the user interfaceNoType: 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 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:

    API keyDescriptionRemarks
    idID of the task.
    senderID of the user who created the task or most recently forwarded it.
    receiveDateDate on which the task was created or most recently forwarded.Format: RFC3339
    stateState of the task: OPEN or COMPLETED.
    editorPerson currently editing the task.
    completionUserUser who completed the task.Only present if the task is completed.
    completionDateDate 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 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.

    API keyDescriptionDefault valueRestriction
    pageSizeNumber of tasks per page in the results.10Maximum 100.
    orderByValue used to sort the results.receivedPermitted values: received, subject, priority and dueDate.
    orderDirSpecified sort order.ASCPermitted values: ASC for sorting in ascending order and DESC for sorting in descending order.
    filter.subjectSearch for subject.-Minimum 1 character, maximum 255.
    filter.assigneeSearch for recipient.-Minimum 1 character, maximum 255.
    filter.senderSearch for sender.-Minimum 1 character, maximum 255.
    filter.stateSearch for state.-Permitted values: OPEN and COMPLETED.
    filter.contextKeySearch for context key.-Max. 255 characters.
    filter.contextNameSearch for context name.-Max. 255 characters.
    filter.contextTypeSearch for context type.-Max. 255 characters.
    filter.dmsObjectIdSearch for DMS object ID.-Minimum 1 character, maximum 100.
    filter.dmsRepoIdSearch for DMS repository ID.-Minimum 1 character, maximum 100.
    filter.attachmentSearch for attachment.-Minimum 1 character, maximum 1.000.
    filter.completionUserSearch for user who completed the task.-Minimum 1 character, maximum 255.
    filter.prioritySearch for priority.-Between 0 and 100. You can search for individual priorities (.e.g.: [50]) or priority ranges (e.g. [“[5 to 50]”]).
    filter.receivedSearch for date received.-Date format according to RFC3339. You can only search for a range.
    filter.dueDateSearch for due date.-Date format according to RFC3339. You can only search for a range.
    filter.reminderDateSearch for reminder date.-Date format according to RFC3339. You can only search for a range.
    filter.completionDateSearch for completion date.-Date format according to RFC3339. You can only search for a range.
    filter.metadataSearch for metadata.-Can contain any quantity of metadata.
    You can only use metadata of the type “STRING” for the search.
    filter.metadata.xxxSearch 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 keyDescription
    tasksTasks found. The structure is the same as the API for retrieving a task.
    _links.nextLink 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 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.

    API keyDescriptionRestriction
    ruleContains the definition of the context rule.
    rule.idThe context rule ID.Is automatically generated.
    rule.nameThe display name of the context rule.Max. 100 characters.
    rule.statementsThe conditions of this context rule.At least one rule must exist.
    rule.statements.fieldThe field for the condition.
    rule.statements.field.fieldTypeThe field type.DEFAULT or METADATA.
    rule.statements.field.nameThe field name.For METADATA the key of a metadata (1-255 alphanumeric characters), for DEFAULT only contextKey.
    rule.statements.expectedThe comparative value for this condition.Max. 255 characters.
    permissionsThe authorized persons and groups for this context rule.
    permissions.idThe ID of a user or a group of the identity provider.The user or the group must exist.
    permissions.grouptrue, if it is a group, false, if it is a user.true or false. If you don't specify a value, false is assumed.
    _linksLinks to the context rule.
    _links.selfLink 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.