Edit on Github

Fetch and Lock External Tasks

Fetches and locks a specific number of external tasks for execution by a worker. Query can be restricted to specific task topics and for each task topic an individual lock time can be provided.

Method

POST /external-task/fetchAndLock

Parameters

Request Body

A JSON object with the following properties:

Name Description

workerId 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 Mandatory. The maximum number of tasks to return.

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

asyncResponseTimeout The Long Polling timeout in milliseconds.
Note: The value cannot be set larger than 1.800.000 milliseconds (corresponds to 30 minutes).

topics

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:

Name	Description
topicName	Mandatory. The topic's name.
lockDuration	Mandatory. The duration to lock the external tasks for in milliseconds.
variables	A JSON array of `String` values that represent variable names. For each result task belonging to this topic, the given variables are returned as well if they are accessible from the external task's execution. If not provided - all variables will be fetched.
localVariables	If `true` only local variables will be fetched.
businessKey	A `String` value which enables the filtering of tasks based on process instance business key.
processDefinitionId	Filter tasks based on process definition id.
processDefinitionIdIn	Filter tasks based on process definition ids.
processDefinitionKey	Filter tasks based on process definition key.
processDefinitionKeyIn	Filter tasks based on process definition keys.
processDefinitionVersionTag	Filter tasks based on process definition version tag.
withoutTenantId	Filter tasks without tenant id.
tenantIdIn	Filter tasks based on tenant ids.
processVariables	A `JSON` object used for filtering tasks based on process instance variable values. A property name of the object represents a process variable name, while the property value represents the process variable value to filter tasks by.
deserializeValues	Determines whether serializable variable values (typically variables that store custom Java objects) should be deserialized on server side (default `false`). If set to `true`, a serializable variable will be deserialized on server side and transformed to JSON using Jackson's POJO/bean property introspection feature. Note that this requires the Java classes of the variable value to be on the REST API's classpath. If set to `false`, a serializable variable will be returned in its serialized format. For example, a variable that is serialized as XML will be returned as a JSON string containing XML.
includeExtensionProperties	Determines whether custom extension properties defined in the BPMN activity of the external task (e.g. via the Extensions tab in the Camunda modeler) should be included in the response. Default: `false`

Result

A JSON array of locked external task objects. Each locked external task object has the following properties:

Name Value Description

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

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

errorMessage String 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 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 The id of the execution that the external task belongs to.

id String The id of the external task.

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

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

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

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

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

tenantId String The id of the tenant the external task belongs to.

retries Number The number of retries the task currently has left.

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

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

priority Number The priority of the external task.

topicName String The topic name of the external task.

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

variables

Object

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:

Name	Value	Description
value	String / Number / Boolean / Object	The variable's value.
type	String	The value type of the variable.
valueInfo	Object	A JSON object containing additional, value-type-dependent properties. For variables of type `Object`, the following properties are returned: `objectTypeName`: A string representation of the object's type name. `serializationDataFormat`: The serialization format used to store the variable.

Response Codes

Code	Media type	Description
200	application/json	Request successful.
500	application/json	Returned if fetching is not successful, for example due to missing parameters. See the Introduction for the error response format.

Example

Request

POST /external-task/fetchAndLock

Request Body:

    {
      "workerId":"aWorkerId",
      "maxTasks":2,
	  "usePriority":true,
      "topics":
          [{"topicName": "createOrder",
          "lockDuration": 10000,
          "variables": ["orderId"]
          }]
    }

Response

Status 200.

    [{
      "activityId": "anActivityId",
      "activityInstanceId": "anActivityInstanceId",
      "errorMessage": "anErrorMessage",
      "errorDetails": "anErrorDetails",
      "executionId": "anExecutionId",
      "id": "anExternalTaskId",
      "lockExpirationTime": "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",
      "processDefinitionId": "aProcessDefinitionId",
      "processDefinitionKey": "aProcessDefinitionKey",
      "processInstanceId": "aProcessInstanceId",
      "tenantId": null,
      "retries": 3,
      "workerId": "aWorkerId",
      "priority": 0,
      "topicName": "createOrder",
      "variables": {
        "orderId": {
          "type": "String",
          "value": "3456",
          "valueInfo": {}
        }
      }
    }]

Example with all variables

Request

POST /external-task/fetchAndLock

Request Body:

    {
      "workerId":"aWorkerId",
      "maxTasks":2,
      "usePriority":true,
      "topics":
          [{"topicName": "createOrder",
            "lockDuration": 10000,
            "processDefinitionId": "aProcessDefinitionId",
            "tenantIdIn": "tenantOne"
          }]
    }

Response

Status 200.

    [{
      "activityId": "anActivityId",
      "activityInstanceId": "anActivityInstanceId",
      "errorMessage": "anErrorMessage",
      "errorDetails": "anErrorDetails",
      "executionId": "anExecutionId",
      "id": "anExternalTaskId",
      "lockExpirationTime": "2015-10-06T16:34:42.00+0200",
      "processDefinitionId": "aProcessDefinitionId",
      "processDefinitionKey": "aProcessDefinitionKey",
      "processInstanceId": "aProcessInstanceId",
      "tenantId": "tenantOne",
      "retries": 3,
      "workerId": "aWorkerId",
      "priority": 4,
      "topicName": "createOrder",
      "businessKey": "aBusinessKey",
      "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",
      "processDefinitionId": "aProcessDefinitionId",
      "processDefinitionKey": "aProcessDefinitionKey",
      "processInstanceId": "aProcessInstanceId",
      "tenantId": null,
      "retries": 3,
      "workerId": "aWorkerId",
      "priority": 0,
      "topicName": "createOrder",
      "businessKey": "aBusinessKey",
      "variables": {
        "orderId": {
          "type": "String",
          "value": "3456",
          "valueInfo": {}
        }
      }
    }]

Example with Extension Properties

Given the external task definition contains extension properties:

    <bpmn:serviceTask id="anActivityId" name="Some External Task" camunda:type="external" camunda:topic="createOrder">
      <bpmn:extensionElements>
        <camunda:properties>
          <camunda:property name="property1" value="value1" />
          <camunda:property name="property2" value="value2" />
        </camunda:properties>
      </bpmn:extensionElements>
    </bpmn:serviceTask>

Request

POST /external-task/fetchAndLock

Request Body:

    {
      "workerId":"aWorkerId",
      "maxTasks":1,
      "usePriority":true,
      "topics":
          [{"topicName": "createOrder",
          "lockDuration": 10000,
          "includeExtensionProperties": true
          }]
    }

Response

Status 200.

  [{
      "activityId": "anActivityId",
      "activityInstanceId": "anActivityInstanceId",
      "errorMessage": "anErrorMessage",
      "errorDetails": "anErrorDetails",
      "executionId": "anExecutionId",
      "id": "anExternalTaskId",
      "lockExpirationTime": "2015-10-06T16:34:42.000+0200",
      "processDefinitionId": "aProcessDefinitionId",
      "processDefinitionKey": "aProcessDefinitionKey",
      "processInstanceId": "aProcessInstanceId",
      "retries": null,
      "suspended": false,
      "workerId": "aWorkerId",
      "topicName": "createOrder",
      "tenantId": null,
      "variables": {},
      "priority": 0,
      "businessKey": "default",
      "extensionProperties": {
          "property2": "value2",
          "property1": "value1"
      }
    }
]

Options

Fetch and Lock External Tasks

Method

Parameters

Request Body

Result

Response Codes

Example

Request

Response

Example with all variables

Request

Response

Example with Extension Properties

Request

Response

On this Page: