org.bonitasoft.engine.api.ProcessRuntimeAPI Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of bonita-common Show documentation
Show all versions of bonita-common Show documentation
Bonita Common is the useful layer common to bonita-client and bonita-server
/**
* Copyright (C) 2019 Bonitasoft S.A.
* Bonitasoft, 32 rue Gustave Eiffel - 38000 Grenoble
* This library is free software; you can redistribute it and/or modify it under the terms
* of the GNU Lesser General Public License as published by the Free Software Foundation
* version 2.1 of the License.
* This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
* without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
* See the GNU Lesser General Public License for more details.
* You should have received a copy of the GNU Lesser General Public License along with this
* program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
* Floor, Boston, MA 02110-1301, USA.
**/
package org.bonitasoft.engine.api;
import java.io.Serializable;
import java.util.Date;
import java.util.List;
import java.util.Map;
import org.bonitasoft.engine.bpm.comment.ArchivedComment;
import org.bonitasoft.engine.bpm.comment.Comment;
import org.bonitasoft.engine.bpm.connector.ArchivedConnectorInstance;
import org.bonitasoft.engine.bpm.connector.ConnectorExecutionException;
import org.bonitasoft.engine.bpm.connector.ConnectorInstance;
import org.bonitasoft.engine.bpm.connector.ConnectorNotFoundException;
import org.bonitasoft.engine.bpm.contract.ContractDefinition;
import org.bonitasoft.engine.bpm.contract.ContractViolationException;
import org.bonitasoft.engine.bpm.data.ArchivedDataInstance;
import org.bonitasoft.engine.bpm.data.ArchivedDataNotFoundException;
import org.bonitasoft.engine.bpm.data.DataInstance;
import org.bonitasoft.engine.bpm.data.DataNotFoundException;
import org.bonitasoft.engine.bpm.flownode.*;
import org.bonitasoft.engine.bpm.process.*;
import org.bonitasoft.engine.exception.*;
import org.bonitasoft.engine.expression.Expression;
import org.bonitasoft.engine.expression.ExpressionEvaluationException;
import org.bonitasoft.engine.identity.User;
import org.bonitasoft.engine.identity.UserNotFoundException;
import org.bonitasoft.engine.job.FailedJob;
import org.bonitasoft.engine.operation.Operation;
import org.bonitasoft.engine.search.SearchOptions;
import org.bonitasoft.engine.search.SearchResult;
import org.bonitasoft.engine.session.InvalidSessionException;
/**
* ProcessRuntimeAPI deals with Process runtime notions such as starting a new instance of a process,
* retrieving and executing tasks, accessing to
* all types of tasks, assigning a user to a task, retrieving archived versions of a task, accessing / updating data /
* variable values, adding / retrieving
* process comments ...
* It generally allows all BPM runtime actions, that is, once process instances are running of finished executing.
*
* @author Baptiste Mesta
* @author Matthieu Chaffotte
* @author Yanyan Liu
* @author Zhao Na
* @author Frederic Bouquet
* @author Elias Ricken de Medeiros
* @author Celine Souchet
* @author Emmanuel Duchastenier
*/
public interface ProcessRuntimeAPI {
/**
* List all open root process instances.
*
* @param searchOptions
* The search criterion. See {@link org.bonitasoft.engine.bpm.process.ProcessInstanceSearchDescriptor} for
* valid fields for searching and sorting.
* @return A {@link ProcessInstance} object.
* @throws SearchException
* If an exception occurs when getting the list of tasks.
* @since 6.0
*/
SearchResult searchOpenProcessInstances(SearchOptions searchOptions) throws SearchException;
/**
* List all process instances.
*
* @param searchOptions
* The search criterion. See {@link org.bonitasoft.engine.bpm.process.ProcessInstanceSearchDescriptor} for
* valid fields for searching and sorting.
* @return A {@link ProcessInstance} object.
* @throws SearchException
* If an exception occurs when getting the list of {@link ProcessInstance}.
* @since 6.2
*/
SearchResult searchProcessInstances(SearchOptions searchOptions) throws SearchException;
/**
* List all process instances with at least one failed task or the
* {@link org.bonitasoft.engine.bpm.process.ProcessInstanceState#ERROR} state.
*
* @param searchOptions
* The search criterion. See {@link org.bonitasoft.engine.bpm.process.ProcessInstanceSearchDescriptor} for
* valid fields for searching and sorting.
* @return A {@link ProcessInstance} object.
* @throws SearchException
* If an exception occurs when getting the list of {@link ProcessInstance}.
* @since 6.4.0
*/
SearchResult searchFailedProcessInstances(SearchOptions searchOptions) throws SearchException;
/**
* List all process instances with at least one failed task or the
* {@link org.bonitasoft.engine.bpm.process.ProcessInstanceState#ERROR} state that
* are supervised by the given user.
* If the specified userId does not correspond to a user, an empty SearchResult is returned.
*
* @param userId
* The identifier of the user.
* @param searchOptions
* The search criterion. See {@link org.bonitasoft.engine.bpm.process.ProcessInstanceSearchDescriptor} for
* valid fields for searching and sorting.
* @return The list of failed process instances supervised by the specified user.
* @throws SearchException
* If an exception occurs when getting the list of process instances.
* @since 7.0
*/
SearchResult searchFailedProcessInstancesSupervisedBy(long userId, SearchOptions searchOptions)
throws SearchException;
/**
* List all open process instances supervised by a user.
* If the specified userId does not correspond to a user, an empty SearchResult is returned.
*
* @param userId
* The identifier of the user.
* @param searchOptions
* The search criterion. See {@link org.bonitasoft.engine.bpm.process.ProcessInstanceSearchDescriptor} for
* valid fields for searching and sorting.
* @return The list of process instances supervised by the specified user.
* @throws SearchException
* If an exception occurs when getting the list of process instances.
* @since 6.0
*/
SearchResult searchOpenProcessInstancesSupervisedBy(long userId, SearchOptions searchOptions)
throws SearchException;
/**
* Get the number of process data instances by process id.
*
* @param processInstanceId
* The identifier of the process instance.
* @return The number of process data instances.
* @throws ProcessInstanceNotFoundException
* If the specified ProcessInstance does not refer to a process instance.
* @since 6.0
*/
long getNumberOfProcessDataInstances(long processInstanceId) throws ProcessInstanceNotFoundException;
/**
* Get the number of activity data instances by activity id.
*
* @param activityInstanceId
* The identifier of the activity instance.
* @return The number of activity data instances.
* @throws ActivityInstanceNotFoundException
* If the specified activity instance does not refer to an activity instance.
* @since 6.0
*/
long getNumberOfActivityDataInstances(long activityInstanceId) throws ActivityInstanceNotFoundException;
/**
* Get a paged list of all process instances.
*
* @param startIndex
* The index of the first result (starting from 0).
* @param maxResults
* The maximum number of results per page.
* @param criterion
* The sort criterion.
* @return The list of process instances.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @since 6.0
*/
List getProcessInstances(int startIndex, int maxResults, ProcessInstanceCriterion criterion);
/**
* Get a paged list of archived process instances.
*
* @param startIndex
* The index of the first result (starting from 0).
* @param maxResults
* The maximum number of results per page.
* @param criterion
* The sort criterion.
* @return The list of archived process instances.
* @since 6.0
*/
List getArchivedProcessInstances(int startIndex, int maxResults,
ProcessInstanceCriterion criterion);
/**
* Get a paged list of archived activity instances for a process instance.
*
* @param sourceProcessInstanceId
* The identifier of the source process instance (used as root container id of the archived activity
* instances).
* @param startIndex
* The index of the first result (starting from 0).
* @param maxResults
* The maximum number of result per page.
* @param criterion
* The sort criterion.
* @return The list of archived activity instances.
* @since 6.0
*/
List getArchivedActivityInstances(long sourceProcessInstanceId, int startIndex,
int maxResults,
ActivityInstanceCriterion criterion);
/**
* Retrieve a paged list of open activities for a given process instance.
*
* @param processInstanceId
* The identifier of the process instance.
* @param startIndex
* The index of the first result (starting from 0).
* @param maxResults
* The maximum number of results per page.
* @param criterion
* The sort criterion.
* @return The list of activity instances.
* @since 6.0
*/
List getOpenActivityInstances(long processInstanceId, int startIndex, int maxResults,
ActivityInstanceCriterion criterion);
/**
* Get the total number of open activity instances by process instance id.
*
* @param processInstanceId
* The identifier of the process instance.
* @return The number of open activity instances.
* @throws ProcessInstanceNotFoundException
* If no matching process instance is found for parameter processInstanceId
* @since 6.0
*/
int getNumberOfOpenedActivityInstances(long processInstanceId) throws ProcessInstanceNotFoundException;
/**
* Get the number of open process instances.
* An open process instance is a process instance that has not been archived.
*
* @return The total number of open process instances.
* @since 6.0
*/
long getNumberOfProcessInstances();
/**
* Get the number of archived process instances.
* Root process instances in state COMPLETED are counted. Process instances started by call activities won't be
* counted.
*
* @return The number of archived process instances.
* @since 6.0
*/
long getNumberOfArchivedProcessInstances();
/**
* Delete the specified process instance.
*
* @param processInstanceId
* The identifier of the process instance to delete.
* @throws org.bonitasoft.engine.exception.ProcessInstanceHierarchicalDeletionException
* If a process instance cannot be deleted because of a parent that is still active.
* @throws DeletionException
* If an error occurs during deletion.
* @since 6.0
*/
void deleteProcessInstance(long processInstanceId) throws DeletionException;
/**
* Delete active process instances, and their elements, of process definition given as input parameter respecting
* the pagination parameters.
* Passing {@link Integer#MAX_VALUE} as maxResults is discouraged as the amount of operations may be large and may
* thus result in timeout operation.
* Instead, to delete all Process instances of a specific process definition, should you should use a loop and
* delete instances in bulk.
*
* @param processDefinitionId
* Identifier of the processDefinition
* @param startIndex
* The index
* @param maxResults
* The max number of elements to retrieve per page
* @return The number of elements that have been deleted
* @throws DeletionException
* If a process instance can't be deleted because of a parent that is still active
* @since 6.1
*/
long deleteProcessInstances(long processDefinitionId, int startIndex, int maxResults) throws DeletionException;
/**
* Delete archived process instances of process definition given as input parameter respecting the pagination
* parameters.
* Passing {@link Integer#MAX_VALUE} as maxResults is discouraged as the amount of operations may be large and may
* thus result in timeout operation.
* Instead, to delete all archived process instances of a specific process definition, you should use a loop and
* delete archived instances in bulk.
*
* @param processDefinitionId
* Identifier of the processDefinition
* @param startIndex
* The index
* @param maxResults
* The max number of elements to retrieve per page
* @return The number of rows deleted from the archived process instance table related to the cases that were
* deleted
* @throws DeletionException
* If there is some e.g. connection issue to the database
* @since 6.1
*/
long deleteArchivedProcessInstances(long processDefinitionId, int startIndex, int maxResults)
throws DeletionException;
/**
* Delete all archived process instance (different states) of the source identifier list.
* This work only with process instances that are root (not called by an other process). Using this method with ids
* of called processes (using call activity) will not delete them.
*
* @param sourceProcessInstanceIds
* Identifiers corresponding to {@link ArchivedProcessInstance#getSourceObjectId()}. These ids needs to be
* ids of root process instances
* @return The number of {@link ArchivedProcessInstance}s that have been deleted in any state. For example, process
* instance can be archived in several
* states: Cancelled, Aborted, Completed, Failed
* @throws DeletionException
* If there is some e.g. connection issue to the database
* @since 6.4.0
*/
long deleteArchivedProcessInstancesInAllStates(List sourceProcessInstanceIds) throws DeletionException;
/**
* Delete all archived process instance (different states) corresponding to the source identifier.
* This work only with process instances that are root (not called by an other process). Using this method with id
* of called process (using call activity) will not delete it.
*
* @param sourceProcessInstanceId
* Identifier corresponding to {@link ArchivedProcessInstance#getSourceObjectId()}. These id needs to be the
* id of a root process instances
* @return The number of {@link ArchivedProcessInstance}s that have been deleted in any state. For example, process
* instance can be archived in several
* states: Cancelled, Aborted, Completed, Failed
* @throws DeletionException
* If there is some e.g. connection issue to the database
* @since 6.4.0
*/
long deleteArchivedProcessInstancesInAllStates(long sourceProcessInstanceId) throws DeletionException;
/**
* Start an instance of the process with the specified process definition, using the current session user.
* Note: If the process instantiation
* contract requires inputs, you must use {@link #startProcessWithInputs(long, Map)} instead.
*
* @param processDefinitionId
* The identifier of the process definition for which an instance will be started.
* @return An instance of the process.
* @throws ProcessDefinitionNotFoundException
* If no matching process definition is found.
* @throws ProcessActivationException
* If an exception occurs during activation.
* @throws ProcessExecutionException
* If a problem occurs when starting the process.
* @since 6.0
*/
ProcessInstance startProcess(long processDefinitionId)
throws ProcessDefinitionNotFoundException, ProcessActivationException, ProcessExecutionException;
/**
* Instantiates a process.
* The process variables will be initialized by the initialVariables parameter. Note: If the
* process instantiation contract requires
* inputs, you must use {@link #startProcessWithInputs(long, Map)} instead, transforming
* initialVariables parameter as follows: in the process,
* define process variables initial values (expressions) with contract inputs.
*
* @param processDefinitionId
* The identifier of the processDefinition
* @param initialVariables
* The couples of initial variable/value
* @return A ProcessInstance object
* @throws ProcessDefinitionNotFoundException
* If The identifier of process definition does not refer to any existing process definition
* @throws ProcessExecutionException
* If the process fails to start
* @throws ProcessActivationException
* If the process is disable
* @since 6.1
*/
ProcessInstance startProcess(long processDefinitionId, Map initialVariables)
throws ProcessDefinitionNotFoundException,
ProcessActivationException, ProcessExecutionException;
/**
* Start an instance of the process with the specified process definition id, and set the initial values of the data
* with the given operations. Note:
* If the process instantiation contract requires inputs, you must use {@link #startProcessWithInputs(long, Map)}
* instead. The best practice is to define
* contract inputs in the process definition, and use these contract inputs in operations, instead of providing
* operations at start time.
*
* @param processDefinitionId
* The identifier of the process definition for which an instance will be started.
* @param operations
* The operations to execute to set the initial values of the data.
* @param context
* The context in which operations are executed.
* @return An instance of the process.
* @throws ProcessDefinitionNotFoundException
* If no matching process definition is found.
* @throws ProcessActivationException
* If an exception occurs during activation.
* @throws ProcessExecutionException
* If a problem occurs when starting the process.
* @since 6.0
*/
ProcessInstance startProcess(long processDefinitionId, List operations,
Map context)
throws ProcessDefinitionNotFoundException, ProcessActivationException, ProcessExecutionException;
/**
* Start an instance of the process with the specified process definition id on behalf of a given user. Note:
* If the process instantiation contract
* requires inputs, you must use {@link #startProcessWithInputs(long, long, Map)} instead.
*
* @param userId
* The user id of the user.
* @param processDefinitionId
* The identifier of the process definition for which an instance will be started.
* @return An instance of the process.
* @throws UserNotFoundException
* If the given user does not exist.
* @throws ProcessDefinitionNotFoundException
* If no matching process definition is found.
* @throws ProcessActivationException
* If a problem occurs when starting the process.
* @throws ProcessExecutionException
* If an execution problem occurs when starting the process.
* @since 6.0
*/
ProcessInstance startProcess(long userId, long processDefinitionId)
throws UserNotFoundException, ProcessDefinitionNotFoundException,
ProcessActivationException, ProcessExecutionException;
/**
* Start an instance of the process with the specified process definition id on behalf of a given user, and set the
* initial values of the data with the
* given operations. Note: If the process instantiation contract requires inputs, you must use
* {@link #startProcessWithInputs(long, long, Map)}
* instead. The best practice is to design contract inputs in the process definition, and use these
* contract inputs in operations, instead of providing operations at start time.
*
* @param userId
* The identifier of the user.
* @param processDefinitionId
* The identifier of the process definition for which an instance will be started.
* @param operations
* The operations to execute to set the initial values of the data.
* @param context
* The context in which the operations are executed.
* @return An instance of the process.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws ProcessDefinitionNotFoundException
* If no matching process definition is found.
* @throws ProcessActivationException
* If an exception occurs during activation.
* @throws UserNotFoundException
* If there is no user with the specified userId.
* @throws ProcessExecutionException
* If a problem occurs when starting the process.
* @since 6.0
*/
ProcessInstance startProcess(long userId, long processDefinitionId, List operations,
Map context)
throws UserNotFoundException, ProcessDefinitionNotFoundException, ProcessActivationException,
ProcessExecutionException;
/**
* Start an instance of the process with the specified process definition id on behalf of a given user, and set the
* initial values of the data with the
* given initialVariables. Note: If the process instantiation contract requires inputs, you must use
* {@link #startProcessWithInputs(long, long, Map)}
* instead, using contract inputs stored in process variables, instead of using directly initialVariables.
*
* @param userId
* The identifier of the user.
* @param processDefinitionId
* The identifier of the process definition for which an instance will be started.
* @param initialVariables
* The couples of initial variable/value
* @return An instance of the process.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws ProcessDefinitionNotFoundException
* If no matching process definition is found.
* @throws ProcessActivationException
* If an exception occurs during activation.
* @throws ProcessExecutionException
* If a problem occurs when starting the process.
* @since 6.0
*/
ProcessInstance startProcess(final long userId, final long processDefinitionId,
final Map initialVariables)
throws ProcessDefinitionNotFoundException, ProcessActivationException, ProcessExecutionException;
/**
* Start an instance of the process with the specified process definition id, and provides inputs to fulfill Process
* Contract.
* See {@link org.bonitasoft.engine.bpm.contract.ContractDefinition} for details on contracts.
*
* @param processDefinitionId
* The identifier of the process definition for which an instance will be started.
* @param instantiationInputs
* The couples of input name/value that allows to start a process with an instantiation contract.
* @return An instance of the process.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws ProcessDefinitionNotFoundException
* If no matching process definition is found.
* @throws ProcessActivationException
* If an exception occurs during activation.
* @throws ProcessExecutionException
* If a problem occurs when starting the process.
* @throws ContractViolationException
* If inputs don't fit with task contract
* @since 7.0.0
*/
ProcessInstance startProcessWithInputs(final long processDefinitionId,
final Map instantiationInputs)
throws ProcessDefinitionNotFoundException, ProcessActivationException, ProcessExecutionException,
ContractViolationException;
/**
* Start an instance of the process with the specified process definition id on behalf of a given user, and provides
* inputs to fulfill Process Contract.
* See {@link org.bonitasoft.engine.bpm.contract.ContractDefinition} for details on contracts.
*
* @param userId The identifier of the user in the name of whom the process is started.
* @param processDefinitionId
* The identifier of the process definition for which an instance will be started.
* @param instantiationInputs
* The couples of input name/value that allows to start a process with an instantiation contract.
* @return An instance of the process.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws ProcessDefinitionNotFoundException
* If no matching process definition is found.
* @throws ProcessActivationException
* If an exception occurs during activation.
* @throws ProcessExecutionException
* If a problem occurs when starting the process.
* @throws ContractViolationException
* If inputs don't fit with process contract
* @since 7.0.0
*/
ProcessInstance startProcessWithInputs(final long userId, final long processDefinitionId,
final Map instantiationInputs)
throws ProcessDefinitionNotFoundException, ProcessActivationException, ProcessExecutionException,
ContractViolationException;
/**
*
* Executes a flow node that is in a stable state.
* Will move the activity to the next stable state and then continue the execution of the process.
*
*
* Use this method only if you need to manually control the execution of a flownode.
* DO NOT USE THIS TO EXECUTE HUMAN TASKS. Use {@link #executeUserTask(long, Map)} instead.
*
*
* @param flownodeInstanceId
* The identifier of the flow node to execute.
* @throws FlowNodeExecutionException
* If an execution exception occurs.
* @since 6.0
*/
void executeFlowNode(long flownodeInstanceId) throws FlowNodeExecutionException;
/**
*
* Executes a flow node that is in a stable state on behalf of a given user
* Will make the flow node go in the next stable state and then continue the execution of the process
* If userId equals 0, the logged-in user is declared as the executer of the flow node.
* The user, who executed the flow node on behalf of a given user, is declared as a executer delegate.
*
*
* Use this method only if you need to manually control the execution of a flownode.
* DO NOT USE THIS TO EXECUTE HUMAN TASKS. Use {@link #executeUserTask(long, long, Map)} instead.
*
*
* @param userId
* The identifier of the user for which you want to execute the flow node
* @param flownodeInstanceId
* The identifier of the flow node to execute
* @throws FlowNodeExecutionException
* If an execution exception occurs
* @since 6.0.1
*/
void executeFlowNode(long userId, long flownodeInstanceId) throws FlowNodeExecutionException;
/**
* Returns all activities (active and finished) of a process instance.
*
* @param processInstanceId
* The identifier of the process instance,
* @param startIndex
* The index of the first result (starting from 0).
* @param maxResults
* The maximum number of results to get.
* @return The matching set of activity instances.
* @since 6.0
*/
List getActivities(long processInstanceId, int startIndex, int maxResults);
/**
* Get the specified process instance.
*
* @param processInstanceId
* The identifier of the process instance.
* @return The matching instance of process.
* @throws ProcessInstanceNotFoundException
* If there is no process instance with the specified identifier.
* @since 6.0
*/
ProcessInstance getProcessInstance(long processInstanceId) throws ProcessInstanceNotFoundException;
/**
* Get the specified activity instance.
*
* @param activityInstanceId
* The identifier of the activity instance.
* @return The matching activity instance.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws ActivityInstanceNotFoundException
* If the activity cannot be found.
* @throws org.bonitasoft.engine.exception.RetrieveException
* If the activity instance cannot be retrieved.
* @since 6.0
*/
ActivityInstance getActivityInstance(long activityInstanceId) throws ActivityInstanceNotFoundException;
/**
* Get a specified flow node instance.
*
* @param flowNodeInstanceId
* The identifier of the flow node instance.
* @return The matching flow node instance.
* @throws FlowNodeInstanceNotFoundException
* If the given flow node instance does not exist.
* @since 6.0
*/
FlowNodeInstance getFlowNodeInstance(final long flowNodeInstanceId) throws FlowNodeInstanceNotFoundException;
/**
* Get an activity instance that is archived.
*
* @param sourceActivityInstanceId
* The identifier of the source activity instance.
* @return The matching archived activity instance.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws ActivityInstanceNotFoundException
* If the archived activity instance cannot be found.
* @throws org.bonitasoft.engine.exception.RetrieveException
* If the archived activity instance cannot be retrieved.
* @since 6.0
*/
ArchivedActivityInstance getArchivedActivityInstance(long sourceActivityInstanceId)
throws ActivityInstanceNotFoundException;
/**
* Get the list of human task instances assigned to the specified user.
*
* @param userId
* The identifier of the user.
* @param startIndex
* The index of the first result (starting from 0).
* @param maxResults
* The maximum number of elements to get per page.
* @param criterion
* The sort criterion.
* @return The matching list of task instances.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* Occurs when the session is invalid.
* @throws org.bonitasoft.engine.exception.RetrieveException
* If a task instance cannot be retrieved.
* @since 6.0
*/
List getAssignedHumanTaskInstances(long userId, int startIndex, int maxResults,
ActivityInstanceCriterion criterion);
/**
* Get the list of pending human task instances available to the specified user.
* A human task is pending for a given user if it is not yet assigned and if the
* user is a candidate either through an {@link org.bonitasoft.engine.bpm.actor.ActorMember} or through a
* {@link org.bonitasoft.engine.filter.UserFilter}.
*
* @param userId
* The identifier of the user.
* @param startIndex
* The index of the first result (starting from 0).
* @param maxResults
* The maximum number of elements to get per page.
* @param pagingCriterion
* The criterion for sorting the items over pages.
* @return The list of matching task instances.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* Occurs when the session is invalid.
* @since 6.0
*/
List getPendingHumanTaskInstances(long userId, int startIndex, int maxResults,
ActivityInstanceCriterion pagingCriterion);
/**
* Count the total number of human task instances assigned to the specified user.
*
* @param userId
* The identifier of a user.
* @return A number of human task instances assigned.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws org.bonitasoft.engine.exception.RetrieveException
* If an error occurs while retrieving an instance of an activity.
* @since 6.0
*/
long getNumberOfAssignedHumanTaskInstances(long userId);
/**
* For a specified list of users, get the number of pending tasks.
*
* @param userIds
* A list of user identifiers.
* @return A map with userId as key and number of tasks as value.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws org.bonitasoft.engine.exception.RetrieveException
* can't retrieve an instance of activity
* @since 6.0
*/
Map getNumberOfOpenTasks(List userIds);
/**
* Count the number of pending human task instances available to a specified user.
*
* @param userId
* The identifier of a user.
* @return A number of pending human task instances.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws org.bonitasoft.engine.exception.RetrieveException
* If an error occurs while retrieving an instance of an activity.
* @since 6.0
*/
long getNumberOfPendingHumanTaskInstances(long userId);
/**
* Retrieve a human task instance by the corresponding activity instance id.
*
* @param activityInstanceId
* The identifier of the activity instance.
* @return The matching instance of human task.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws ActivityInstanceNotFoundException
* If the human task cannot be found.
* @throws org.bonitasoft.engine.exception.RetrieveException
* If an error occurs while retrieving the instance of the activity.
* @since 6.0
*/
HumanTaskInstance getHumanTaskInstance(long activityInstanceId) throws ActivityInstanceNotFoundException;
/**
* Get a list of event instances related to a process instance that match the specified conditions.
*
* @param rootContainerId
* The identifier of the containing root process instance.
* @param startIndex
* The index of the first result (starting from 0).
* @param maxResults
* The maximum number of results to get.
* @param sortingType
* The criterion for sorting event instances.
* @return The matching list of event instances.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @since 6.0
*/
List getEventInstances(long rootContainerId, int startIndex, int maxResults,
EventCriterion sortingType);
/**
* Assign a task to a user with given user identifier.
*
* @param userTaskId
* The identifier of the user task.
* @param userId
* The identifier of the user.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws UpdateException
* If an error occurs while updating the activity instance.
* @since 6.0
*/
void assignUserTask(long userTaskId, long userId) throws UpdateException;
/**
* Assign a task to a user with given user identifier if the task is not currently assigned to another user.
*
* @param userTaskId
* The identifier of the user task.
* @param userId
* The identifier of the user.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws UpdateException
* If an error occurs while updating the activity instance.
* @since 7.6
*/
void assignUserTaskIfNotAssigned(long userTaskId, long userId) throws UpdateException;
/**
* Updates the actors of the user task. It evaluates again the eligible users for that task.
*
* @param userTaskId
* The identifier of the user task
* @throws UpdateException
* If an exception occurs during the evaluation of actors.
* @since 6.1
*/
void updateActorsOfUserTask(long userTaskId) throws UpdateException;
/**
* Returns all data of a process instance.
*
* @param processInstanceId
* The identifier of the process instance.
* @param startIndex
* The index of the page of results to get (starting from 0).
* @param maxResults
* The maximum number of results to get.
* @return The matching list of dataInstances.
* @since 6.0
*/
List getProcessDataInstances(long processInstanceId, int startIndex, int maxResults);
/**
* Get the value of named data item from a specified process instance.
* The value is returned in a DataInstance object.
*
* @param dataName
* The name of the data item.
* @param processInstanceId
* The identifier of the process instance.
* @return An instance of the data
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws DataNotFoundException
* If the specified data value cannot be found.
* @since 6.0
*/
DataInstance getProcessDataInstance(String dataName, long processInstanceId) throws DataNotFoundException;
/**
*
* Update the value of a named process variable of a specified process instance.
*
*
* Warning: there is a known limitation about the usage of this method: if the new data value is of a custom
* data type AND
* the call to this method is performed from a java client configured to access Bonita Engine through HTTP,
* the API method call fails because the class of the custom data type cannot be loaded yet.
* The workaround to this limitation is to put the jar file containing your custom data
* type classes into the classloader of Bonita ([BONITA_INSTALLATION_FOLDER]/server/lib/bonita folder in a standard
* installation),
* and REMOVE it from the libraries of all the processes that use them.
*
*
* If the call is made from a standard Bonita bundle, the calls to Engine APIs are performed locally (and not
* through HTTP),
* so it does NOT fall into this limitation. So in a standard Bonita installation, it is safe to call this
* method in code like
* Rest API Extensions, Groovy scripts, Custom connector implementations...
*
*
* @param dataName
* The name of the data item.
* @param processInstanceId
* The identifier of the process instance.
* @param dataValue
* The new value for the data item.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws UpdateException
* If a problem occurs while updating the data value.
* @since 6.0
*/
void updateProcessDataInstance(String dataName, long processInstanceId, Serializable dataValue)
throws UpdateException;
/**
*
* Update the value of named process variables of a specified process instance.
*
*
* Warning: there is a known limitation about the usage of this method: if the new data value is of a custom
* data type AND
* the call to this method is performed from a java client configure to access Bonita Engine through HTTP,
* the API method call fails because the class of the custom data type cannot be loaded yet.
* The workaround to this limitation is to put the jar file containing your custom data
* type classes into the classloader of Bonita ([BONITA_INSTALLATION_FOLDER]/server/lib/bonita folder in a standard
* installation),
* and REMOVE it from the libraries of all the processes that use them.
*
*
* If the call is made from a standard Bonita bundle, the calls to Engine APIs are performed locally (and not
* through HTTP),
* so it does NOT fall into this limitation. So in a standard Bonita installation, it is safe to call this
* method in code like
* Rest API Extensions, Groovy scripts, Custom connector implementations...
*
*
* @param processInstanceId
* The identifier of the process instance.
* @param dataNameValues
* The mapping between the data name and its value to update to.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws UpdateException
* If a problem occurs while updating the data value.
* @since 6.2.3
*/
void updateProcessDataInstances(final long processInstanceId, final Map dataNameValues)
throws UpdateException;
/**
* Get a list of the data instances from a specified activity instance.
*
* @param activityInstanceId
* The identifier of the activity instance.
* @param startIndex
* The index of the first result (starting at 0).
* @param maxResults
* The maximum number of results to get.
* @return The list of matching DataInstances.
* @since 6.0
*/
List getActivityDataInstances(long activityInstanceId, int startIndex, int maxResults);
/**
* Get a named data instance from a specified activity instance.
*
* @param dataName
* The name of the data item.
* @param activityInstanceId
* The identifier of the activity instance.
* @return An instance of data.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws DataNotFoundException
* If the specified data value cannot be found.
* @since 6.0
*/
DataInstance getActivityDataInstance(String dataName, long activityInstanceId) throws DataNotFoundException;
/**
*
* Update the value of a named activity variable of a specified activity instance.
*
*
* Warning: there is a known limitation about the usage of this method: if the new data value is of a custom
* data type AND
* the call to this method is performed from a java client configure to access Bonita Engine through HTTP,
* the API method call fails because the class of the custom data type cannot be loaded yet.
* The workaround to this limitation is to put the jar file containing your custom data
* type classes into the classloader of Bonita ([BONITA_INSTALLATION_FOLDER]/server/lib/bonita folder in a standard
* installation),
* and REMOVE it from the libraries of all the processes that use them.
* Or use {@link ProcessRuntimeAPI#updateActivityInstanceVariables(List, long, Map)} instead
*
*
* If the call is made from a standard Bonita bundle, the calls to Engine APIs are performed locally (and not
* through HTTP),
* so it does NOT fall into this limitation. So in a standard Bonita installation, it is safe to call this
* method in code like
* Rest API Extensions, Groovy scripts, Custom connector implementations...
*
*
* @param dataName
* The name of the data instance.
* @param activityInstanceId
* The identifier of the activity instance.
* @param dataValue
* The new value of the data to set.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws UpdateException
* If an error occurs during the update.
* @since 6.0
*/
void updateActivityDataInstance(String dataName, long activityInstanceId, Serializable dataValue)
throws UpdateException;
/**
* Update the value of a named transient data instance in a specified activity instance.
*
* @param dataName
* The name of the data instance.
* @param activityInstanceId
* The identifier of the activity instance.
* @param dataValue
* The new value of the data to set.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws UpdateException
* If an error occurs during the update.
* @since 6.0
*/
void updateActivityTransientDataInstance(String dataName, long activityInstanceId, Serializable dataValue)
throws UpdateException;
/**
* Get a list of the transient data instances from a specified activity instance.
*
* @param activityInstanceId
* The identifier of the activity instance.
* @param startIndex
* The index of the first result (starting at 0).
* @param maxResults
* The maximum number of results to get.
* @return The list of matching DataInstances.
* @since 6.0
*/
List getActivityTransientDataInstances(long activityInstanceId, int startIndex, int maxResults);
/**
* Get a named transient data instance from a specified activity instance.
*
* @param dataName
* The name of the data item.
* @param activityInstanceId
* The identifier of the activity instance.
* @return An instance of data.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws DataNotFoundException
* If the specified data value cannot be found.
* @since 6.0
*/
DataInstance getActivityTransientDataInstance(String dataName, long activityInstanceId)
throws DataNotFoundException;
/**
* Get the date when the specified activity instance reached the given state.
*
* @param activityInstanceId
* The identifier of the activity instance.
* @param state
* The state of interest.
* @return The date at which the activity instance reached the state.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws org.bonitasoft.engine.exception.RetrieveException
* If an error occurs while retrieving the activity instance.
* @since 6.0
*/
Date getActivityReachedStateDate(long activityInstanceId, String state);
/**
*
* Update the value of named activity variables of a specified activity instance.
*
*
* Warning: there is a known limitation about the usage of this method: if the new data value is of a custom
* data type AND
* the call to this method is performed from a java client configure to access Bonita Engine through HTTP,
* the API method call fails because the class of the custom data type cannot be loaded yet.
* The workaround to this limitation is to put the jar file containing your custom data
* type classes into the classloader of Bonita ([BONITA_INSTALLATION_FOLDER]/server/lib/bonita folder in a standard
* installation),
* and REMOVE it from the libraries of all the processes that use them.
* Or use {@link ProcessRuntimeAPI#updateActivityInstanceVariables(List, long, Map)} instead
*
*
* If the call is made from a standard Bonita bundle, the calls to Engine APIs are performed locally (and not
* through HTTP),
* so it does NOT fall into this limitation. So in a standard Bonita installation, it is safe to call this
* method in code like Rest API Extensions, Groovy scripts, Custom connector implementations...
*
*
* @param activityInstanceId
* The activity identifier.
* @param variables
* A map which contains several pairs of variable name and value.
* @throws UpdateException
* If a problem occurs while updating one of the data instance value.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @since 6.0
*/
void updateActivityInstanceVariables(long activityInstanceId, Map variables)
throws UpdateException;
/**
* Update the values of variables in an activity instance using expressions.
*
* @param operations
* A sequence of operations on expressions that update the values variables.
* @param activityInstanceId
* The identifier of the activity instance.
* @param expressionContexts
* Store all information identifying the container that the data belongs to.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws UpdateException
* If an error occurs during the update.
* @since 6.0
*/
void updateActivityInstanceVariables(List operations, long activityInstanceId,
Map expressionContexts) throws UpdateException;
/**
* Update the due date of a task.
*
* @param userTaskId
* The identifier of the task to update.
* @param dueDate
* The new due date for the task.
* @throws UpdateException
* If the activity does not exist or the update cannot be fulfilled.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @since 6.0
*/
void updateDueDateOfTask(long userTaskId, Date dueDate) throws UpdateException;
/**
* Get an instance of a task asssigned to a given user for the specified process instance.
*
* @param processInstanceId
* The identifier of the process instance.
* @param userId
* The identifier of the user.
* @return The identifier of a user task from the process instance that is assigned to the user.
* @throws ProcessInstanceNotFoundException
* If the given process instance does not exist.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws UserNotFoundException
* If there is no user with the specified id.
* @throws org.bonitasoft.engine.exception.RetrieveException
* If an error occurs happen while retrieving the activity instance.
* @since 6.0
*/
long getOneAssignedUserTaskInstanceOfProcessInstance(long processInstanceId, long userId)
throws ProcessInstanceNotFoundException, UserNotFoundException;
/**
* Get an instance of a task asssigned to a given user for the specified process definition.
*
* @param processDefinitionId
* The identifier of the process definition.
* @param userId
* The identifier of a user.
* @return The identifier of a user task from the process definition that is assigned to the user.
* @throws ProcessDefinitionNotFoundException
* If the given process definition does not exist.
* @throws UserNotFoundException
* If the given user does not exist.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws org.bonitasoft.engine.exception.RetrieveException
* If an error occurs happen while retrieving the activity instance.
* @since 6.0
*/
long getOneAssignedUserTaskInstanceOfProcessDefinition(long processDefinitionId, long userId)
throws ProcessDefinitionNotFoundException,
UserNotFoundException;
/**
* Get the state of a specified activity instance.
*
* @param activityInstanceId
* The identifier of the activity instance.
* @return The state of the activity instance.
* @throws ActivityInstanceNotFoundException
* If the activity cannot be found.
* @since 6.0
*/
String getActivityInstanceState(long activityInstanceId) throws ActivityInstanceNotFoundException;
/**
* Check whether a specified task can be executed by a given user.
*
* @param activityInstanceId
* The identifier of the activity instance.
* @param userId
* The identifier of a user.
* @return A flag that indicates whether task can be executed by the user.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws ActivityInstanceNotFoundException
* If the activity cannot be found.
* @throws UserNotFoundException
* If there is no user with the specified userId.
* @throws org.bonitasoft.engine.exception.RetrieveException
* If an error occurs happen while retrieving the activity instance.
* @since 6.0
*/
boolean canExecuteTask(long activityInstanceId, long userId)
throws ActivityInstanceNotFoundException, UserNotFoundException;
/**
* Release a task (unclaim or unassign). After the operation, the task is in the pending task list.
*
* @param userTaskId
* The identifier of the user task.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws ActivityInstanceNotFoundException
* If the activity cannot be found.
* @throws UpdateException
* If a problem occurs while release (un-assigning) the user task.
* @since 6.0
*/
void releaseUserTask(long userTaskId) throws ActivityInstanceNotFoundException, UpdateException;
/**
* List the archived process instances for the specified process instance.
* A process instance is archived when it changes state, so there are several archived process instances for each
* process instance.
*
* @param processInstanceId
* The identifier of the process instance.
* @param startIndex
* The index of the page of results to get.
* @param maxResults
* The maximum number of results to get.
* @return The list of archived process instances.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If no current valid session is found.
* @throws org.bonitasoft.engine.exception.RetrieveException
* If the search fails because an archived process instance cannot be read.
* @since 6.0
*/
List getArchivedProcessInstances(long processInstanceId, int startIndex, int maxResults);
/**
* Get the last archived instance of a process instance.
* A process instance is archived when it changes state, so there are several archived process instances for each
* process instance.
* The last archived instance is returned.
*
* @param sourceProcessInstanceId
* The identifier of the source process instance, i.e. not an archived version, the original process instance
* id.
* @return The archived process instance.
* @throws ArchivedProcessInstanceNotFoundException
* If no archived process instance can be found with the provided Id.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If no current valid session is found.
* @throws org.bonitasoft.engine.exception.RetrieveException
* If the search fails because an archived process instance cannot be read.
* @since 6.0
*/
ArchivedProcessInstance getFinalArchivedProcessInstance(long sourceProcessInstanceId)
throws ArchivedProcessInstanceNotFoundException;
/**
* Set the state of an activity instance.
*
* @param activityInstanceId
* The identifier of the activity instance.
* @param stateId
* The identifier of the required state.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If no current valid session is found.
* @throws UpdateException
* If an error occurs during the update.
* @since 6.0
*/
void setActivityStateById(long activityInstanceId, int stateId) throws UpdateException;
/**
* Set the state of an activity instance.
*
* @param activityInstanceId
* The identifier of the activity instance.
* @param state
* The name of the required state.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If no current valid session is found.
* @throws UpdateException
* If an error occurs during the update.
* @since 6.0
*/
void setActivityStateByName(long activityInstanceId, String state) throws UpdateException;
/**
* Set a state of a process instance.
*
* @param processInstance
* The process instance.
* @param state
* The name of the required state.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws UpdateException
* If an error occurs during the update.
* @since 6.0
*/
void setProcessInstanceState(ProcessInstance processInstance, String state) throws UpdateException;
/**
* Set the priority of a user task.
*
* @param userTaskInstanceId
* The identifier of user task instance.
* @param priority
* The new priority of this task.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws UpdateException
* If an error occurs during the update.
* @since 6.0
*/
void setTaskPriority(long userTaskInstanceId, TaskPriority priority) throws UpdateException;
/**
* Execute a connector in a specified processDefinition.
*
* @param connectorDefinitionId
* The identifier of connector definition.
* @param connectorDefinitionVersion
* The version of the connector definition.
* @param connectorInputParameters
* The expressions related to the connector input paramters.
* @param inputValues
* The parameters values for expression needed when evaluating the connector.
* @param processDefinitionId
* The identifier of the process definition.
* @return A map with connector parameter names and parameter value objects.
* @throws ConnectorExecutionException
* If an error occurs during connector execution.
* @throws ConnectorNotFoundException
* If there is no connector definition with the specified identifier or version.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @since 6.0
*/
Map executeConnectorOnProcessDefinition(String connectorDefinitionId,
String connectorDefinitionVersion,
Map connectorInputParameters, Map> inputValues,
long processDefinitionId)
throws ConnectorExecutionException, ConnectorNotFoundException;
/**
* Execute a connector in a specified processDefinition with operations.
*
* @param connectorDefinitionId
* The identifier of connector definition.
* @param connectorDefinitionVersion
* The version of the connector definition.
* @param connectorInputParameters
* The expressions related to the connector input parameters.
* @param inputValues
* The parameters values for expression needed when evaluating the connector.
* @param operations
* The operations used when executing the connector.
* @param operationInputValues
* The input values for the operations.
* @param processDefinitionId
* The identifier of the process definition.
* @return A map with connector parameter names and parameter value objects after operations and connector
* execution.
* @throws ConnectorExecutionException
* If an error occurs during connector execution.
* @throws ConnectorNotFoundException
* If there is no connector definition with the specified identifier or version.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @since 6.0
*/
Map executeConnectorOnProcessDefinition(String connectorDefinitionId,
String connectorDefinitionVersion,
Map connectorInputParameters, Map> inputValues,
List operations,
Map operationInputValues, long processDefinitionId)
throws ConnectorExecutionException, ConnectorNotFoundException;
/**
* Search the archived human tasks for tasks that match the search options.
*
* @param searchOptions
* The search conditions and the options for sorting and paging the results. See
* {@link org.bonitasoft.engine.bpm.flownode.HumanTaskInstanceSearchDescriptor} for valid
* fields
* for searching and sorting.
* @return The archived human tasks that match the search conditions.
* @throws SearchException
* If the search could not be completed correctly.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @since 6.0
*/
SearchResult searchArchivedHumanTasks(SearchOptions searchOptions)
throws SearchException;
/**
* Search the assigned human tasks for tasks that match the search options and are administered by the specified
* user.
*
* @param managerUserId
* The identifier of the user.
* @param searchOptions
* The search conditions and the options for sorting and paging the results. See
* {@link org.bonitasoft.engine.bpm.flownode.HumanTaskInstanceSearchDescriptor} for valid fields for
* searching and sorting.
* @return The assigned human tasks that match the search conditions and are supervised by the user.
* @throws SearchException
* If there is an error in the search conditions.
* @since 6.0
*/
SearchResult searchAssignedTasksManagedBy(long managerUserId, SearchOptions searchOptions)
throws SearchException;
/**
* Search the pending human tasks for tasks that match the search options and are supervised by the specified user.
*
* @param userId
* The identifier of the user.
* @param searchOptions
* The search conditions and the options for sorting and paging the results. See
* {@link org.bonitasoft.engine.bpm.flownode.HumanTaskInstanceSearchDescriptor} for valid fields for
* searching and sorting.
* @return The pending human tasks that match the search conditions and are supervised by the user.
* @throws SearchException
* If there is an error in the search conditions.
* @since 6.0
*/
SearchResult searchPendingTasksSupervisedBy(long userId, SearchOptions searchOptions)
throws SearchException;
/**
* Search the pending human tasks for tasks available to the specified user.
*
* @param userId
* The identifier of the user.
* @param searchOptions
* The search conditions and the options for sorting and paging the results. See
* {@link org.bonitasoft.engine.bpm.flownode.HumanTaskInstanceSearchDescriptor} for valid fields for
* searching and sorting.
* @return The pending human tasks that match the search conditions and are available to the user.
* @throws SearchException
* If there is an error in the search conditions.
* @since 6.0
*/
SearchResult searchPendingTasksForUser(long userId, SearchOptions searchOptions)
throws SearchException;
/**
* Search the pending human tasks assigned to a specified user.
*
* @param userId
* The identifier of the user.
* @param searchOptions
* The search conditions and the options for sorting and paging the results. See
* {@link org.bonitasoft.engine.bpm.flownode.HumanTaskInstanceSearchDescriptor} for valid fields for
* searching and sorting.
* @return The pending human tasks that match the search conditions and are assigned to the user.
* @throws SearchException
* If there is an error in the search conditions.
* @since 7.5.5
*/
SearchResult searchPendingTasksAssignedToUser(long userId, SearchOptions searchOptions)
throws SearchException;
/**
* Search the pending human tasks for tasks that match the search options and are managed by the specified user.
*
* @param managerUserId
* The identifier of the user.
* @param searchOptions
* The search conditions and the options for sorting and paging the results. See
* {@link org.bonitasoft.engine.bpm.flownode.HumanTaskInstanceSearchDescriptor} for valid fields for
* searching and sorting.
* @return The pending human tasks that match the search conditions and are managed by the user.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws SearchException
* If there is an error in the search conditions.
* @since 6.0
*/
SearchResult searchPendingTasksManagedBy(long managerUserId, SearchOptions searchOptions)
throws SearchException;
/**
* Search the assigned and pending human tasks for the specified user, on the specified root process definition,
* corresponding to the options.
*
* @param rootProcessDefinitionId
* The identifier of the root process definition
* @param userId
* The identifier of the user
* @param searchOptions
* The search conditions and the options for sorting and paging the results. See
* {@link org.bonitasoft.engine.bpm.flownode.HumanTaskInstanceSearchDescriptor} for valid fields for
* searching and sorting.
* @return The assigned and pending human tasks
* @throws SearchException
* If there is an error in the search conditions.
* @since 6.3.3
*/
SearchResult searchAssignedAndPendingHumanTasksFor(final long rootProcessDefinitionId,
final long userId,
final SearchOptions searchOptions) throws SearchException;
/**
* Search the assigned and pending human tasks for any user, on the specified root process definition, corresponding
* to the options.
*
* @param rootProcessDefinitionId
* The identifier of the root process definition
* @param searchOptions
* The search conditions and the options for sorting and paging the results. See
* {@link org.bonitasoft.engine.bpm.flownode.HumanTaskInstanceSearchDescriptor} for valid fields for
* searching and sorting.
* @return The assigned and pending human tasks
* @throws SearchException
* If there is an error in the search conditions.
* @since 6.3.3
*/
SearchResult searchAssignedAndPendingHumanTasks(final long rootProcessDefinitionId,
final SearchOptions searchOptions)
throws SearchException;
/**
* Search the assigned and pending human tasks for any user corresponding to the options.
*
* @param searchOptions The search conditions and the options for sorting and paging the results. See
* {@link org.bonitasoft.engine.bpm.flownode.HumanTaskInstanceSearchDescriptor} for valid fields for
* searching and sorting.
* @return The assigned and pending human tasks
* @throws SearchException If there is an error in the search conditions.
* @since 7.6.1
*/
SearchResult searchAssignedAndPendingHumanTasks(final SearchOptions searchOptions)
throws SearchException;
/**
* Get the number of assigned and pending overdue tasks for the specified users.
*
* @param userIds
* A list of user identifiers.
* @return A map of user identifiers and numbers of overdue tasks.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @since 6.0
*/
Map getNumberOfOverdueOpenTasks(List userIds);
/**
* Cancels the process instance and all of its active flow nodes.
*
* @param processInstanceId
* The identifier of the root process instance.
* @throws ProcessInstanceNotFoundException
* If the process instance identifier does not refer to a process instance.
* @throws UpdateException
* If an exception occurs during the process instance canceling.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid (expired, unknown, ...)
* @since 6.0
*/
void cancelProcessInstance(long processInstanceId) throws ProcessInstanceNotFoundException, UpdateException;
/**
* Reset the state of a failed {@link org.bonitasoft.engine.bpm.flownode.FlowNodeInstance} to its previous state and
* then execute it. Pre-condition: the
* {@code FlowNodeInstance} must be in state FAILED. If this condition is not respected, a
* ActivityExecutionException is thrown.
* If the {@code FlowNodeInstance} contains failed
* {@link org.bonitasoft.engine.bpm.connector.ConnectorInstance}s, they will be re-executed. In the case
* where the connector execution fails again, the {@code FlowNodeInstance} will remain in failed state. There is not
* counter on the number of
* re-executions
*
* @param activityInstanceId
* The identifier of the {@code FlowNodeInstance} to be re-retried.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* when session is invalid, e.g. the session has expired.
* @throws ActivityInstanceNotFoundException
* when no {@code FlowNodeInstance} is found with the specified identifier.
* @throws ActivityExecutionException
* occurs if the current Flownode is not in FAILED state, or while resetting the state, or while executing
* the {@code FlowNodeInstance}.
* @since 6.0
* @see org.bonitasoft.engine.bpm.flownode.FlowNodeInstance
* @see org.bonitasoft.engine.bpm.connector.ConnectorInstance
*/
void retryTask(long activityInstanceId) throws ActivityInstanceNotFoundException, ActivityExecutionException;
/**
* When a matching BPM event couple messageInstance / waitingMessageEvent fails to execute and no failure handling
* has been successful, a log message
* indicates that this method can be called to try again the execution. The necessary parameters are also indicated.
*
* @param messageInstanceId the ID of the message instance to try to trigger again.
* @param waitingMessageEventId the ID of the waiting message event to try to trigger again.
* @throws ExecutionException if the execution failed. A more precise cause is given in the getCause() method.
*/
void executeMessageCouple(long messageInstanceId, long waitingMessageEventId) throws ExecutionException;
/**
* Evaluate an expression in the context of the specified process.
* Some context values can also be provided
*
* @param expression
* The expression to evaluate.
* @param context
* The context values that are provided for evaluating the expression.
* @param processDefinitionId
* The identifier of the process definition in which the expression is evaluated.
* @return The result of the evaluation.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If there is no current valid session.
* @throws ExpressionEvaluationException
* If an error occurs while evaluating the expression.
* @since 6.0
*/
Serializable evaluateExpressionOnProcessDefinition(Expression expression, Map context,
long processDefinitionId)
throws ExpressionEvaluationException;
/**
* Get the number of comments matching the search conditions.
*
* @param searchOptions
* The search conditions and the options for sorting and paging the results.
* @return The number of comments matching the search conditions.
* @throws SearchException
* If the search could not be completed correctly.
* @since 6.0
*/
long countComments(SearchOptions searchOptions) throws SearchException;
/**
* Get the number of attachments matching the search conditions.
*
* @param searchOptions
* The search conditions and the options for sorting and paging the results.
* @return The number of attachments matching the search conditions.
* @throws SearchException
* If the search could not be completed correctly.
* @since 6.0
*/
long countAttachments(SearchOptions searchOptions) throws SearchException;
/**
* Send a BPMN signal event. Invoking this method acts as executing a Throw Signal Event.
*
* @param signalName
* The signal name.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If there is no current valid session.
* @throws SendEventException
* If an exception occurs while sending signal.
* @since 6.0
*/
void sendSignal(String signalName) throws SendEventException;
/**
* Send a BPMN message event. Invoking this method acts as executing a Throw Message Event.
*
* @param messageName
* The message name.
* @param targetProcess
* An expression representing the target process name.
* @param targetFlowNode
* An expression representing the target flow node name. Optional parameter that can be used to explicitly
* set the target flow node if the
* message is caught by different flow nodes in the same process. If not necessary, pass null value.
* @param messageContent
* A key->value map containing the message data, with the data name as key.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If there is no current valid session.
* @throws SendEventException
* If an exception occurs while sending message.
* @since 6.0
*/
void sendMessage(String messageName, Expression targetProcess, Expression targetFlowNode,
Map messageContent)
throws SendEventException;
/**
* Send a BPMN message event, with message correlation. Invoking this method acts as executing a Throw Message
* Event.
*
* @param messageName
* The message name.
* @param targetProcess
* An expression representing the target process name.
* @param targetFlowNode
* An expression representing the target flow node name. Optional parameter that can be used to explicitly
* set the target flow node if the
* message is caught by different flow nodes in the same process. If not necessary, pass null value.
* @param messageContent
* A key->value map containing the message data, with the data name as key.
* @param correlations
* The message correlations (five maximum).
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If there is no current valid session.
* @throws SendEventException
* If there are too many correlations (more than 5) or an exception occurs while sending message.
* @since 6.0
*/
void sendMessage(String messageName, Expression targetProcess, Expression targetFlowNode,
Map messageContent,
Map correlations) throws SendEventException;
/**
* Delete messages until date and matching to search condition.
*
* @param creationDate
* The date until the messages will be deleted.
* @param searchOptions
* The optional search conditions for retrieve messages that will be removed.
* @return The number of message deleted
* @throws ExecutionException
* If the deletion could not be completed correctly.
* @since 7.10
*/
int deleteMessageByCreationDate(long creationDate, SearchOptions searchOptions) throws ExecutionException;
/**
* Retrieve an ArchivedProcessInstance specified by its identifier.
*
* @param archivedProcessInstanceId
* The identifier of the ArchivedProcessInstance to be retrieved.
* @return The ArchivedProcessInstance instance.
* @throws ArchivedProcessInstanceNotFoundException
* If the ArchivedProcessInstance was not found.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws org.bonitasoft.engine.exception.RetrieveException
* If an error occurs while trying to retrieve the ArchivedProcessInstance.
* @since 6.0
*/
ArchivedProcessInstance getArchivedProcessInstance(long archivedProcessInstanceId)
throws ArchivedProcessInstanceNotFoundException;
/**
* Retrieve an ArchivedFlowNodeInstance specified by its identifier.
*
* @param archivedFlowNodeInstanceId
* The identifier of the ArchivedFlowNodeInstance to be retrieved.
* @return The ArchivedFlowNodeInstance instance.
* @throws ArchivedFlowNodeInstanceNotFoundException
* If the ArchivedFlowNodeInstance was not found.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws org.bonitasoft.engine.exception.RetrieveException
* If an error occurs while trying to retrieve the ArchivedFlowNodeInstance.
* @since 6.0
*/
ArchivedFlowNodeInstance getArchivedFlowNodeInstance(long archivedFlowNodeInstanceId)
throws ArchivedFlowNodeInstanceNotFoundException;
/**
* Retrieve an ArchivedComment specified by its identifier.
*
* @param archivedCommentId
* The identifier of the ArchivedComment to be retrieved.
* @return The ArchivedComment instance.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws org.bonitasoft.engine.exception.RetrieveException
* If an error occurs while trying to retrieve the ArchivedComment.
* @throws NotFoundException
* If no ArchivedComment was found with the specified archivedCommentId.
* @since 6.0
*/
ArchivedComment getArchivedComment(long archivedCommentId) throws NotFoundException;
/**
* Search for connector instances.
*
* @param searchOptions
* The search conditions and the options for sorting and paging the results. See
* {@link org.bonitasoft.engine.bpm.connector.ConnectorInstancesSearchDescriptor} for valid fields for
* searching and sorting.
* @return The {@link SearchResult} containing the ConnectorInstances matching the search options.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws SearchException
* If the search could not be completed correctly.
* @since 6.0
*/
SearchResult searchConnectorInstances(SearchOptions searchOptions) throws SearchException;
/**
* Search for archived connector instances.
*
* @param searchOptions
* The search options parameters. See
* {@link org.bonitasoft.engine.bpm.connector.ArchiveConnectorInstancesSearchDescriptor} for valid fields for
* searching and sorting.
* @return The {@link SearchResult} containing the ArchivedConnectorInstances matching the search
* options.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws SearchException
* If the search could not be completed correctly.
* @since 6.0
*/
SearchResult searchArchivedConnectorInstances(SearchOptions searchOptions)
throws SearchException;
/**
* List the named human tasks belonging to the specified process instance.
*
* @param rootProcessInstanceId
* The identifier of the root process instance.
* @param taskName
* The name of the required human tasks.
* @param startIndex
* The result start index (strating from 0).
* @param maxResults
* The maximum number of results to retrieve.
* @return The list of matching human task instances.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @since 6.0
*/
List getHumanTaskInstances(long rootProcessInstanceId, String taskName, int startIndex,
int maxResults);
/**
* Return the last created human task instance with the specified name for the given process instance.
*
* @param rootProcessInstanceId
* The identifier of the root process instance.
* @param taskName
* The name of the required human task.
* @return A HumanTaskInstance, in its latest state.
* @throws NotFoundException
* If no current task with provided name is found.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @since 6.0
*/
HumanTaskInstance getLastStateHumanTaskInstance(long rootProcessInstanceId, String taskName)
throws NotFoundException;
/**
* Search for archived activity instances in terminal states. Archived activity instances in intermediate states are
* not considered.
*
* @param searchOptions
* The criterion used to search for archived activity instances. See
* {@link org.bonitasoft.engine.bpm.flownode.ArchivedActivityInstanceSearchDescriptor} for valid fields for
* searching and sorting.
* @return A {@link SearchResult} containing the search result.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws SearchException
* If an exception occurs during the search.
* @since 6.0
*/
SearchResult searchArchivedActivities(SearchOptions searchOptions) throws SearchException;
/**
* Search for activity instances.
*
* @param searchOptions
* The criterion used to search for activity instances. See
* {@link org.bonitasoft.engine.bpm.flownode.ActivityInstanceSearchDescriptor} for valid
* fields for searching and sorting.
* @return A {@link SearchResult} containing the search result.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws SearchException
* If the search could not be completed correctly.
* @since 6.0
*/
SearchResult searchActivities(SearchOptions searchOptions) throws SearchException;
/**
* Search for flow node instances (activities, gateways and events).
*
* @param searchOptions
* The criterion used to search for flow node instances. See
* {@link org.bonitasoft.engine.bpm.flownode.FlowNodeInstanceSearchDescriptor} for valid
* fields for searching and sorting.
* @return A {@link SearchResult} containing the search result
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the ession is invalid, e.g session has expired.
* @throws SearchException
* If an exception occurs during the search.
* @since 6.0
*/
SearchResult searchFlowNodeInstances(SearchOptions searchOptions) throws SearchException;
/**
* Search for archived flow node instances (activities, gateways and events)
*
* @param searchOptions
* The options used to search for flow node instances. See
* {@link org.bonitasoft.engine.bpm.flownode.ArchivedFlowNodeInstanceSearchDescriptor} for
* valid fields for searching and sorting.
* @return A {@link SearchResult} containing the search result.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g session has expired.
* @throws SearchException
* If an exception occurs during the search.
* @see ArchivedFlowNodeInstance
* @since 6.0
*/
SearchResult searchArchivedFlowNodeInstances(SearchOptions searchOptions)
throws SearchException;
/**
* Search for all tasks available to a specified user.
* A task is available to a user if is assigned to the user or it is pending for that user.
*
* @param userId
* The identifier of the user for whom the tasks are available.
* @param searchOptions
* The options used to search for tasks. See
* {@link org.bonitasoft.engine.bpm.flownode.HumanTaskInstanceSearchDescriptor} for valid fields for
* searching and sorting.
* @return The list of tasks matching the search options.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the current session is invalid.
* @throws SearchException
* If an exception occurs during the search.
* @since 6.0
*/
SearchResult searchMyAvailableHumanTasks(long userId, SearchOptions searchOptions)
throws SearchException;
/**
* Search for all tasks assigned to the user or taken by others users, or pending for that user.
*
* @param userId
* The identifier of the user for whom the tasks are available.
* @param searchOptions
* The options used to search for tasks. See
* {@link org.bonitasoft.engine.bpm.flownode.HumanTaskInstanceSearchDescriptor} for valid fields for
* searching and sorting.
* @return The list of tasks matching the search options.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the current session is invalid.
* @throws SearchException
* If an exception occurs during the search.
* @since 7.15
*/
SearchResult searchPendingOrAssignedToUserOrAssignedToOthersTasks(long userId,
SearchOptions searchOptions)
throws SearchException;
/**
* Search for comments related to the specified process instance.
*
* @param searchOptions
* The options used to search for comments. See
* {@link org.bonitasoft.engine.bpm.comment.SearchCommentsDescriptor} for valid fields for searching
* and sorting.
* @return The matching comments.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws SearchException
* If an exception occurs during the search.
* @since 6.0
*/
SearchResult searchComments(SearchOptions searchOptions) throws SearchException;
/**
* Add a comment on a process instance. Be aware that operations inside tasks are executed by the System, not the
* task assignee.
* Therefore, when called from an operation inside a task, the user "System" will be marked as having made the
* comment. If you wish to add a comment made by the assigned user in those places,
* use addProcessCommentOnBehalfOfUser.
*
* @param processInstanceId
* The identifier of the process instance.
* @param comment
* The content of the comment.
* @return The newly created comment.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws CreationException
* If the parameter processInstanceId does not refer to any active process instance (existing and
* non-archived).
* @since 6.1
*/
Comment addProcessComment(final long processInstanceId, final String comment) throws CreationException;
/**
* Add a comment on a process instance, on behalf of an user. Mainly intended to be used in groovy scripts when the
* behavior of the addProcessComment might be unsatisfactory.
*
* @param processInstanceId
* The identifier of the process instance.
* @param comment
* The content of the comment.
* @param userId
* The user that will be said to have made the comment
* @return The newly created comment.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws CreationException
* If the parameter processInstanceId does not refer to any active process instance (existing and
* non-archived).
* @since 7.7
*/
Comment addProcessCommentOnBehalfOfUser(final long processInstanceId, final String comment, long userId)
throws CreationException;
/**
* Get all the comments managed by the specified user.
* A comment is considered to be managed by user A if one or more of the following conditions is true:
* - the author of the comment is a subordinate of user A (A the author's manager).
* - the comment belongs to a process started by a subordinate of user A.
* - the comment belongs to a process where at least one human task is assigned to a subordinate of user A.
*
* @param managerUserId
* The identifier of the user.
* @param searchOptions
* The options used to search for comments. See
* {@link org.bonitasoft.engine.bpm.comment.SearchCommentsDescriptor} for valid fields for searching and
* sorting.
* @return The comments managed by the user that match the search options.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws SearchException
* If the search could not be completed correctly.
* @since 6.0
*/
SearchResult searchCommentsManagedBy(long managerUserId, SearchOptions searchOptions)
throws SearchException;
/**
* Get the comments on process instances that the specified user can access.
*
* @param userId
* The identifier of the user.
* @param searchOptions
* The options used to search for comments. See
* {@link org.bonitasoft.engine.bpm.comment.SearchCommentsDescriptor} for valid fields for searching and
* sorting.
* @return The comments on process instances that the user can access.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws SearchException
* If the search could not be completed correctly.
* @since 6.0
*/
SearchResult searchCommentsInvolvingUser(long userId, SearchOptions searchOptions) throws SearchException;
/**
* Get the children instances (sub process or call activity) of a process instance. The returned list is paginated.
* It does not return the process instance of the given id (itself).
*
* @param processInstanceId
* The identifier of the process instance.
* @param startIndex
* The index of the page to be returned (starting at 0).
* @param maxResults
* The maximum number of results per page.
* @param criterion
* The criterion used to sort the result.
* @return The list of children instance identifiers.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @since 6.0
*/
List getChildrenInstanceIdsOfProcessInstance(long processInstanceId, int startIndex, int maxResults,
ProcessInstanceCriterion criterion);
/**
* Check whether a specific user is involved in a given process instance.
* User A is involved with a process instance if any of the following is true:
*
* - user A has started the process instance
* - a task in the process instance is assigned to user A
* - a task in the process instance is pending for user A
* - a task in the process instance has been performed by user A
*
* This method also applies to completed instances of process.
*
* @param userId
* The identifier of the user.
* @param processInstanceId
* The identifier of the process instance.
* @return True if the user is involved with the process instance.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws ProcessInstanceNotFoundException
* If there is no processInstance with the specified identifier.
* @throws UserNotFoundException
* If there is no user with the specified identifier.
* @since 6.0
* @see #isManagerOfUserInvolvedInProcessInstance(long, long)
*/
boolean isInvolvedInProcessInstance(long userId, long processInstanceId)
throws ProcessInstanceNotFoundException, UserNotFoundException;
/**
* Check whether a specific user is involved in a given human task instance.
* User A is involved with a human task instance if any of the following is true:
*
* - the human task instance is assigned to user A
* - the human task instance is pending for user A
*
*
* @param userId
* The identifier of the user.
* @param humanTaskInstanceId
* The identifier of the human task instance.
* @return True if the user is involved with the human task instance.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws ActivityInstanceNotFoundException
* If there is no the human task instance with the specified identifier.
* @since 6.5.1
* @see #isManagerOfUserInvolvedInProcessInstance(long, long)
*/
boolean isInvolvedInHumanTaskInstance(long userId, long humanTaskInstanceId)
throws ActivityInstanceNotFoundException, UserNotFoundException;
/**
* Check whether a specific user has at least one subordinate (person he / she is the manager of) involved in a
* given process instance.
* User A is involved with a process instance if any of the following is true:
*
* - user A has started the process instance
* - a task in the process instance is assigned to user A
* - a task in the process instance is pending for user A
* - a task in the process instance has been performed by user A
*
* This method also applies to completed instances of process.
*
* @param managerUserId the ID of the manager of the user involved.
* @param processInstanceId the ID of the process instance we are interested in.
* @return true if the specified manager has subordinates involved in the given process instance.
* @throws ProcessInstanceNotFoundException if the process instance does not exist.
* @throws BonitaException if an error occurred while searching for users involved.
* @since 6.4.2
* @see #isInvolvedInProcessInstance(long, long)
*/
boolean isManagerOfUserInvolvedInProcessInstance(long managerUserId, long processInstanceId) throws BonitaException;
/**
* Get the process instance id from an activity instance id.
*
* @param activityInstanceId
* The identifier of the activity instance.
* @return The corresponding process instance id.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws ProcessInstanceNotFoundException
* If there is no process instance with the specified identifier.
* @since 6.0
*/
long getProcessInstanceIdFromActivityInstanceId(long activityInstanceId) throws ProcessInstanceNotFoundException;
/**
* Get the process definition id from an process instance id.
*
* @param processInstanceId
* The identifier of the process instance.
* @return The corresponding process definition id.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws ProcessDefinitionNotFoundException
* If there is no process definition with the specified identifier.
* @since 6.0
*/
long getProcessDefinitionIdFromProcessInstanceId(long processInstanceId) throws ProcessDefinitionNotFoundException;
/**
* Get the process definition id from an activity instance id.
*
* @param activityInstanceId
* The identifier of the activity instance.
* @return The corresponding process definition id.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws ProcessDefinitionNotFoundException
* If no ProcessDefinition have an id corresponding to the parameter.
* @since 6.0
*/
long getProcessDefinitionIdFromActivityInstanceId(long activityInstanceId)
throws ProcessDefinitionNotFoundException;
/**
* Search for archived comments.
* -- ex: Retrieve comments of a given archived case --
*
*
* {@code
* public List retrieveComments(ProcessRuntimeAPI processRuntimeAPI, ArchivedProcessInstance archivedProcessInstance) {
* SearchOptions searchOptions = new SearchOptionsBuilder(0, Integer.MAX_VALUE)
* .filter(ArchivedCommentsSearchDescriptor.PROCESS_INSTANCE_ID, archivedProcessInstance.getSourceObjectId())
* .done();
* return processRuntimeAPI.searchArchivedComments(searchOptions).getResult();
* }
* }
*
*
* @param searchOptions
* The options used to search for comments. See
* {@link org.bonitasoft.engine.bpm.comment.ArchivedCommentsSearchDescriptor} for valid fields for
* searching and sorting.
* @throws InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @return The ArchivedComment items that match the search options.
* @throws SearchException
* If the search could not be completed correctly.
* @since 6.0
*/
SearchResult searchArchivedComments(SearchOptions searchOptions) throws SearchException;
/**
* Search for archived human tasks managed by the specified user.
*
* @param managerUserId
* The identifier of the user manager,
* @param searchOptions
* The options used to search for tasks. See
* {@link org.bonitasoft.engine.bpm.flownode.ArchivedHumanTaskInstanceSearchDescriptor} for valid fields
* for searching and sorting.
* @return The archived humanTask instances managed by the specified user that match the search options.
* @throws SearchException
* If the search could not be completed correctly.
* @since 6.0
*/
SearchResult searchArchivedHumanTasksManagedBy(long managerUserId,
SearchOptions searchOptions) throws SearchException;
/**
* Search for open process instances that the specified user can access.
*
* @param userId
* The identifier of the user.
* @param searchOptions
* The options used to search for process instance. See
* {@link org.bonitasoft.engine.bpm.process.ProcessInstanceSearchDescriptor} for valid fields
* for searching and sorting.
* @return The ProcessInstances that match the search options.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws SearchException
* If the search could not be completed correctly.
* @since 6.0
*/
SearchResult searchOpenProcessInstancesInvolvingUser(long userId, SearchOptions searchOptions)
throws SearchException;
/**
* Search for open process instances that all subordinates of the specified user can access.
*
* @param managerUserId
* The identifier of the user manager.
* @param searchOptions
* The search options (pagination, filter, order sort). See
* {@link org.bonitasoft.engine.bpm.process.ProcessInstanceSearchDescriptor} for valid
* fields for searching and sorting.
* @return The ProcessInstances that match the search options.
* @throws SearchException
* If the search could not be completed correctly.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @since 6.0
*/
SearchResult searchOpenProcessInstancesInvolvingUsersManagedBy(long managerUserId,
SearchOptions searchOptions) throws SearchException;
/**
* Search for archived root process instances. Only archived process instances in states COMPLETED, ABORTED,
* CANCELED and FAILED will be retrieved. Process instances started by call activities won't be retrieved.
* See {@link #searchArchivedProcessInstancesInAllStates(SearchOptions) searchArchivedProcessInstancesInAllStates}
* to search amoung any archived instance.
*
* @param searchOptions
* The search options (pagination, filter, order sort).
* @return The archived process instances that match the search options. See
* {@link org.bonitasoft.engine.bpm.process.ArchivedProcessInstancesSearchDescriptor} for valid fields for
* searching and sorting.
* @throws SearchException
* If the search could not be full filled correctly
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @since 6.0
*/
SearchResult searchArchivedProcessInstances(SearchOptions searchOptions)
throws SearchException;
/**
* Search for archived process instances (root and intermediate levels) in all states (even intermediate states).
* Depending on used filters several
* ArchivedProcessInstance will be
* retrieved for a single ProcessInstance (one for each reached state).
*
* @param searchOptions
* The search options (pagination, filter, order sort). See
* {@link org.bonitasoft.engine.bpm.process.ArchivedProcessInstancesSearchDescriptor} for
* valid fields for searching and sorting.
* @return The archived process instances in all states that match the search options.
* @throws SearchException
* If the search could not be completed correctly.
* @since 6.2
*/
SearchResult searchArchivedProcessInstancesInAllStates(SearchOptions searchOptions)
throws SearchException;
/**
* Search for archived process instances supervised by the specified user.
*
* @param userId
* The identifier of the user.
* @param searchOptions
* The search options (pagination, filter, order sort). See
* {@link org.bonitasoft.engine.bpm.process.ArchivedProcessInstancesSearchDescriptor} for
* valid fields for searching and sorting.
* @return The archived process instances supervised by the user that match the search options.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws SearchException
* If the search could not be completed correctly.
* @since 6.0
*/
SearchResult searchArchivedProcessInstancesSupervisedBy(long userId,
SearchOptions searchOptions) throws SearchException;
/**
* Search for archived process instances that the specified user can access.
*
* @param userId
* The identifier of the user.
* @param searchOptions
* The search options (pagination, filter, order sort). See
* {@link org.bonitasoft.engine.bpm.process.ArchivedProcessInstancesSearchDescriptor} for
* valid fields for searching and sorting.
* @return The archived process instances that the user can access that match the search options.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws SearchException
* If the search could not be completed correctly.
* @since 6.0
*/
SearchResult searchArchivedProcessInstancesInvolvingUser(long userId,
SearchOptions searchOptions) throws SearchException;
/**
* Search for human task instances.
*
* @param searchOptions
* The search options (pagination, filter, order sort). See
* {@link org.bonitasoft.engine.bpm.flownode.HumanTaskInstanceSearchDescriptor} for valid
* fields for searching and sorting.
* @return The human task instances that match the search options.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws SearchException
* If the search could not be completed correctly.
* @since 6.0
*/
SearchResult searchHumanTaskInstances(SearchOptions searchOptions) throws SearchException;
/**
* Search for tasks assigned to users supervised by the specified user.
*
* @param supervisorId
* The identifier of supervising user.
* @param searchOptions
* The search options (pagination, filter, order sort). See
* {@link org.bonitasoft.engine.bpm.flownode.HumanTaskInstanceSearchDescriptor} for valid
* fields for searching and sorting.
* @return The human task instances that match the search options.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws SearchException
* If the search could not be completed correctly.
* @since 6.0
*/
SearchResult searchAssignedTasksSupervisedBy(long supervisorId, SearchOptions searchOptions)
throws SearchException;
/**
* Search for archived tasks assigned to users supervised by the specified user.
*
* @param supervisorId
* The identifier of the supervising user.
* @param searchOptions
* The search options (pagination, filter, order sort). See
* {@link org.bonitasoft.engine.bpm.flownode.ArchivedHumanTaskInstanceSearchDescriptor} for
* valid fields for searching and sorting.
* @return The archived human task instances that match the search options.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid, e.g. the session has expired.
* @throws SearchException
* If the search could not be completed correctly.
* @since 6.0
*/
SearchResult searchArchivedHumanTasksSupervisedBy(long supervisorId,
SearchOptions searchOptions) throws SearchException;
/**
* Evaluate expressions with values valid at process instantiation scope.
*
* @param processInstanceId
* The identifier of the process instance.
* @param expressions
* The map of expressions to evaluate.
* @return The result of the expression execution. Content of the resulting map depends on the incoming expression
* map. The returned key is The name of the
* expression (or its content if name is empty), the returned value is the evaluated expression result.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* Generic exception thrown if API Session is invalid, e.g session has expired.
* @throws ExpressionEvaluationException
* Occurs when an exception is thrown during expression evaluation.
* @since 6.0
*/
Map evaluateExpressionsAtProcessInstanciation(long processInstanceId,
Map> expressions)
throws ExpressionEvaluationException;
/**
* Evaluate expressions with values valid on a completed process instance scope.
*
* @param processInstanceId
* The identifier of the process instance.
* @param expressions
* The map of expressions to evaluate.
* @return The result of the expression execution. Content of the resulting map depends on the incoming expression
* map. The returned key is The name of the
* expression (or its content if name is empty), the returned value is the evaluated expression result.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the API session is invalid, e.g session has expired.
* @throws ExpressionEvaluationException
* Occurs when an exception is thrown during expression evaluation.
* @since 6.0
*/
Map evaluateExpressionOnCompletedProcessInstance(long processInstanceId,
Map> expressions)
throws ExpressionEvaluationException;
/**
* Evaluate expressions with values valid on a process instance scope.
*
* @param processInstanceId
* The identifier of the process instance.
* @param expressions
* The map of expressions to evaluate.
* @return The result of the expression execution. Content of the resulting map depends on the incoming expression
* map. The returned key is The name of the
* expression (or its content if name is empty), the returned value is the evaluated expression result.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the API session is invalid, e.g session has expired.
* @throws ExpressionEvaluationException
* Occurs when an exception is thrown during expression evaluation.
* @since 6.0
*/
Map evaluateExpressionsOnProcessInstance(long processInstanceId,
Map> expressions)
throws ExpressionEvaluationException;
/**
* Evaluate expressions with values valid on a process definition scope.
*
* @param processDefinitionId
* The identifier of the process definition.
* @param expressions
* The map of expressions to evaluate.
* @return The result of the expression execution. Content of the resulting map depends on the incoming expression
* map. The returned key is The name of the
* expression (or its content if name is empty), the returned value is the evaluated expression result.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the API session is invalid, e.g session has expired.
* @throws ExpressionEvaluationException
* Occurs when an exception is thrown during expression evaluation.
* @since 6.0
*/
Map evaluateExpressionsOnProcessDefinition(long processDefinitionId,
Map> expressions)
throws ExpressionEvaluationException;
/**
* Evaluate expressions with values valid on an activity instance scope.
*
* @param activityInstanceId
* The identifier of the activity instance.
* @param expressions
* The map of expressions to evaluate.
* @return The result of the expression execution. Content of the resulting map depends on the incoming expression
* map. The returned key is The name of the
* expression (or its content if name is empty), the returned value is the evaluated expression result.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the API session is invalid, e.g session has expired.
* @throws ExpressionEvaluationException
* Occurs when an exception is thrown during expression evaluation.
* @since 6.0
*/
Map evaluateExpressionsOnActivityInstance(long activityInstanceId,
Map> expressions)
throws ExpressionEvaluationException;
/**
* Evaluate expressions with values valid on a completed activity instance scope.
*
* @param activityInstanceId
* The identifier of the activity instance.
* @param expressions
* The map of expressions to evaluate.
* @return The result of the expression execution. Content of the resulting map depends on the incoming expression
* map. The returned key is The name of the
* expression (or its content if name is empty), the returned value is the evaluated expression result.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the API session is invalid, e.g session has expired.
* @throws ExpressionEvaluationException
* Occurs when an exception is thrown during expression evaluation.
* @since 6.0
*/
Map evaluateExpressionsOnCompletedActivityInstance(long activityInstanceId,
Map> expressions)
throws ExpressionEvaluationException;
/**
* Returns the list of jobs that failed.
*
* @param startIndex
* The result start index (starting from 0).
* @param maxResults
* The maximum number of results to retrieve.
* @return The list of failed jobs.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid (expired, unknown, ...)
* @since 6.1
*/
List getFailedJobs(int startIndex, int maxResults);
/**
* Replay a job that failed.
* Job that failed can be found using {@link #getFailedJobs(int, int)}
* This will remove the traces of Failed Jobs and restart the job once.
* If you wish to re-execute multiple times the job that failed in case a recurrent job failed multiple times,
* call this method several times.
*
* @param jobDescriptorId
* The identifier of the job descriptor.
* @since 6.1
*/
void replayFailedJob(final long jobDescriptorId) throws ExecutionException;
/**
* Update parameters of a job and replay it.
* The specified parameters replace the stored parameters. i.e. If the job is recurrent, all
* future executions of this job will use the newly specified parameters.
*
* @param jobDescriptorId
* The identifier of the job descriptor.
* @param parameters
* The job parameters.
* @since 6.1
* @deprecated since 7.9, use {@link #replayFailedJob(long)} instead, parameters should not be modified.
*/
@Deprecated(since = "7.9", forRemoval = true)
void replayFailedJob(final long jobDescriptorId, Map parameters) throws ExecutionException;
/**
* Gets the last archived data instance of the named data of the specified process instance.
*
* @param dataName
* The name of the data
* @param sourceProcessInstanceId
* The identifier of the source process instance (used as root container id of the archived activity
* instances).
* @return An archived instance of data.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid (expired, unknown, ...)
* @throws ArchivedDataNotFoundException
* If the specified data cannot be found.
* @since 6.1
*/
ArchivedDataInstance getArchivedProcessDataInstance(String dataName, long sourceProcessInstanceId)
throws ArchivedDataNotFoundException;
/**
* Gets the last archived data instance of the named data of the specified activity instance.
*
* @param dataName
* The name of the data
* @param sourceActivityInstanceId
* The identifier of the source activity instance
* @return An archived instance of data.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid (expired, unknown, ...)
* @throws ArchivedDataNotFoundException
* If the specified data cannot be found
* @since 6.1
*/
ArchivedDataInstance getArchivedActivityDataInstance(String dataName, long sourceActivityInstanceId)
throws ArchivedDataNotFoundException;
/**
* Lists the last archived instances of data of the specified process instance.
*
* @param sourceProcessInstanceId
* The identifier of the source process instance (used as root container id of the archived activity
* instances).
* @param startIndex
* The start index
* @param maxResults
* The max number of archived data instances
* @return The list of archived data instances.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid (expired, unknown, ...)
* @throws org.bonitasoft.engine.exception.RetrieveException
* If an exception occurs while retrieving the archived instances of data
* @since 6.1
*/
List getArchivedProcessDataInstances(long sourceProcessInstanceId, int startIndex,
int maxResults);
/**
* Lists the last archived instances of data of the specified activity instance.
*
* @param sourceActivityInstanceId
* The identifier of the source activity instance
* @param startIndex
* The start index
* @param maxResults
* The max number of archived data instances
* @return The list of archived data instances.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid (expired, unknown, ...)
* @throws org.bonitasoft.engine.exception.RetrieveException
* If an exception occurs while retrieving the archived instances of data
* @since 6.1
*/
List getArchivedActivityDataInstances(long sourceActivityInstanceId, int startIndex,
int maxResults);
/**
* Lists the possible users (candidates) of the specified human task instance.
* Users are ordered by user name.
*
* @param humanTaskInstanceId
* The identifier of the human task instance
* @param startIndex
* The start index
* @param maxResults
* The max number of users
* @return The list of users.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid (expired, unknown, ...)
* @throws org.bonitasoft.engine.exception.RetrieveException
* If an exception occurs while retrieving the users
* @since 6.1
*/
List getPossibleUsersOfPendingHumanTask(long humanTaskInstanceId, int startIndex, int maxResults);
/**
* Lists the possible users (candidates) that can execute the specified human task instance.
* Users are ordered by user name.
*
* @param humanTaskInstanceId
* The identifier of the human task instance
* @param searchOptions
* the search options. See {@link org.bonitasoft.engine.identity.UserSearchDescriptor} for valid fields for
* searching and sorting.
* @return The list of users.
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid (expired, unknown, ...)
* @throws org.bonitasoft.engine.exception.RetrieveException
* If an exception occurs while retrieving the users
* @since 6.3
*/
SearchResult searchUsersWhoCanExecutePendingHumanTask(final long humanTaskInstanceId,
SearchOptions searchOptions);
/**
* Search process definitions that have instances with assigned or pending human tasks for a specific user.
* The tasks are in stable state, not in terminal/executing state.
*
* @param userId
* The identifier of the user.
* @param searchOptions
* The search criterion. See {@link org.bonitasoft.engine.bpm.process.ProcessDeploymentInfoSearchDescriptor}
* for valid fields for searching and
* sorting.
* @return The list of process definitions
* @throws SearchException
* if an exception occurs when getting the process deployment information.
* @since 6.3.3
*/
SearchResult searchProcessDeploymentInfosWithAssignedOrPendingHumanTasksFor(long userId,
SearchOptions searchOptions)
throws SearchException;
/**
* Search process definitions supervised by a specific user, that have instances with assigned or pending human
* tasks.
* The tasks are in stable state, not in terminal/executing state.
*
* @param supervisorId
* The identifier of the user.
* @param searchOptions
* The search criterion. See {@link org.bonitasoft.engine.bpm.process.ProcessDeploymentInfoSearchDescriptor}
* for valid fields for searching and
* sorting.
* @return The list of process definitions
* @throws SearchException
* if an exception occurs when getting the process deployment information.
* @since 6.3.3
*/
SearchResult searchProcessDeploymentInfosWithAssignedOrPendingHumanTasksSupervisedBy(
long supervisorId, SearchOptions searchOptions)
throws SearchException;
/**
* Search process definitions that have instances with assigned or pending human tasks.
* The tasks are in stable state, not in terminal/executing state.
*
* @param searchOptions
* The search criterion. See {@link org.bonitasoft.engine.bpm.process.ProcessDeploymentInfoSearchDescriptor}
* for valid fields for searching and
* sorting.
* @return The list of process definitions
* @throws SearchException
* If an exception occurs when getting the process deployment information.
* @since 6.3.3
*/
SearchResult searchProcessDeploymentInfosWithAssignedOrPendingHumanTasks(
SearchOptions searchOptions) throws SearchException;
/**
* Retrieve, for a given process definition, the current counters on active (not archived) flownodes.
*
* @param processDefinitionId ID of the process definition for which to retrieve the current indicators.
* @return A map of counters: the key is the name of the flownode, as defined at design-time. the value is the
* current counters for this flownode, that is,
* a map of <state name, number of current flownode in that state> (possible state names are: ready,
* executing, waiting, initializing, failed, completing)
* If no results, returns an empty Map.
* @throws ProcessDefinitionNotFoundException
* If not process definition exists with the ID processDefinitionId.
* @since 7.15.0
*/
Map> getActiveFlownodeStateCountersForProcessDefinition(final long processDefinitionId)
throws ProcessDefinitionNotFoundException;
/**
* Retrieve, for a given process instance, the current counters on flownodes. Please note: this method does not
* count the flownodes of sub-process instances
* of the given process instance.
*
* @param processInstanceId ID of the process instance for which to retrieve the current indicators.
* @return A map of counters: the key is the name of the flownode, as defined at design-time. the value is the
* current counters for this flownode, that is,
* a map of <state name, number of current flownode in that state> (possible state names are: ready,
* executing, waiting, initializing, failed, completing, completed, skipped, cancelled, aborted)
* If no results, returns an empty Map.
* @throws RetrieveException
* If not process instance exists with the ID processInstanceId.
* @since 6.5.0
*/
Map> getFlownodeStateCounters(long processInstanceId);
/**
* Search the {@link TimerEventTriggerInstance} on the specific {@link ProcessInstance}.
*
* @param searchOptions
* The search criterion.
* @return The list of the timer event triggers
* @throws SearchException
* If an exception occurs when getting the timer event triggers.
* @since 6.4.0
*/
SearchResult searchTimerEventTriggerInstances(long processInstanceId,
SearchOptions searchOptions) throws SearchException;
/**
* Change the date of the execution of a specific {@link TimerEventTriggerInstance}.
*
* @param timerEventTriggerInstanceId
* The identifier of the {@link TimerEventTriggerInstance} to update
* @param executionDate
* The new date of the execution of the {@link TimerEventTriggerInstance}
* @return The first fire time of the newly scheduled trigger is returned
* @throws TimerEventTriggerInstanceNotFoundException
* If the {@link TimerEventTriggerInstance} doesn't exist
* @throws UpdateException
* If an exception occurs when updating the {@link TimerEventTriggerInstance}
* @since 6.4.0
*/
Date updateExecutionDateOfTimerEventTriggerInstance(long timerEventTriggerInstanceId, Date executionDate)
throws TimerEventTriggerInstanceNotFoundException, UpdateException;
/**
* Gets the contract of the user task.
*
* @param userTaskId the identifier of the user task.
* @return the contract of the user task
* @throws UserTaskNotFoundException
* if identifier does not refer to a real user task.
*/
ContractDefinition getUserTaskContract(long userTaskId) throws UserTaskNotFoundException;
/**
* Gets the process instantiation contract for a given process definition.
*
* @param processDefinitionId the identifier of the process definition.
* @return the contract of the given process
* @throws ProcessDefinitionNotFoundException
* if identifier does not refer to an existing process definition.
*/
ContractDefinition getProcessContract(long processDefinitionId) throws ProcessDefinitionNotFoundException;
/**
* Executes a user task that is in a stable state.
* Will move the activity to the next stable state and then continue the execution of the process.
*
* @param userTaskInstanceId
* The identifier of the user task to execute.
* @param inputs
* the inputs used for user task execution
* @throws UserTaskNotFoundException
* If user task to execute is not found
* @throws ContractViolationException
* If inputs don't fit with task contract
* @throws FlowNodeExecutionException
* If an execution exception occurs
* @since 7.0
*/
void executeUserTask(long userTaskInstanceId, Map inputs)
throws UserTaskNotFoundException, ContractViolationException,
FlowNodeExecutionException;
/**
* Executes a user task that is in a stable state on behalf of a given user
* Will make the task go in the next stable state and then continue the execution of the process
* If userId equals 0, the logged-in user is declared as the executer of the task.
* The user, who executed the task on behalf of a given user, is declared as a executer delegate.
*
* @param userId
* The identifier of the user for which you want to execute the flow node
* @param userTaskInstanceId
* The identifier of the user task to execute
* @param inputs
* the input used for user task execution
* @throws UserTaskNotFoundException
* If user task to execute is not found
* @throws ContractViolationException
* If inputs don't fit with task contract
* @throws FlowNodeExecutionException
* If an execution exception occurs
* @since 7.0
*/
void executeUserTask(long userId, long userTaskInstanceId, Map inputs)
throws UserTaskNotFoundException, ContractViolationException,
FlowNodeExecutionException;
/**
* Assign a task to a user with given user identifier and executes a user task that is in a stable state on behalf
* of a given user
* Will make the task go in the next stable state and then continue the execution of the process
* If userId equals 0, the logged-in user is declared as the executer of the task.
* The user, who executed the task on behalf of a given user, is declared as a executer delegate.
*
* @param userId
* The identifier of the user for which you want to assign and execute the flow node
* @param userTaskInstanceId
* The identifier of the user task to execute
* @param inputs
* the input used for user task execution
* @throws UpdateException
* If an assignment exception occurs
* @throws UserTaskNotFoundException
* If user task to execute is not found
* @throws ContractViolationException
* If inputs don't fit with task contract
* @throws FlowNodeExecutionException
* If an execution exception occurs
* @since 7.9
*/
void assignAndExecuteUserTask(long userId, long userTaskInstanceId, Map inputs)
throws UpdateException, UserTaskNotFoundException, ContractViolationException,
FlowNodeExecutionException;
/**
* Gets the value of the variable of the user task contract.
*
* @param userTaskInstanceId
* The identifier of the user task
* @param name
* The name of the variable
* @return The identifier of the user task
* @throws ContractDataNotFoundException if no data found for the given user task instance and name.
*/
Serializable getUserTaskContractVariableValue(long userTaskInstanceId, String name)
throws ContractDataNotFoundException;
/**
* Gets the value of a process instantiation input, during the phase of initializing. For instance, if a connector
* on_enter fails, this method can be called
* to check the current value.
*
* @param processInstanceId The identifier of the process instance
* @param name The name of the process input to retrieve
* @return The identifier of the user task
* @throws ContractDataNotFoundException if no data found for the given process instance and name.
*/
Serializable getProcessInputValueDuringInitialization(long processInstanceId, String name)
throws ContractDataNotFoundException;
/**
* Gets the value of a process instantiation input, after initialization has finished. Requires Archiving feature to
* be enabled (default behaviour).
*
* @param processInstanceId The identifier of the process instance
* @param name The name of the process input to retrieve
* @return The identifier of the user task
* @throws ContractDataNotFoundException if identifier does not refer to an existing process instance.
*/
Serializable getProcessInputValueAfterInitialization(long processInstanceId, String name)
throws ContractDataNotFoundException;
/**
* return the context defined in the process definition for this user task instance. Context includes:
*
* - Business data references (see {@link org.bonitasoft.engine.business.data.BusinessDataReference},
* {@link org.bonitasoft.engine.business.data.SimpleBusinessDataReference} and
* {@link org.bonitasoft.engine.business.data.MultipleBusinessDataReference}).
* Key of
* data reference is the name of the business data as declared in process definition followed by "_ref".
*
- Documents reference (see {@link org.bonitasoft.engine.bpm.document.Document}). Naming convention is the same
* as for business data ("_ref" suffix).
*
- For multi-instantiated task only: iterator name with "_ref" suffix (type of the value is
* {@link org.bonitasoft.engine.business.data.BusinessDataReference}). By default: multiInstanceIterator_ref. Only
* exist if iterator value is set using
* a business variable.
*
-
*
*
* @param userTaskInstanceId the id of the user task instance
* @return a map containing the evaluated context
* @throws UserTaskNotFoundException if userTaskInstanceId does not reference any existing task.
*/
Map getUserTaskExecutionContext(long userTaskInstanceId)
throws UserTaskNotFoundException, ExpressionEvaluationException;
/**
* return the context defined in the process definition for this user task instance. Context includes:
*
* - Business data references (see {@link org.bonitasoft.engine.business.data.BusinessDataReference},
* {@link org.bonitasoft.engine.business.data.SimpleBusinessDataReference} and
* {@link org.bonitasoft.engine.business.data.MultipleBusinessDataReference}).
* Key of
* data reference is the name of the business data as declared in process definition followed by "_ref".
*
- Documents reference (see {@link org.bonitasoft.engine.bpm.document.Document}). Naming convention is the same
* as for business data ("_ref" suffix).
*
- For multi-instantiated task only: iterator name with "_ref" suffix (type of the value is
* {@link org.bonitasoft.engine.business.data.BusinessDataReference}). By default: multiInstanceIterator_ref. Only
* exist if iterator value is set using
* a business variable.
*
-
*
*
* @param archivedUserTaskInstanceId the id of the archived version of the user task instance
* @return a map containing the evaluated context
* @throws UserTaskNotFoundException if archivedUserTaskInstanceId does not reference any existing
* archived task.
*/
Map getArchivedUserTaskExecutionContext(long archivedUserTaskInstanceId)
throws UserTaskNotFoundException, ExpressionEvaluationException;
/**
* return the context defined in the process definition for this process instance. Context includes:
*
* - Business data references (see {@link org.bonitasoft.engine.business.data.BusinessDataReference},
* {@link org.bonitasoft.engine.business.data.SimpleBusinessDataReference} and
* {@link org.bonitasoft.engine.business.data.MultipleBusinessDataReference}).
* Key of
* data reference is the name of the business data as declared in process definition followed by "_ref".
*
- Documents reference (see {@link org.bonitasoft.engine.bpm.document.Document}). Naming convention is the same
* as for business data ("_ref" suffix).
*
*
* @param processInstanceId the id of the process instance
* @return a map containing the evaluated context
* @throws ProcessInstanceNotFoundException if processInstanceId does not reference any existing
* process.
*/
Map getProcessInstanceExecutionContext(long processInstanceId)
throws ProcessInstanceNotFoundException, ExpressionEvaluationException;
/**
* return the context defined in the process definition for this process instance. Context includes:
*
* - Business data references (see {@link org.bonitasoft.engine.business.data.BusinessDataReference},
* {@link org.bonitasoft.engine.business.data.SimpleBusinessDataReference} and
* {@link org.bonitasoft.engine.business.data.MultipleBusinessDataReference}).
* Key of
* data reference is the name of the business data as declared in process definition followed by "_ref".
*
- Documents reference (see {@link org.bonitasoft.engine.bpm.document.Document}). Naming convention is the same
* as for business data ("_ref" suffix).
*
*
* @param archivedProcessInstanceId the id of the archived version of a process instance. You can use
* {@link #getFinalArchivedProcessInstance(long)} to get
* the id of an archived instance based on the id of the same instance while it was running.
* @return a map containing the evaluated context
* @throws ProcessInstanceNotFoundException if archivedProcessInstanceId does not reference any
* existing process.
*/
Map getArchivedProcessInstanceExecutionContext(long archivedProcessInstanceId)
throws ProcessInstanceNotFoundException, ExpressionEvaluationException;
/**
* Update an instance of process with the given processInstanceId.
*
* @param processInstanceId
* Identifier of the process instance
* @param updater
* including new value of all attributes adaptable
* @return the updated process instance
* @throws ProcessInstanceNotFoundException if no process instance can be found with id processInstanceId.
* @throws UpdateException
* if an error is thrown while updating the process instance.
* @throws InvalidSessionException
* if the session is invalid, e.g. the session has expired.
* @since 6.0
*/
ProcessInstance updateProcessInstance(long processInstanceId,
org.bonitasoft.engine.bpm.process.impl.ProcessInstanceUpdater updater)
throws ProcessInstanceNotFoundException, UpdateException;
/**
* Update a search key of a process instance, also known as string index.
*
* @param processInstanceId
* identifier of the process instance
* @param index the search to update
* @param value
* the new value for the search key
* @return the updated process instance
* @throws ProcessInstanceNotFoundException
* Error thrown if no process instance have an id corresponding to the value of processInstanceId parameter.
* @throws UpdateException
* if an error is thrown while updating the process instance.
* @throws InvalidSessionException
* if the session is invalid, e.g. the session has expired.
* @since 7.12.0
*/
ProcessInstance updateProcessInstanceIndex(long processInstanceId, Index index, String value)
throws ProcessInstanceNotFoundException, UpdateException;
}