Task-App

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

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 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.
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
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
    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 ‘Technical administrator’.
    No
    _linksLinks to the task. The URL must be stored under the respective property href.claim, completion, contextPermission, disclaim, events, forward, preview, read and self are invalid.
    sendCreationNotificationSpecifies if a notification should be send when creating the task. 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

    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 a context 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.

    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.
    • 415: An incorrect type was transferred 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 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"]
    }
    

    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.

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

    Important

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

    Important

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

    Hiding the context action "Complete"

    To prevent the completion of a task via the context action in the task app, the following meta tag must be added to the form:

    
    <meta name="TaskApp.disableCompleteAction">
    

    Hiding the context action "Forward"

    To prevent the forwarding of a task via the context action in the task app, the following meta tag must be added to the form:

    
    <meta name="TaskApp.disableForwardAction">
    

    Hiding the context actions "Adopt" and "Return"

    To prevent the adopting and returning of a task via the context actions in the task app, the following meta tag must be added 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

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

     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.
    • Content:
      
      {
      "complete" : true
      }
      
    • 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.
    • 406: An incorrect type was transferred in the Content-Type header.
    • 410: This task was already completed.
    • 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 context action of the task app.

    Important

    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 "Technical administrator" 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.
    • 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"]
            }
        ],
        "_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

    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
    • _links: Links

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

    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
    }
    

    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.
    • 410: This task was already completed.
    • 415: An incorrect type was transferred 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 technical administrator.

     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 transferred 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 transferred in the Content-Type 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 the 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 the 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 professional administrator or technical administrator.

     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 transferred 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 transferred 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 transferred 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.