Skip to main content
POST
/
external-task
/
fetchAndLock
curl --request POST \
  --url http://{host}:{port}/{contextPath}/external-task/fetchAndLock \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '{
  "workerId": "aWorkerId",
  "maxTasks": 2,
  "usePriority": true,
  "topics": [
    {
      "topicName": "createOrder",
      "lockDuration": 10000,
      "variables": [
        "orderId"
      ]
    }
  ]
}'
[
  {
    "activityId": "anActivityId",
    "activityInstanceId": "anActivityInstanceId",
    "errorMessage": "anErrorMessage",
    "errorDetails": "anErrorDetails",
    "executionId": "anExecutionId",
    "id": "anExternalTaskId",
    "lockExpirationTime": "2015-10-06T16:34:42.000+0200",
    "createTime": "2015-10-06T16:34:42.000+0200",
    "processDefinitionId": "aProcessDefinitionId",
    "processDefinitionKey": "aProcessDefinitionKey",
    "processInstanceId": "aProcessInstanceId",
    "tenantId": null,
    "retries": 3,
    "workerId": "aWorkerId",
    "priority": 4,
    "topicName": "createOrder",
    "variables": {
      "orderId": {
        "type": "String",
        "value": "1234",
        "valueInfo": {}
      }
    }
  },
  {
    "activityId": "anActivityId",
    "activityInstanceId": "anActivityInstanceId",
    "errorMessage": "anErrorMessage",
    "errorDetails": "anotherErrorDetails",
    "executionId": "anExecutionId",
    "id": "anExternalTaskId",
    "lockExpirationTime": "2015-10-06T16:34:42.000+0200",
    "createTime": "2015-10-06T16:34:42.000+0200",
    "processDefinitionId": "aProcessDefinitionId",
    "processDefinitionKey": "aProcessDefinitionKey",
    "processInstanceId": "aProcessInstanceId",
    "tenantId": null,
    "retries": 3,
    "workerId": "aWorkerId",
    "priority": 0,
    "topicName": "createOrder",
    "variables": {
      "orderId": {
        "type": "String",
        "value": "3456",
        "valueInfo": {}
      }
    }
  }
]

Authorizations

​
Authorization
string
header
required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Body

application/json
​
workerId
string
required

Mandatory. The id of the worker on which behalf tasks are fetched. The returned tasks are locked for that worker and can only be completed when providing the same worker id.

​
maxTasks
integer | null
required

Mandatory. The maximum number of tasks to return.

​
usePriority
boolean | null

A boolean value, which indicates whether the task should be fetched based on its priority or arbitrarily.

​
asyncResponseTimeout
integer | null

The Long Polling timeout in milliseconds.

Note: The value cannot be set larger than 1.800.000 milliseconds (corresponds to 30 minutes).

​
topics
object[] | null

A JSON array of topic objects for which external tasks should be fetched. The returned tasks may be arbitrarily distributed among these topics. Each topic object has the following properties:

​
sorting
object[] | null

Apply sorting of the result

Response

Request successful.

​
activityId
string | null

The id of the activity that this external task belongs to.

​
activityInstanceId
string | null

The id of the activity instance that the external task belongs to.

​
errorMessage
string | null

The full error message submitted with the latest reported failure executing this task;null if no failure was reported previously or if no error message was submitted

​
errorDetails
string | null

The error details submitted with the latest reported failure executing this task.null if no failure was reported previously or if no error details was submitted

​
executionId
string | null

The id of the execution that the external task belongs to.

​
id
string | null

The id of the external task.

​
lockExpirationTime
string<date-time> | null

The date that the task's most recent lock expires or has expired.

​
processDefinitionId
string | null

The id of the process definition the external task is defined in.

​
processDefinitionKey
string | null

The key of the process definition the external task is defined in.

​
processDefinitionVersionTag
string | null

The version tag of the process definition the external task is defined in.

​
processInstanceId
string | null

The id of the process instance the external task belongs to.

​
tenantId
string | null

The id of the tenant the external task belongs to.

​
retries
integer | null

The number of retries the task currently has left.

​
suspended
boolean | null

Whether the process instance the external task belongs to is suspended.

​
workerId
string | null

The id of the worker that posesses or posessed the most recent lock.

​
priority
integer | null

The priority of the external task.

​
topicName
string | null

The topic name of the external task.

​
businessKey
string | null

The business key of the process instance the external task belongs to.

​
variables
object | null

A JSON object containing a property for each of the requested variables. The key is the variable name, the value is a JSON object of serialized variable values with the following properties: