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

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 error message that was supplied when the last failure of this task was reported.
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.
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.
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.
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",
  "executionId": "anExecutionId",
  "id": "anExternalTaskId",
  "lockExpirationTime": "2015-10-06T16:34:42",
  "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",
  "executionId": "anExecutionId",
  "id": "anExternalTaskId",
  "lockExpirationTime": "2015-10-06T16:34:42",
  "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
      }]
}

Response

Status 200.

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