org.camunda.bpm.engine.ExternalTaskService Maven / Gradle / Ivy
/* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.camunda.bpm.engine;
import java.util.Map;
import org.camunda.bpm.engine.authorization.Permissions;
import org.camunda.bpm.engine.authorization.Resources;
import org.camunda.bpm.engine.exception.NotFoundException;
import org.camunda.bpm.engine.externaltask.ExternalTask;
import org.camunda.bpm.engine.externaltask.ExternalTaskQuery;
import org.camunda.bpm.engine.externaltask.ExternalTaskQueryBuilder;
/**
* Service that provides access to {@link ExternalTask} instances. External tasks
* represent work items that are processed externally and independently of the process
* engine.
*
* @author Thorben Lindhauer
* @author Christopher Zell
*/
public interface ExternalTaskService {
/**
* Calls method fetchAndLock(maxTasks, workerId, usePriority), where usePriority is false.
*
* @param maxTasks the maximum number of tasks to return
* @param workerId the id of the worker to lock the tasks for
* @return a builder to define and execute an external task fetching operation
* @see {@link ExternalTaskService#fetchAndLock(int, java.lang.String, boolean)}.
*/
public ExternalTaskQueryBuilder fetchAndLock(int maxTasks, String workerId);
/**
* 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.Is the priority 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:
*
*
* - {@link Permissions#READ} on {@link Resources#PROCESS_INSTANCE}
* - {@link Permissions#READ_INSTANCE} on {@link Resources#PROCESS_DEFINITION}
*
*
* - {@link Permissions#UPDATE} on {@link Resources#PROCESS_INSTANCE}
* - {@link Permissions#UPDATE_INSTANCE} on {@link Resources#PROCESS_DEFINITION}
*
*
*
* @param maxTasks the maximum number of tasks to return
* @param workerId the id of the worker to lock the tasks for
* @param usePriority the flag to enable the priority fetching mechanism
* @return a builder to define and execute an external task fetching operation
*/
public ExternalTaskQueryBuilder fetchAndLock(int maxTasks, String workerId, boolean usePriority);
/**
* Completes an external task on behalf of a worker. The given task must be
* assigned to the worker.
*
* @param externalTaskId the id of the external to complete
* @param workerId the id of the worker that completes the task
* @throws NotFoundException if no external task with the given id exists
* @throws BadUserRequestException if the task is assigned to a different worker
* @throws AuthorizationException thrown if the current user does not possess any of the following permissions:
*
* - {@link Permissions#UPDATE} on {@link Resources#PROCESS_INSTANCE}
* - {@link Permissions#UPDATE_INSTANCE} on {@link Resources#PROCESS_DEFINITION}
*
*/
public void complete(String externalTaskId, String workerId);
/**
* 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.
*
* @param externalTaskId the id of the external to complete
* @param workerId the id of the worker that completes the task
* @param 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
* @throws BadUserRequestException if the task is assigned to a different worker
* @throws AuthorizationException thrown if the current user does not possess any of the following permissions:
*
* - {@link Permissions#UPDATE} on {@link Resources#PROCESS_INSTANCE}
* - {@link Permissions#UPDATE_INSTANCE} on {@link Resources#PROCESS_DEFINITION}
*
*/
public void complete(String externalTaskId, String workerId, Map variables);
/**
* 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.
*
* @param externalTaskId the id of the external task to report a failure for
* @param workerId the id of the worker that reports the failure
* @param errorMessage the error message related to this failure. This message can be retrieved via
* {@link ExternalTask#getErrorMessage()} and is used as the incident message in case retries is null.
* May be null.
* @param 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.
* @param retryTimeout the timeout before the task can be fetched again. Must be >= 0.
*
* @throws NotFoundException if no external task with the given id exists
* @throws BadUserRequestException if the task is assigned to a different worker
* @throws AuthorizationException thrown if the current user does not possess any of the following permissions:
*
* - {@link Permissions#UPDATE} on {@link Resources#PROCESS_INSTANCE}
* - {@link Permissions#UPDATE_INSTANCE} on {@link Resources#PROCESS_DEFINITION}
*
*/
public void handleFailure(String externalTaskId, String workerId, String errorMessage, int retries, long retryTimeout);
/**
* 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.
*
* @param externalTaskId the id of the external task to report a bpmn error
* @param workerId the id of the worker that reports the bpmn error
* @param errorCode the error code of the corresponding bmpn error
* @since 7.5
*
* @throws NotFoundException if no external task with the given id exists
* @throws BadUserRequestException if the task is assigned to a different worker
* @throws AuthorizationException thrown if the current user does not possess any of the following permissions:
*
* - {@link Permissions#UPDATE} on {@link Resources#PROCESS_INSTANCE}
* - {@link Permissions#UPDATE_INSTANCE} on {@link Resources#PROCESS_DEFINITION}
*
*/
public void handleBpmnError(String externalTaskId, String workerId, String errorCode);
/**
* Unlocks an external task instance.
*
* @param externalTaskId the id of the task to unlock
* @throws NotFoundException if no external task with the given id exists
* @throws AuthorizationException thrown if the current user does not possess any of the following permissions:
*
* - {@link Permissions#UPDATE} on {@link Resources#PROCESS_INSTANCE}
* - {@link Permissions#UPDATE_INSTANCE} on {@link Resources#PROCESS_DEFINITION}
*
*/
public void unlock(String externalTaskId);
/**
* Sets the retries for an external task. 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.
*
* @param externalTaskId the id of the task to set the
* @param retries
* @throws NotFoundException if no external task with the given id exists
* @throws AuthorizationException thrown if the current user does not possess any of the following permissions:
*
* - {@link Permissions#UPDATE} on {@link Resources#PROCESS_INSTANCE}
* - {@link Permissions#UPDATE_INSTANCE} on {@link Resources#PROCESS_DEFINITION}
*
*/
public void setRetries(String externalTaskId, int retries);
/**
* Sets the priority for an external task.
*
* @param externalTaskId the id of the task to set the
* @param priority the new priority of the task
* @throws NotFoundException if no external task with the given id exists
* @throws AuthorizationException thrown if the current user does not possess any of the following permissions:
*
* - {@link Permissions#UPDATE} on {@link Resources#PROCESS_INSTANCE}
* - {@link Permissions#UPDATE_INSTANCE} on {@link Resources#PROCESS_DEFINITION}
*
*/
public void setPriority(String externalTaskId, long priority);
/**
*
* Queries for tasks that the currently authenticated user has at least one
* of the following permissions for:
*
*
* - {@link Permissions#READ} on {@link Resources#PROCESS_INSTANCE}
* - {@link Permissions#READ_INSTANCE} on {@link Resources#PROCESS_DEFINITION}
*
*
*
* @return a new {@link ExternalTaskQuery} that can be used to dynamically
* query for external tasks.
*/
public ExternalTaskQuery createExternalTaskQuery();
}