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).
Name Description
——-
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:

NameDescription
topicNameMandatory. The topic's name.
lockDurationMandatory. The duration to lock the external tasks for in milliseconds.
variablesA 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.
localVariablesIf true only local variables will be fetched.
businessKeyA String value which enables the filtering of tasks based on process instance business key.
processVariablesA 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.


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

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

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.
Name Value Description
——-
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:

NameValueDescription
valueString / Number / Boolean / Object The variable's value.
typeStringThe value type of the variable.
valueInfoObject 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.


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

    1. {
    2.   "workerId":"aWorkerId",
    3.   "maxTasks":2,
    4.   "usePriority":true,
    5.   "topics":
    6.       [{"topicName": "createOrder",
    7.       "lockDuration": 10000,
    8.       "variables": ["orderId"]
    9.       }]
    10. }

    Response

    Status 200.

    1. [{
    2.   "activityId": "anActivityId",
    3.   "activityInstanceId": "anActivityInstanceId",
    4.   "errorMessage": "anErrorMessage",
    5.   "errorDetails": "anErrorDetails",
    6.   "executionId": "anExecutionId",
    7.   "id": "anExternalTaskId",
    8.   "lockExpirationTime": "2015-10-06T16:34:42.000+0200",
    9.   "processDefinitionId": "aProcessDefinitionId",
    10.   "processDefinitionKey": "aProcessDefinitionKey",
    11.   "processInstanceId": "aProcessInstanceId",
    12.   "tenantId": null,
    13.   "retries": 3,
    14.   "workerId": "aWorkerId",
    15.   "priority": 4,
    16.   "topicName": "createOrder",
    17.   "variables": {
    18.     "orderId": {
    19.       "type": "String",
    20.       "value": "1234",
    21.       "valueInfo": {}
    22.     }
    23.   }
    24. },
    25. {
    26.   "activityId": "anActivityId",
    27.   "activityInstanceId": "anActivityInstanceId",
    28.   "errorMessage": "anErrorMessage",
    29.   "errorDetails": "anotherErrorDetails",
    30.   "executionId": "anExecutionId",
    31.   "id": "anExternalTaskId",
    32.   "lockExpirationTime": "2015-10-06T16:34:42.000+0200",
    33.   "processDefinitionId": "aProcessDefinitionId",
    34.   "processDefinitionKey": "aProcessDefinitionKey",
    35.   "processInstanceId": "aProcessInstanceId",
    36.   "tenantId": null,
    37.   "retries": 3,
    38.   "workerId": "aWorkerId",
    39.   "priority": 0,
    40.   "topicName": "createOrder",
    41.   "variables": {
    42.     "orderId": {
    43.       "type": "String",
    44.       "value": "3456",
    45.       "valueInfo": {}
    46.     }
    47.   }
    48. }]

    Example with all variables

    Request

    POST /external-task/fetchAndLock

    Request Body:

    1. {
    2.   "workerId":"aWorkerId",
    3.   "maxTasks":2,
    4.   "usePriority":true,
    5.   "topics":
    6.       [{"topicName": "createOrder",
    7.       "lockDuration": 10000
    8.       }]
    9. }

    Response

    Status 200.

    1. [{
    2.   "activityId": "anActivityId",
    3.   "activityInstanceId": "anActivityInstanceId",
    4.   "errorMessage": "anErrorMessage",
    5.   "errorDetails": "anErrorDetails",
    6.   "executionId": "anExecutionId",
    7.   "id": "anExternalTaskId",
    8.   "lockExpirationTime": "2015-10-06T16:34:42.00+0200",
    9.   "processDefinitionId": "aProcessDefinitionId",
    10.   "processDefinitionKey": "aProcessDefinitionKey",
    11.   "processInstanceId": "aProcessInstanceId",
    12.   "tenantId": null,
    13.   "retries": 3,
    14.   "workerId": "aWorkerId",
    15.   "priority": 4,
    16.   "topicName": "createOrder",
    17.   "businessKey": "aBusinessKey",
    18.   "variables": {
    19.     "orderId": {
    20.       "type": "String",
    21.       "value": "1234",
    22.       "valueInfo": {}
    23.     }
    24.   }
    25. },
    26. {
    27.   "activityId": "anActivityId",
    28.   "activityInstanceId": "anActivityInstanceId",
    29.   "errorMessage": "anErrorMessage",
    30.   "errorDetails": "anotherErrorDetails",
    31.   "executionId": "anExecutionId",
    32.   "id": "anExternalTaskId",
    33.   "lockExpirationTime": "2015-10-06T16:34:42.000+0200",
    34.   "processDefinitionId": "aProcessDefinitionId",
    35.   "processDefinitionKey": "aProcessDefinitionKey",
    36.   "processInstanceId": "aProcessInstanceId",
    37.   "tenantId": null,
    38.   "retries": 3,
    39.   "workerId": "aWorkerId",
    40.   "priority": 0,
    41.   "topicName": "createOrder",
    42.   "businessKey": "aBusinessKey",
    43.   "variables": {
    44.     "orderId": {
    45.       "type": "String",
    46.       "value": "3456",
    47.       "valueInfo": {}
    48.     }
    49.   }
    50. }]

    原文: https://docs.camunda.org/manual/7.9/reference/rest/external-task/fetch/