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:
|
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. | ||||||||||||
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. | ||||||||||||
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:
|
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
}]
}
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": null,
"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": {}
}
}
}]