Package com.orchestranetworks.workflow

Class WorkflowEngine

java.lang.Object
com.orchestranetworks.workflow.WorkflowEngine
public final class WorkflowEngine extends Object
Represents the workflow engine and offers some administration functionalities.

  • Method Details

    • getFromRepository

      public static WorkflowEngine getFromRepository(Repository aRepository, Session aSession)
      Creates a workflow engine from a repository and, optionally, a session.
      Parameters:
      aRepository - repository in which the workflow is running.
      aSession - optional user session, must only be defined in order to invoke methods that require information about the current user: isUserInRoleAdmin, allocateWorkItem(WorkItemKey, UserReference), deallocateWorkItem(WorkItemKey), reallocateWorkItem(WorkItemKey, UserReference) and terminateProcessInstance.

    • getFromProcedureContext

      public static WorkflowEngine getFromProcedureContext(ProcedureContext aContext)

    • getFromServiceContext

      @Deprecated public static WorkflowEngine getFromServiceContext(ServiceContext aContext)
      Deprecated.

    • getFromUserServiceContext

      public static WorkflowEngine getFromUserServiceContext(UserServiceRequest aContext)
      Creates a workflow engine from a user service context.
      Since:
      6.0.0

    • isUserInRoleAdmin

      public boolean isUserInRoleAdmin(PublishedProcessKey aKey)
      Returns true if the user of the current session is the administrator of the process definition associated with the specified publication key.
      Throws:
      IllegalStateException - if the session of the workflow engine is null.

    • isUserAuthorizedToLaunch

      public boolean isUserAuthorizedToLaunch(PublishedProcessKey aKey)
      Returns true if the user of the current session is authorized to launch a workflow for the specified publication key.
      Returns:
      a Boolean
      Throws:
      IllegalStateException - if the session of the workflow engine is null.
      Since:
      6.0.10

    • getProcessLauncher

      public ProcessLauncher getProcessLauncher(PublishedProcessKey aKey)
      Returns a launcher to create workflows from the specified publication.
      Throws:
      IllegalStateException - if the session of the workflow engine is null.

    • forceTerminationWithoutCleaning

      public void forceTerminationWithoutCleaning(ProcessInstanceKey aKey)
      Terminates the specified process instance without deleting it. Contrary to the method terminateProcessInstance(ProcessInstanceKey), this method does not delete the process instance. It only deletes the objects associated with the current process instance (work items, interactions, sub-workflows).

      The current user must have the permission to perform the administration action 'Force termination' (unless this method is called from a procedure with all privileges).

      This method can only be used in order to force termination of sub-workflows in order to wake up the parent, or to force the termination of a process instance if an error has occurred during normal completion.

      Since:
      5.5.0
      See Also:

    • terminateProcessInstance

      public void terminateProcessInstance(ProcessInstanceKey aKey)
      Terminates and cleans the specified process instance.

      The current user must have the permissions for the administration action 'Terminate and clean' (unless this method is called from a procedure with all privileges).

      Throws:
      IllegalStateException - if the session of the workflow engine is null
      IllegalArgumentException - if the process instance to clean is a sub-workflow.
      See Also:

    • replayCurrentStep

      public void replayCurrentStep(ProcessInstanceKey aKey) throws OperationException
      Replays the current step of the specified workflow.

      This action removes all objects linked to the current step (current work items, interaction, sub-workflows) and restarts it. If an action has already been performed by a user, no rollback is done (for example in the record creation case).

      Parameters:
      aKey - the workflow identifier
      Throws:
      IllegalStateException - if the session of the workflow engine is null
      IllegalArgumentException - if the specified workflow key is null.
      OperationException - if one of the following occurs:
      • the user has no permission to replay the step (unless this method is called from a procedure with all privileges),
      • the workflow has not been found,
      • an unexpected error occurs during the current step restart.
      Since:
      5.7.1-fix N

    • resumeWaitTask

      public WaitTaskResumeResult resumeWaitTask(WaitTaskResumeMessage aMessage) throws OperationException
      Resumes a wait task.

      The resume identifier is required to resume a wait task by a WaitTaskResumeMessage.

      The resumption can fail if:

      • the associated workflow has been deleted,
      • the resume identifier has not been found,
      • the workflow and the associated task are not in a waiting state (if the event has already been received).

      In these cases, no exception is thrown, but the WaitTaskResumeResult contains the reason of the resumption failure.

      Returns:
      a WaitTaskResumeResult to indicate if the resumption has failed, and in this case the error reason.
      Throws:
      OperationException - If an unexpected error occurs during the wait task resumption.
      IllegalStateException - If the session of the workflow engine is null.
      IllegalArgumentException - If the user is not allowed to resume the wait task (if the user does not belong to the expected profile).
      Since:
      5.6.1

    • allocateWorkItem

      public void allocateWorkItem(WorkItemKey aKey, UserReference aUser)
      Allocates the specified work item to the specified user.

      The work item must be in the 'Offered' state, and the current user must have the permission to perform the administration action 'Allocate' (unless this method is called from a procedure with all privileges).

      After this method is called, the work item is in the 'Allocated' state.

      Parameters:
      aUser - the new owner of the work item. Even if an offered role is defined for the work item, the workflow engine does not check that the new owner of the work item belongs to the offered role.
      Throws:
      IllegalStateException - if the session of the workflow engine is null.
      IllegalArgumentException - if the work item is not in the 'Offered' state.
      See Also:

    • deallocateWorkItem

      public void deallocateWorkItem(WorkItemKey aKey)
      Deallocates the specified work item.

      The work item must be in the 'Allocated' or 'Started' state, and users must be available for allocation. The current user must have the permission to perform the administration action 'Deallocate' (unless this method is called from a procedure with all privileges).

      After this method is called, the work item is in the 'Offered' state.

      Throws:
      IllegalStateException - if the session of the workflow engine is null.
      IllegalArgumentException - if one of the following occurs:
      • the work item is not in the 'Allocated' or 'Started' state,
      • the current user is not allowed for this action.

    • reallocateWorkItem

      public void reallocateWorkItem(WorkItemKey aKey, UserReference aUser)
      Reallocates the specified work item.

      The work item must be in the 'Allocated' or 'Started' state, and the current user must have the permission to perform the administration action 'Reallocate' (unless this method is called from a procedure with all privileges).

      After this method is called, the work item is in the 'Allocated' state.

      Parameters:
      aUser - the new owner of the work item. No verification is performed on the user. If an offered role is specified, it is not enforced.
      Throws:
      IllegalStateException - if one of the following occurs: if the session of the workflow engine is null.
      IllegalArgumentException - if one of the following occurs:
      • the work item is not in the 'Allocated' or 'Started' state,
      • the current user is not allowed for this action.

    • allocateWorkItemToMyself

      public void allocateWorkItemToMyself(WorkItemKey aWorkItemKey) throws OperationException
      Allocates a work item to the current user.

      The work item must be in the offered state, and offered to the current user. After calling this method, the work item will be in the allocated state.

      Throws:
      IllegalStateException - if the session of the workflow engine is null.
      OperationException - if one of the following occurs:
      • the work item has not been found,
      • the work item is not in the offered state,
      • the work item is not offered to the current user.
      Since:
      5.7.1 fix D
      See Also:

    • createOrOpenInteraction

      public SessionInteraction createOrOpenInteraction(WorkItemKey aWorkItemKey) throws OperationException
      Creates or opens the interaction associated with the specified work item.

      The work item must be allocated to the current user, and either in the allocated or in the started state. If the work item is in the offered state, first call the allocateWorkItemToMyself(WorkItemKey) method (see the work item state diagram).

      This method does the following:

      1. If the work item is in the allocated state, it is started.
      2. If the interaction does not exist, it is created and initialized according to the mapping of the input parameters.
      3. Then, if the interaction is associated to an auto-complete service, the interaction is set in the 'complete' state; see the SessionInteraction life cycle. A custom user service is considered as auto-complete if it has been declared as auto-complete (see WebComponentDeclarationContext.setAvailableAsWorkflowUserTask(boolean, boolean). The following built-in services (or extensions of these services) can be considered as auto-complete too:
      Throws:
      IllegalStateException - if: the session of the workflow engine is null.
      OperationException - if one of the following occurs:
      • the work item has not been found,
      • the work item is not in the allocated state neither in the started state,
      • the work item is not allocated to or started by the current user.
      Since:
      5.7.1 fix D

    • getInteractionSpecification

      public SessionInteraction.Specification getInteractionSpecification(WorkItemKey aWorkItemKey)
      Returns the specification of a session interaction.

      Returns null if the work item has not been found.

      Throws:
      IllegalArgumentException - if the work item key is null.
      Since:
      5.8.0
      See Also:

    • getWorkflowPublisher

      public WorkflowPublisher getWorkflowPublisher() throws OperationException
      Retrieves an instance of the WorkflowPublisher class.

      This method is used to obtain an instance of the WorkflowPublisher class, which is responsible for publishing workflows. It is typically called to publish a model.

      Returns:
      An instance of WorkflowPublisher.
      Throws:
      IllegalStateException - If the user session is null, indicating that a session is required to invoke this method.
      OperationException - If any operation-specific exception occurs while creating the WorkflowPublisher instance.
      Since:
      6.1.3
      See Also:

    • getPublishedKeys

      public List<PublishedProcessKey> getPublishedKeys()
      Returns the enabled publication keys.
      Returns:
      a List of PublishedProcessKey.
      See Also:

    • getPublishedKeys

      public List<PublishedProcessKey> getPublishedKeys(boolean onlyEnabled)
      Returns the publication keys.
      Parameters:
      onlyEnabled - if true returns only the keys of enabled publications, else returns all keys regardless of the publication state.
      Returns:
      a List of PublishedProcessKey.

    • getPublishedProcess

      public PublishedProcess getPublishedProcess(PublishedProcessKey aPublishProcessKey)
      Returns information about the specified workflow publication.

    • getProcessInstanceKeys

      public List<ProcessInstanceKey> getProcessInstanceKeys(PublishedProcessKey aKey)
      Returns a list containing all existing process instance keys for the specified publication key.

      This method returns only execution data. As a consequence, it does not return deleted processes.

      See Also:

    • getProcessInstanceKeys

      public List<ProcessInstanceKey> getProcessInstanceKeys(String aLaunchingPublicationName)
      Returns a list containing all existing workflow keys for the specified launching publication name.

      This method returns all workflows which have been launched with the specified publication name (initial or current publication name), including workflows associated with a disabled publication.

      This method returns only execution data. As a consequence, it does not return deleted processes.

      Parameters:
      aLaunchingPublicationName - publication name with which workflows have been launched.
      Throws:
      IllegalArgumentException - if the publication is not defined.
      Since:
      5.9.0
      See Also:

    • getProcessInstanceKeysFromHistory

      public List<ProcessInstanceKey> getProcessInstanceKeysFromHistory(PublishedProcessKey aKey)
      Returns a list containing all the process instance keys for the specified publication key, including deleted processes.

      Unlike getProcessInstance(ProcessInstanceKey), this method will query directly the workflow history.

      Parameters:
      aKey - a specified PublishedProcessKey
      Throws:
      IllegalArgumentException - if the specified PublishedProcessKey is null.
      Since:
      5.8.1
      See Also:

    • getProcessInstanceKeysFromHistory

      public List<ProcessInstanceKey> getProcessInstanceKeysFromHistory(String aLaucnhingPublicationName) throws IllegalArgumentException, OperationException
      Returns a list containing all existing workflow keys for the specified launching publication name, including deleted workflows.

      This method returns all workflows from history which have been launched with the specified publication name (initial or current publication name), including workflows associated with a disabled publication.

      This method will query directly the workflow history.

      Parameters:
      aLaucnhingPublicationName - publication name with which workflows have been launched.
      Throws:
      IllegalArgumentException - if the publication is not defined.
      OperationException
      Since:
      5.9.0
      See Also:

    • getProcessInstance

      public ProcessInstance getProcessInstance(ProcessInstanceKey aProcessInstanceKey)
      Returns information about the specified workflow.

    • getProcessInstanceHistory

      public ProcessInstanceHistory getProcessInstanceHistory(ProcessInstanceKey aProcessInstanceKey) throws OperationException
      Returns the history of the specified workflow.
      Parameters:
      aProcessInstanceKey - the key of a workflow, which can represent a completed workflow.
      Throws:
      OperationException
      Since:
      5.4.1

    • getProcessInstanceComments

      public List<ProcessInstanceComment> getProcessInstanceComments(ProcessInstanceKey aProcessInstanceKey)
      Returns the comments of the specified workflow.

      The result includes comments of the sub-workflows of the specified workflow in a recursive way. The list of comments is sorted by descending date.

      If the associated workflow has not been found, returns an empty list.

      Throws:
      IllegalArgumentException - if the process instance key is null.
      Since:
      5.8.0

    • getWorkItem

      public UserTask.WorkItem getWorkItem(WorkItemKey aWorkItemKey)
      Returns information about the specified work item.
      Since:
      5.5.1

    • getWorkItemsOfferedToRole

      public List<UserTask.WorkItem> getWorkItemsOfferedToRole(Role aRole)
      Returns all the work items offered to a role.

      Only returns work items in the 'Offered' state.

      Returns:
      a List of UserTask.WorkItem.
      Since:
      5.4.1

    • getWorkItemsAllocatedToUser

      public List<UserTask.WorkItem> getWorkItemsAllocatedToUser(UserReference aUser)
      Returns all the work items allocated to a user.

      The returned work items can be in the following states:

      • 'Allocated',
      • 'Started': if the user has already opened the work item.
      Returns:
      a List of UserTask.WorkItem.
      Since:
      5.4.1

    • getWorkItemsOfferedToUser

      public List<UserTask.WorkItem> getWorkItemsOfferedToUser(UserReference aUser)
      Returns all the work items offered to a user. Only the work items in the 'Offered' state are returned.

      It only returns the work items in the 'Offered' state.

      This method returns an empty list for the system user.

      Returns:
      a List of UserTask.WorkItem.
      Throws:
      IllegalArgumentException - if the user is null.
      Since:
      5.4.1
      See Also:

    • getWorkItemsOfferedToSession

      public List<UserTask.WorkItem> getWorkItemsOfferedToSession(Session aSession)
      Returns all the work items offered to a Session.

      It only returns the work items in the 'Offered' state.

      Returns:
      a List of UserTask.WorkItem.
      Since:
      5.5.1

    • getAllWorkItems

      public List<UserTask.WorkItem> getAllWorkItems()
      Returns all the work items.

      All the current work items are returned whatever their state: they can be offered, allocated, started, completed or in error.

      Returns:
      a List of UserTask.WorkItem.
      Since:
      5.4.1

    • getProcessInstanceKeysForDataContextVariable

      public List<ProcessInstanceKey> getProcessInstanceKeysForDataContextVariable(PublishedProcessKey publishedProcessKey, String varName, String varValue)
      Retrieves active process instances that match a specified data context value within a given published process. This method allows for a flexible search: if a data context variable name is provided, it narrows the search to entries matching both the name and value. If the name is null, it searches across all data context entries for the specified value. This method selects process instances which:
      • are associated with the specified published process key,
      • have in their current data context the specified variable and equal to the specified value.
      The result is a list containing all the process instance keys.
      Parameters:
      publishedProcessKey - The key identifying the published process from which to retrieve instances. This key is essential for limiting the search scope to a specific published process.
      varName - The name of the data context variable to filter by. This parameter is optional and can be null. If provided, the search is filtered to only include data context entries with this name.
      varValue - The value of the data context variable required for a match. This parameter cannot be null and is used to identify matching entries. The search is case-insensitive.
      Returns:
      A list of ProcessInstanceKey objects representing the found process instances that match the specified criteria. An empty list is returned if no matching instances are found.
      Throws:
      IllegalArgumentException - If the repository or publishedProcessKey is null, if both dataContextVariableName and dataContextVariableValue are null, or if the publishedProcessKey does not correspond to any existing published process.

    • isProcessInstanceRunning

      public boolean isProcessInstanceRunning(ProcessInstanceKey aKey)
      Returns true if the specified process instance is running, else false.

    • cleanHistory

      public void cleanHistory(ProcessInstanceKey processInstanceKey) throws OperationException
      Deletes the data in history for workflows terminated for a given ProcessInstanceKey.

      The method will also remove recursively all history data related to the associated sub-workflows.

      Parameters:
      processInstanceKey - a specified ProcessInstanceKey
      Throws:
      IllegalArgumentException - if the specified ProcessInstanceKey is null.
      OperationException - if one of the following occurs:
      Since:
      5.8.1
      See Also:

    • cleanHistory

      public void cleanHistory(Date aDate) throws OperationException
      Deletes the data in history for workflows terminated from a given date.

      This method deletes only workflows which meet the following criteria:

      • the workflow is in the terminated state,
      • the workflow has been terminated at the specified date or before the specified date,
      • the associated execution data has been cleaned.

      The workflows which does not meet these criteria are ignored.

      The method will also remove recursively all history data related to the associated sub-workflows.

      Warning: it may take a long time to complete and as a result, all workflow executions might also be affected. For a more targeted clean, please consider using cleanHistory(ProcessInstanceKey).

      Parameters:
      aDate - the date to compare at the termination date of workflows. Only workflows with a terminated date lower than or equal to the specified date will be deleted.
      Throws:
      IllegalArgumentException - if the specified date is null.
      OperationException
      Since:
      5.8.1
      See Also:

    • unPublish

      public void unPublish(PublishedProcessKey publicationKey, boolean forceCurrentInstanceToTerminate, UserReference user) throws OperationException
      Unpublishes a workflow process publication.

      This method is designed to handle the removal of a published workflow process. If there are active instances of the process, it can optionally terminate them.

      Parameters:
      publicationKey - The published workflow process definition to be unpublished.
      forceCurrentInstanceToTerminate - If true, active instances of the workflow will be forcibly terminated. If false, they will remain running.
      user - The user initiating the unpublish action. This might be used for logging or authorization purposes.
      Throws:
      IllegalArgumentException - If the provided processDefinitionPublished is null or invalid.
      IllegalStateException - If unable to unpublish due to active instances and forceCurrentInstanceToTerminate is false.
      SecurityException - If the user lacks the necessary permissions to unpublish the workflow.
      OperationException
      Since:
      6.1.3