Package org.camunda.bpm.engine

Interface ExternalTaskService

  • All Known Implementing Classes:
    ExternalTaskServiceImpl
    public interface ExternalTaskService
    Service that provides access to ExternalTask instances. External tasks represent work items that are processed externally and independently of the process engine.
    Author:
    Thorben Lindhauer, Christopher Zell

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void complete​(java.lang.String externalTaskId, java.lang.String workerId)
      Completes an external task on behalf of a worker.
      void complete​(java.lang.String externalTaskId, java.lang.String workerId, java.util.Map<java.lang.String,​java.lang.Object> variables)
      Completes an external task on behalf of a worker and submits variables to the process instance before continuing execution.
      void complete​(java.lang.String externalTaskId, java.lang.String workerId, java.util.Map<java.lang.String,​java.lang.Object> variables, java.util.Map<java.lang.String,​java.lang.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​(java.lang.String externalTaskId, java.lang.String workerId, long newLockDuration)
      Extends a lock of an external task on behalf of a worker.
      ExternalTaskQueryBuilder fetchAndLock​(int maxTasks, java.lang.String workerId)
      Calls method fetchAndLock(maxTasks, workerId, usePriority), where usePriority is false.
      ExternalTaskQueryBuilder fetchAndLock​(int maxTasks, java.lang.String workerId, boolean usePriority)
      Defines fetching of external tasks by using a fluent builder.
      java.lang.String getExternalTaskErrorDetails​(java.lang.String externalTaskId)
      Returns the full error details that occurred while running external task with the given id.
      java.util.List<java.lang.String> getTopicNames()
      Returns a list of distinct topic names of all currently existing external tasks.
      java.util.List<java.lang.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​(java.lang.String externalTaskId, java.lang.String workerId, java.lang.String errorCode)
      Signals that an business error appears, which should be handled by the process engine.
      void handleBpmnError​(java.lang.String externalTaskId, java.lang.String workerId, java.lang.String errorCode, java.lang.String errorMessage)
      Signals that an business error appears, which should be handled by the process engine.
      void handleBpmnError​(java.lang.String externalTaskId, java.lang.String workerId, java.lang.String errorCode, java.lang.String errorMessage, java.util.Map<java.lang.String,​java.lang.Object> variables)
      Signals that an business error appears, which should be handled by the process engine.
      void handleFailure​(java.lang.String externalTaskId, java.lang.String workerId, java.lang.String errorMessage, int retries, long retryTimeout)
      Signals that an external task could not be successfully executed.
      void handleFailure​(java.lang.String externalTaskId, java.lang.String workerId, java.lang.String errorMessage, java.lang.String errorDetails, int retries, long retryTimeout)
      Signals that an external task could not be successfully executed.
      void handleFailure​(java.lang.String externalTaskId, java.lang.String workerId, java.lang.String errorMessage, java.lang.String errorDetails, int retries, long retryDuration, java.util.Map<java.lang.String,​java.lang.Object> variables, java.util.Map<java.lang.String,​java.lang.Object> localVariables)
      Signals that an external task could not be successfully executed.
      void lock​(java.lang.String externalTaskId, java.lang.String workerId, long lockDuration)
      Lock an external task on behalf of a worker.
      void setPriority​(java.lang.String externalTaskId, long priority)
      Sets the priority for an external task.
      void setRetries​(java.lang.String externalTaskId, int retries)
      Sets the retries for an external task.
      void setRetries​(java.util.List<java.lang.String> externalTaskIds, int retries)
      Sets the retries for external tasks.
      Batch setRetriesAsync​(java.util.List<java.lang.String> externalTaskIds, ExternalTaskQuery externalTaskQuery, int retries)
      Sets the retries for external tasks asynchronously as batch.
      void unlock​(java.lang.String externalTaskId)
      Unlocks an external task instance.
      UpdateExternalTaskRetriesSelectBuilder updateRetries()
      Sets the retries for external tasks using a fluent builder.

    • Method Detail

      • fetchAndLock

        ExternalTaskQueryBuilder fetchAndLock​(int maxTasks,
                                      java.lang.String workerId)
        Calls method fetchAndLock(maxTasks, workerId, usePriority), where usePriority is false.
        Parameters:
        maxTasks - the maximum number of tasks to return
        workerId - the id of the worker to lock the tasks for
        Returns:
        a builder to define and execute an external task fetching operation

      • fetchAndLock

        ExternalTaskQueryBuilder fetchAndLock​(int maxTasks,
                                      java.lang.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:

        Parameters:
        maxTasks - the maximum number of tasks to return
        workerId - the id of the worker to lock the tasks for
        usePriority - the flag to enable the priority fetching mechanism
        Returns:
        a builder to define and execute an external task fetching operation

      • lock

        void lock​(java.lang.String externalTaskId,
          java.lang.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.

        Parameters:
        externalTaskId - the id of the external task to lock
        workerId - the id of the worker to lock the task for
        lockDuration - the duration in milliseconds for which task should be locked
        Throws:
        NotFoundException - if no external task with the given id exists
        BadUserRequestException - if the task was already locked by a different worker
        AuthorizationException - thrown if the current user does not possess any of the following permissions:

      • complete

        void complete​(java.lang.String externalTaskId,
              java.lang.String workerId,
              java.util.Map<java.lang.String,​java.lang.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.

        Parameters:
        externalTaskId - the id of the external task to complete
        workerId - the id of the worker that completes the task
        variables - a map of variables to set on the execution (non-local) the external task is assigned to
        Throws:
        NotFoundException - if no external task with the given id exists
        BadUserRequestException - if the task is assigned to a different worker
        AuthorizationException - thrown if the current user does not possess any of the following permissions:

      • complete

        void complete​(java.lang.String externalTaskId,
              java.lang.String workerId,
              java.util.Map<java.lang.String,​java.lang.Object> variables,
              java.util.Map<java.lang.String,​java.lang.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.

        Parameters:
        externalTaskId - the id of the external task to complete
        workerId - the id of the worker that completes the task
        variables - a map of variables to set on the execution the external task is assigned to
        localVariables - a map of variables to set on the execution locally
        Throws:
        NotFoundException - if no external task with the given id exists
        BadUserRequestException - if the task is assigned to a different worker
        AuthorizationException - thrown if the current user does not possess any of the following permissions:

      • handleFailure

        void handleFailure​(java.lang.String externalTaskId,
                   java.lang.String workerId,
                   java.lang.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.

        Parameters:
        externalTaskId - the id of the external task to report a failure for
        workerId - the id of the worker that reports the failure
        errorMessage - 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.
        Throws:
        NotFoundException - if no external task with the given id exists
        BadUserRequestException - if the task is assigned to a different worker
        AuthorizationException - thrown if the current user does not possess any of the following permissions:

      • handleFailure

        void handleFailure​(java.lang.String externalTaskId,
                   java.lang.String workerId,
                   java.lang.String errorMessage,
                   java.lang.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.

        Parameters:
        externalTaskId - the id of the external task to report a failure for
        workerId - the id of the worker that reports the failure
        errorMessage - 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.
        Throws:
        NotFoundException - if no external task with the given id exists
        BadUserRequestException - if the task is assigned to a different worker
        AuthorizationException - thrown if the current user does not possess any of the following permissions:

      • handleFailure

        void handleFailure​(java.lang.String externalTaskId,
                   java.lang.String workerId,
                   java.lang.String errorMessage,
                   java.lang.String errorDetails,
                   int retries,
                   long retryDuration,
                   java.util.Map<java.lang.String,​java.lang.Object> variables,
                   java.util.Map<java.lang.String,​java.lang.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 the variables or localVariables parameter will be set before any output mapping is performed.
        Parameters:
        externalTaskId - the id of the external task to report a failure for
        workerId - the id of the worker that reports the failure
        errorMessage - 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 to
        localVariables - a map of variables to set on the execution locally
        Throws:
        NotFoundException - if no external task with the given id exists
        BadUserRequestException - if the task is assigned to a different worker
        AuthorizationException - thrown if the current user does not possess any of the following permissions:

      • handleBpmnError

        void handleBpmnError​(java.lang.String externalTaskId,
                     java.lang.String workerId,
                     java.lang.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.

        Parameters:
        externalTaskId - the id of the external task to report a bpmn error
        workerId - the id of the worker that reports the bpmn error
        errorCode - the error code of the corresponding bmpn error
        Throws:
        NotFoundException - if no external task with the given id exists
        BadUserRequestException - if the task is assigned to a different worker
        AuthorizationException - thrown if the current user does not possess any of the following permissions:
        Since:
        7.5

      • handleBpmnError

        void handleBpmnError​(java.lang.String externalTaskId,
                     java.lang.String workerId,
                     java.lang.String errorCode,
                     java.lang.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.

        Parameters:
        externalTaskId - the id of the external task to report a bpmn error
        workerId - the id of the worker that reports the bpmn error
        errorCode - the error code of the corresponding bmpn error
        errorMessage - the error message of the corresponding bmpn error
        Throws:
        NotFoundException - if no external task with the given id exists
        BadUserRequestException - if the task is assigned to a different worker
        AuthorizationException - thrown if the current user does not possess any of the following permissions:
        Since:
        7.10

      • handleBpmnError

        void handleBpmnError​(java.lang.String externalTaskId,
                     java.lang.String workerId,
                     java.lang.String errorCode,
                     java.lang.String errorMessage,
                     java.util.Map<java.lang.String,​java.lang.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.

        Parameters:
        externalTaskId - the id of the external task to report a bpmn error
        workerId - the id of the worker that reports the bpmn error
        errorCode - the error code of the corresponding bmpn error
        errorMessage - the error message of the corresponding bmpn error
        variables - the variables to pass to the execution
        Throws:
        NotFoundException - if no external task with the given id exists
        BadUserRequestException - if the task is assigned to a different worker
        AuthorizationException - thrown if the current user does not possess any of the following permissions:
        Since:
        7.10

      • setRetriesAsync

        Batch setRetriesAsync​(java.util.List<java.lang.String> externalTaskIds,
                      ExternalTaskQuery externalTaskQuery,
                      int retries)
        Sets the retries for external tasks asynchronously as batch. The returned batch can be used to track the progress. If the new value is 0, a new incident with a null message is created. If the old value is 0 and the new value is greater than 0, an existing incident is resolved.
        Parameters:
        externalTaskIds - the ids of the tasks to set the
        retries -
        externalTaskQuery - a query which selects the external tasks to set the retries for.
        Returns:
        the batch
        Throws:
        NotFoundException - if no external task with one of the given id exists
        BadUserRequestException - if the ids are null or the number of retries is negative
        AuthorizationException - If the user has no Permissions.CREATE or BatchPermissions.CREATE_BATCH_SET_EXTERNAL_TASK_RETRIES permission on Resources.BATCH.

      • getTopicNames

        java.util.List<java.lang.String> getTopicNames()
        Returns a list of distinct topic names of all currently existing external tasks. Returns an empty list if no topics are found.

      • getTopicNames

        java.util.List<java.lang.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. Returns an empty list if no matching tasks are found. Parameters are conjunctive, i.e. only tasks are returned that match all parameters with value 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.
        Parameters:
        withLockedTasks - return only topic names of unlocked tasks
        withUnlockedTasks - return only topic names of locked tasks
        withRetriesLeft - return only topic names of tasks with retries remaining