public interface ExternalTaskService
ExternalTask
instances. External tasks
represent work items that are processed externally and independently of the process
engine.Modifier and Type | Method and Description |
---|---|
void |
complete(String externalTaskId,
String workerId)
Completes an external task on behalf of a worker.
|
void |
complete(String externalTaskId,
String workerId,
Map<String,Object> variables)
Completes an external task on behalf of a worker and submits variables
to the process instance before continuing execution.
|
void |
complete(String externalTaskId,
String workerId,
Map<String,Object> variables,
Map<String,Object> localVariables)
Completes an external task on behalf of a worker and submits variables
to the process instance before continuing execution.
|
ExternalTaskQuery |
createExternalTaskQuery()
Queries for tasks that the currently authenticated user has at least one
of the following permissions for:
Permissions.READ on Resources.PROCESS_INSTANCE
Permissions.READ_INSTANCE on Resources.PROCESS_DEFINITION
|
void |
extendLock(String externalTaskId,
String workerId,
long newLockDuration)
Extends a lock of an external task on behalf of a worker.
|
ExternalTaskQueryBuilder |
fetchAndLock(int maxTasks,
String workerId)
Calls method fetchAndLock(maxTasks, workerId, usePriority), where usePriority is false.
|
ExternalTaskQueryBuilder |
fetchAndLock(int maxTasks,
String workerId,
boolean usePriority)
Defines fetching of external tasks by using a fluent builder.
|
String |
getExternalTaskErrorDetails(String externalTaskId)
Returns the full error details that occurred while running external task
with the given id.
|
List<String> |
getTopicNames()
Returns a list of distinct topic names of all currently existing external tasks.
|
List<String> |
getTopicNames(boolean withLockedTasks,
boolean withUnlockedTasks,
boolean withRetriesLeft)
Returns a list of distinct topic names of all currently existing external tasks
restricted by the parameters.
|
void |
handleBpmnError(String externalTaskId,
String workerId,
String errorCode)
Signals that an business error appears, which should be handled by the process engine.
|
void |
handleBpmnError(String externalTaskId,
String workerId,
String errorCode,
String errorMessage)
Signals that an business error appears, which should be handled by the process engine.
|
void |
handleBpmnError(String externalTaskId,
String workerId,
String errorCode,
String errorMessage,
Map<String,Object> variables)
Signals that an business error appears, which should be handled by the process engine.
|
void |
handleFailure(String externalTaskId,
String workerId,
String errorMessage,
int retries,
long retryTimeout)
Signals that an external task could not be successfully executed.
|
void |
handleFailure(String externalTaskId,
String workerId,
String errorMessage,
String errorDetails,
int retries,
long retryTimeout)
Signals that an external task could not be successfully executed.
|
void |
handleFailure(String externalTaskId,
String workerId,
String errorMessage,
String errorDetails,
int retries,
long retryDuration,
Map<String,Object> variables,
Map<String,Object> localVariables)
Signals that an external task could not be successfully executed.
|
void |
lock(String externalTaskId,
String workerId,
long lockDuration)
Lock an external task on behalf of a worker.
|
void |
setPriority(String externalTaskId,
long priority)
Sets the priority for an external task.
|
void |
setRetries(List<String> externalTaskIds,
int retries)
Sets the retries for external tasks.
|
void |
setRetries(String externalTaskId,
int retries)
Sets the retries for an external task.
|
Batch |
setRetriesAsync(List<String> externalTaskIds,
ExternalTaskQuery externalTaskQuery,
int retries)
Sets the retries for external tasks asynchronously as batch.
|
void |
unlock(String externalTaskId)
Unlocks an external task instance.
|
UpdateExternalTaskRetriesSelectBuilder |
updateRetries()
Sets the retries for external tasks using a fluent builder.
|
ExternalTaskQueryBuilder fetchAndLock(int maxTasks, String workerId)
maxTasks
- the maximum number of tasks to returnworkerId
- the id of the worker to lock the tasks forExternalTaskService#fetchAndLock(int, java.lang.String, boolean)}.
ExternalTaskQueryBuilder fetchAndLock(int maxTasks, String workerId, boolean usePriority)
Defines fetching of external tasks by using a fluent builder. The following parameters must be specified: A worker id, a maximum number of tasks to fetch and a flag that indicates whether priority should be regarded or not. The builder allows to specify multiple topics to fetch tasks for and individual lock durations. For every topic, variables can be fetched in addition. If priority is enabled, the tasks with the highest priority are fetched.
Returned tasks are locked for the given worker until
now + lockDuration
expires.
Locked tasks cannot be fetched or completed by other workers. When the lock time has expired,
a task may be fetched and locked by other workers.
Returns at most maxTasks
tasks. The tasks are arbitrarily
distributed among the specified topics. Example: Fetching 10 tasks of topics
"a"/"b"/"c" may return 3/3/4 tasks, or 10/0/0 tasks, etc.
May return less than maxTasks
tasks, if there exist not enough
unlocked tasks matching the provided topics or if parallel fetching by other workers
results in locking failures.
Returns only tasks that the currently authenticated user has at least one permission out of all of the following groups for:
maxTasks
- the maximum number of tasks to returnworkerId
- the id of the worker to lock the tasks forusePriority
- the flag to enable the priority fetching mechanismvoid lock(String externalTaskId, String workerId, long lockDuration)
Lock an external task on behalf of a worker.
Note: Attempting to lock an already locked external task with the same workerId
will succeed and a new lock duration will be set, starting from the current moment.
externalTaskId
- the id of the external task to lockworkerId
- the id of the worker to lock the task forlockDuration
- the duration in milliseconds for which task should be lockedNotFoundException
- if no external task with the given id existsBadUserRequestException
- if the task was already locked by a different workerAuthorizationException
- thrown if the current user does not possess any of the following permissions:
void complete(String externalTaskId, String workerId)
Completes an external task on behalf of a worker. The given task must be assigned to the worker.
externalTaskId
- the id of the external task to completeworkerId
- the id of the worker that completes the taskNotFoundException
- if no external task with the given id existsBadUserRequestException
- if the task is assigned to a different workerAuthorizationException
- thrown if the current user does not possess any of the following permissions:
void complete(String externalTaskId, String workerId, Map<String,Object> variables)
Completes an external task on behalf of a worker and submits variables to the process instance before continuing execution. The given task must be assigned to the worker.
externalTaskId
- the id of the external task to completeworkerId
- the id of the worker that completes the taskvariables
- a map of variables to set on the execution (non-local)
the external task is assigned toNotFoundException
- if no external task with the given id existsBadUserRequestException
- if the task is assigned to a different workerAuthorizationException
- thrown if the current user does not possess any of the following permissions:
void complete(String externalTaskId, String workerId, Map<String,Object> variables, Map<String,Object> localVariables)
Completes an external task on behalf of a worker and submits variables to the process instance before continuing execution. The given task must be assigned to the worker.
externalTaskId
- the id of the external task to completeworkerId
- the id of the worker that completes the taskvariables
- a map of variables to set on the execution
the external task is assigned tolocalVariables
- a map of variables to set on the execution locallyNotFoundException
- if no external task with the given id existsBadUserRequestException
- if the task is assigned to a different workerAuthorizationException
- thrown if the current user does not possess any of the following permissions:
void extendLock(String externalTaskId, String workerId, long newLockDuration)
Extends a lock of an external task on behalf of a worker. The given task must be assigned to the worker.
externalTaskId
- the id of the external taskworkerId
- the id of the worker that extends the lock of the taskNotFoundException
- if no external task with the given id existsBadUserRequestException
- if the task is assigned to a different workerAuthorizationException
- thrown if the current user does not possess any of the following permissions:
void handleFailure(String externalTaskId, String workerId, String errorMessage, int retries, long retryTimeout)
Signals that an external task could not be successfully executed.
The task must be assigned to the given worker. The number of retries left can be specified. In addition, a timeout can be
provided, such that the task cannot be fetched before now + retryTimeout
again.
If retries
is 0, an incident with the given error message is created. The incident gets resolved,
once the number of retries is increased again.
Exceptions raised in evaluating expressions of error event definitions attached to the task will be ignored by this method and the event definitions considered as not-matching.
externalTaskId
- the id of the external task to report a failure forworkerId
- the id of the worker that reports the failureerrorMessage
- short error message related to this failure. This message can be retrieved via
ExternalTask.getErrorMessage()
and is used as the incident message in case retries
is null
.
May be null
.retries
- the number of retries left. External tasks with 0 retries cannot be fetched anymore unless
the number of retries is increased via API. Must be >= 0.retryTimeout
- the timeout before the task can be fetched again. Must be >= 0.NotFoundException
- if no external task with the given id existsBadUserRequestException
- if the task is assigned to a different workerAuthorizationException
- thrown if the current user does not possess any of the following permissions:
void handleFailure(String externalTaskId, String workerId, String errorMessage, String errorDetails, int retries, long retryTimeout)
Signals that an external task could not be successfully executed.
The task must be assigned to the given worker. The number of retries left can be specified. In addition, a timeout can be
provided, such that the task cannot be fetched before now + retryTimeout
again.
If retries
is 0, an incident with the given error message is created. The incident gets resolved,
once the number of retries is increased again.
Exceptions raised in evaluating expressions of error event definitions attached to the task will be ignored by this method and the event definitions considered as not-matching.
externalTaskId
- the id of the external task to report a failure forworkerId
- the id of the worker that reports the failureerrorMessage
- short error message related to this failure. This message can be retrieved via
ExternalTask.getErrorMessage()
and is used as the incident message in case retries
is null
.
May be null
.errorDetails
- full error message related to this failure. This message can be retrieved via
getExternalTaskErrorDetails(String)
()}retries
- the number of retries left. External tasks with 0 retries cannot be fetched anymore unless
the number of retries is increased via API. Must be >= 0.retryTimeout
- the timeout before the task can be fetched again. Must be >= 0.NotFoundException
- if no external task with the given id existsBadUserRequestException
- if the task is assigned to a different workerAuthorizationException
- thrown if the current user does not possess any of the following permissions:
void handleFailure(String externalTaskId, String workerId, String errorMessage, String errorDetails, int retries, long retryDuration, Map<String,Object> variables, Map<String,Object> localVariables)
Signals that an external task could not be successfully executed.
The task must be assigned to the given worker. The number of retries left can be specified. In addition, a timeout can be
provided, such that the task cannot be fetched before now + retryTimeout
again.
If retries
is 0, an incident with the given error message is created. The incident gets resolved,
once the number of retries is increased again.
Exceptions raised in evaluating expressions of error event definitions attached to the task will be ignored by this method and the event definitions considered as not-matching.
Variables passed with thevariables
or localVariables
parameter will be set before any
output mapping is performed.externalTaskId
- the id of the external task to report a failure forworkerId
- the id of the worker that reports the failureerrorMessage
- short error message related to this failure. This message can be retrieved via
ExternalTask.getErrorMessage()
and is used as the incident message in case retries
is null
.
May be null
.errorDetails
- full error message related to this failure. This message can be retrieved via
getExternalTaskErrorDetails(String)
()}retries
- the number of retries left. External tasks with 0 retries cannot be fetched anymore unless
the number of retries is increased via API. Must be >= 0.retryTimeout
- the timeout before the task can be fetched again. Must be >= 0.variables
- a map of variables to set on the execution
the external task is assigned tolocalVariables
- a map of variables to set on the execution locallyNotFoundException
- if no external task with the given id existsBadUserRequestException
- if the task is assigned to a different workerAuthorizationException
- thrown if the current user does not possess any of the following permissions:
void handleBpmnError(String externalTaskId, String workerId, String errorCode)
Signals that an business error appears, which should be handled by the process engine. The task must be assigned to the given worker. The error will be propagated to the next error handler. Is no existing error handler for the given bpmn error the activity instance of the external task ends.
externalTaskId
- the id of the external task to report a bpmn errorworkerId
- the id of the worker that reports the bpmn errorerrorCode
- the error code of the corresponding bmpn errorNotFoundException
- if no external task with the given id existsBadUserRequestException
- if the task is assigned to a different workerAuthorizationException
- thrown if the current user does not possess any of the following permissions:
void handleBpmnError(String externalTaskId, String workerId, String errorCode, String errorMessage)
Signals that an business error appears, which should be handled by the process engine. The task must be assigned to the given worker. The error will be propagated to the next error handler. Is no existing error handler for the given bpmn error the activity instance of the external task ends.
externalTaskId
- the id of the external task to report a bpmn errorworkerId
- the id of the worker that reports the bpmn errorerrorCode
- the error code of the corresponding bmpn errorerrorMessage
- the error message of the corresponding bmpn errorNotFoundException
- if no external task with the given id existsBadUserRequestException
- if the task is assigned to a different workerAuthorizationException
- thrown if the current user does not possess any of the following permissions:
void handleBpmnError(String externalTaskId, String workerId, String errorCode, String errorMessage, Map<String,Object> variables)
Signals that an business error appears, which should be handled by the process engine. The task must be assigned to the given worker. The error will be propagated to the next error handler. Is no existing error handler for the given bpmn error the activity instance of the external task ends.
externalTaskId
- the id of the external task to report a bpmn errorworkerId
- the id of the worker that reports the bpmn errorerrorCode
- the error code of the corresponding bmpn errorerrorMessage
- the error message of the corresponding bmpn errorvariables
- the variables to pass to the executionNotFoundException
- if no external task with the given id existsBadUserRequestException
- if the task is assigned to a different workerAuthorizationException
- thrown if the current user does not possess any of the following permissions:
void unlock(String externalTaskId)
externalTaskId
- the id of the task to unlockNotFoundException
- if no external task with the given id existsAuthorizationException
- thrown if the current user does not possess any of the following permissions:
void setRetries(String externalTaskId, int retries)
null
message is created. If the old value is 0 and the new value is greater than 0, an existing incident
is resolved.externalTaskId
- the id of the task to set theretries
- NotFoundException
- if no external task with the given id existsAuthorizationException
- thrown if the current user does not possess any of the following permissions:
void setRetries(List<String> externalTaskIds, int retries)
null
message is created. If the old value is 0 and the new value is greater than 0, an existing incident
is resolved.externalTaskIds
- the ids of the tasks to set theretries
- NotFoundException
- if no external task with one of the given id existsBadUserRequestException
- if the ids are null or the number of retries is negativeAuthorizationException
- thrown if the current user does not possess any of the following permissions:
Batch setRetriesAsync(List<String> externalTaskIds, ExternalTaskQuery externalTaskQuery, int retries)
null
message is created. If the old value is 0 and the new value is greater than 0, an existing incident
is resolved.externalTaskIds
- the ids of the tasks to set theretries
- externalTaskQuery
- a query which selects the external tasks to set the retries for.NotFoundException
- if no external task with one of the given id existsBadUserRequestException
- if the ids are null or the number of retries is negativeAuthorizationException
- If the user has no Permissions.CREATE
or
BatchPermissions.CREATE_BATCH_SET_EXTERNAL_TASK_RETRIES
permission on Resources.BATCH
.UpdateExternalTaskRetriesSelectBuilder updateRetries()
UpdateExternalTaskRetriesBuilder.set(int)
or
UpdateExternalTaskRetriesBuilder.setAsync(int)
.void setPriority(String externalTaskId, long priority)
externalTaskId
- the id of the task to set thepriority
- the new priority of the taskNotFoundException
- if no external task with the given id existsAuthorizationException
- thrown if the current user does not possess any of the following permissions:
ExternalTaskQuery createExternalTaskQuery()
Queries for tasks that the currently authenticated user has at least one of the following permissions for:
ExternalTaskQuery
that can be used to dynamically
query for external tasks.List<String> getTopicNames()
List<String> getTopicNames(boolean withLockedTasks, boolean withUnlockedTasks, boolean withRetriesLeft)
true
. Parameters with value false
are effectively ignored.
For example, this means that an empty list is returned if both withLockedTasks
and withUnlockedTasks
are true.withLockedTasks
- return only topic names of unlocked taskswithUnlockedTasks
- return only topic names of locked taskswithRetriesLeft
- return only topic names of tasks with retries remainingString getExternalTaskErrorDetails(String externalTaskId)
externalTaskId
- id of the external task, cannot be null.ProcessEngineException
- When no external task exists with the given id.AuthorizationException
- If the user has no Permissions.READ
permission on Resources.PROCESS_INSTANCE
or no Permissions.READ_INSTANCE
permission on Resources.PROCESS_DEFINITION
.Copyright © 2022. All rights reserved.