com.day.cq.workflow

Interface WorkflowSession

public interface WorkflowSession

The WorkflowSession class provides all functionality (depending on the users rights) for managing WorkflowModels, Workflow instances and their execution.

It provides methods to:

• deploy/create a workflow models
• start, stop, suspend, resume and complete a workflow instance
• retrieve and complete WorkItems assigned to a user/group

Method Summary

Modifier and Type	Method and Description
void	complete(WorkItem item, Route route) Completes the WorkItem for the assigned Workflow instance and assign to the next WorkflowNode according to the given Route.
WorkflowModel	createNewModel(java.lang.String title) Creates a new blank WorkflowModel.
WorkflowModel	createNewModel(java.lang.String title, java.lang.String id) Creates a new blank WorkflowModel under the given path.
void	delegateWorkItem(WorkItem item, Authorizable participant) Delegates the WorkItem to the specified Authorizable.
void	deleteModel(java.lang.String id) Deletes the given WorkflowModel.
void	deployModel(WorkflowModel model) Deploys a new or modified WorkflowModel.
boolean	evaluate(WorkflowData data, java.lang.String rule) Evaluate the passed rule by choosing the right rule engine.
WorkItem[]	getActiveWorkItems() All WorkItems assigned to an active Workflow instance and the respective user of the WorkflowSession will be returned.
ResultSet<WorkItem>	getActiveWorkItems(long start, long limit) All WorkItems assigned to an active Workflow instance and the respective user of the WorkflowSession will be returned.
ResultSet<WorkItem>	getActiveWorkItems(long start, long limit, WorkItemFilter filter) All WorkItems assigned to an active Workflow instance and the respective user of the WorkflowSession will be returned.
Workflow[]	getAllWorkflows() Returns all Workflows which the WorkflowSession has access to.
WorkItem[]	getAllWorkItems() All WorkItems assigned to a Workflow instance and assigned to the respective user of the WorkflowSession will be returned.
ResultSet<WorkItem>	getAllWorkItems(long start, long limit) All WorkItems assigned to a Workflow instance and assigned to the respective user of the WorkflowSession will be returned.
java.util.List<Route>	getBackRoutes(WorkItem item) All Route to all possible already passed destinations will be returned.
java.util.List<Route>	getBackRoutes(WorkItem item, boolean expand) All Route to all possible already passed destinations will be returned.
java.util.List<Authorizable>	getDelegatees(WorkItem item) Returns all delegatees as Authorizable who are allowed to take over the WorkItem
java.util.List<HistoryItem>	getHistory(Workflow instance) The complete ordered list of HistoryItem s is returned for the given Workflow instance.
WorkflowModel	getModel(java.lang.String id) Returns newest version of the WorkflowModel with the given ID.
WorkflowModel	getModel(java.lang.String id, java.lang.String version) Returns the WorkflowModel with the given ID and version.
WorkflowModel[]	getModels() Returns newest versions of all deployed WorkflowModels.
ResultSet<WorkflowModel>	getModels(long start, long limit) Returns newest versions of all deployed WorkflowModels.
ResultSet<WorkflowModel>	getModels(long start, long limit, WorkflowModelFilter filter) Returns newest versions of all deployed WorkflowModels.
WorkflowModel[]	getModels(WorkflowModelFilter filter) Returns newest versions of all deployed WorkflowModels.
java.util.List<Route>	getRoutes(WorkItem item) All Route to all possible destinations will be returned.
java.util.List<Route>	getRoutes(WorkItem item, boolean expand) All Route to all possible destinations will be returned.
Session	getSession() Returns the JCR Session assigned to the WorkflowSession instance.
Authorizable	getUser() Returns the user that owns the WorkflowSession.
Workflow	getWorkflow(java.lang.String id) Retrieve the Workflow instance with the given ID.
Workflow[]	getWorkflows(java.lang.String[] states) Returns all Workflow instances that are in one of the given states and to which the WorkflowSession has access to.
ResultSet<Workflow>	getWorkflows(java.lang.String[] states, long start, long limit) Returns all Workflows instances that are in one of the given states and to which the WorkflowSession has access to.
WorkflowService	getWorkflowService() Returns the WorkflowService that was used to create the WorkflowSession instance.
WorkItem	getWorkItem(java.lang.String id) Returns the WorkItem with the given ID assigned to a Workflow instance, but only if the respective users WorkflowSession} has access to it.
boolean	isSuperuser() Checks for the workflow superuser
void	logout() The logout method has to be called in order to clean up all jcr session references.
WorkflowData	newWorkflowData(java.lang.String payloadType, java.lang.Object payload) Creates a new WorkflowData instance based on the given data.
void	restartWorkflow(Workflow workflow) This method restarts a workflow instance that is in a "stale" state.
void	resumeWorkflow(Workflow instance) Resumes the given Workflow instance.
Workflow	startWorkflow(WorkflowModel model, WorkflowData data) Start a new Workflow instance with the given WorkflowModel and WorkflowData.
Workflow	startWorkflow(WorkflowModel model, WorkflowData data, java.util.Dictionary<java.lang.String,java.lang.String> metaData) Deprecated. It is recommended to use startWorkflow(WorkflowModel, WorkflowData, Map) instead.
Workflow	startWorkflow(WorkflowModel model, WorkflowData data, java.util.Map<java.lang.String,java.lang.Object> metaData) Start a new Workflow instance with the given WorkflowModel, WorkflowData and meta data.
void	suspendWorkflow(Workflow instance) Suspends the given Workflow instance.
void	terminateWorkflow(Workflow instance) Terminates the given Workflow instance.
void	updateWorkflowData(Workflow instance, WorkflowData data) Updates the workflow data of a running workflow instance to the given WorkflowData.

Method Detail

getWorkflowService

WorkflowService getWorkflowService()

Returns the WorkflowService that was used to create the WorkflowSession instance.

Returns:

The WorkflowService that was used to create the WorkflowSession instance.

getSession

Session getSession()

Returns the JCR Session assigned to the WorkflowSession instance.

Returns:

The JCR Session assigned to the WorkflowSession instance.

getUser

Authorizable getUser()

Returns the user that owns the WorkflowSession.

Returns:

The user that owns the WorkflowSession.

evaluate

boolean evaluate(WorkflowData data,
                 java.lang.String rule)

Evaluate the passed rule by choosing the right rule engine.

Parameters:

data - workflow data to apply the rule

rule - rule to execute

Returns:

true if rule evaluation is true or the rule is null

deployModel

void deployModel(WorkflowModel model)
          throws WorkflowException

Deploys a new or modified WorkflowModel.

Parameters:

model - The WorkflowModel to be deployed.

Throws:

WorkflowException - Thrown in case an error prevents deployment of the WorkflowModel.

createNewModel

WorkflowModel createNewModel(java.lang.String title)
                      throws WorkflowException

Creates a new blank WorkflowModel.

Parameters:

title - The title of the newly created WorkflowModel.

Returns:

The newly created WorkflowModel.

Throws:

WorkflowException - Thrown in case an error prevents creation of the WorkflowModel.

createNewModel

WorkflowModel createNewModel(java.lang.String title,
                             java.lang.String id)
                      throws WorkflowException

Creates a new blank WorkflowModel under the given path.

Parameters:

title - The title of the newly created WorkflowModel.

id - The ID of the new WorkflowModel.

Returns:

The newly created WorkflowModel.

Throws:

WorkflowException - Thrown in case an error prevents creation of the WorkflowModel.

deleteModel

void deleteModel(java.lang.String id)
          throws WorkflowException

Deletes the given WorkflowModel.

Parameters:

id - The ID of the WorkflowModel to be deleted.

Throws:

WorkflowException - Thrown in case an error prevents deployment of the WorkflowModel.

getModels

WorkflowModel[] getModels()
                   throws WorkflowException

Returns newest versions of all deployed WorkflowModels.

Returns:

All deployed WorkflowModel at their newest versions.

Throws:

WorkflowException - Thrown in case an error occurs while fetching the WorkflowModels.

getModels

WorkflowModel[] getModels(WorkflowModelFilter filter)
                   throws WorkflowException

Returns newest versions of all deployed WorkflowModels.

Parameters:

filter - The WorkflowModelFilter used for getting workflow models

Returns:

All deployed WorkflowModel at their newest versions.

Throws:

WorkflowException - Thrown in case an error occurs while fetching the WorkflowModel.

getModels

ResultSet<WorkflowModel> getModels(long start,
                                   long limit)
                            throws WorkflowException

Returns newest versions of all deployed WorkflowModels.

Parameters:

start - Start index of the result set.

limit - Limit of the result set.

Returns:

All deployed WorkflowModel at their newest versions.

Throws:

WorkflowException - Thrown in case an error occurs while fetching the WorkflowModels.

getModels

ResultSet<WorkflowModel> getModels(long start,
                                   long limit,
                                   WorkflowModelFilter filter)
                            throws WorkflowException

Returns newest versions of all deployed WorkflowModels.

Parameters:

start - Start index of the result set.

limit - Limit of the result set.

filter - The WorkflowModelFilter used for getting workflow models

Returns:

All deployed WorkflowModel at their newest versions.

Throws:

WorkflowException - Thrown in case an error occurs while fetching the WorkflowModels.

getModel

WorkflowModel getModel(java.lang.String id)
                throws WorkflowException

Returns newest version of the WorkflowModel with the given ID.

Parameters:

id - The ID of the WorkflowModel.

Returns:

The newest version of the WorkflowModel with the given ID or null, if no WorkflowModel with the given ID exists.

Throws:

WorkflowException - Thrown in case an error occurs while fetching the WorkflowModel.

getModel

WorkflowModel getModel(java.lang.String id,
                       java.lang.String version)
                throws WorkflowException,
                       VersionException

Returns the WorkflowModel with the given ID and version.

Parameters:

id - The ID of the WorkflowModel.

version - The version of the WorkflowModel.

Returns:

The WorkflowModel with the given ID and version or null, if no WorkflowModel matches the given ID and/or version.

Throws:

WorkflowException - Thrown in case an error occurs while fetching the WorkflowModel.

VersionException - Thrown in case the version does not exist or can not be accessed.

startWorkflow

Workflow startWorkflow(WorkflowModel model,
                       WorkflowData data)
                throws WorkflowException

Start a new Workflow instance with the given WorkflowModel and WorkflowData.

Parameters:

model - WorkflowModel to be used for the new Workflow instance.

data - WorkflowData to be attached to the new workflow instance.

Returns:

The Workflow of the newly started Workflow instance.

Throws:

WorkflowException - Thrown in case the workflow process cannot be started.

startWorkflow

Workflow startWorkflow(WorkflowModel model,
                       WorkflowData data,
                       java.util.Dictionary<java.lang.String,java.lang.String> metaData)
                throws WorkflowException

Deprecated. It is recommended to use startWorkflow(WorkflowModel, WorkflowData, Map) instead.

Start a new Workflow instance with the given WorkflowModel and WorkflowData.

Parameters:

model - WorkflowModel to be used for the new Workflow instance.

data - WorkflowData to be attached to the new workflow instance.

metaData - Meta data assigned to the new Workflow.

Returns:

The Workflow of the newly started Workflow instance.

Throws:

WorkflowException - Thrown in case the workflow process cannot be started.

startWorkflow

Workflow startWorkflow(WorkflowModel model,
                       WorkflowData data,
                       java.util.Map<java.lang.String,java.lang.Object> metaData)
                throws WorkflowException

Start a new Workflow instance with the given WorkflowModel, WorkflowData and meta data.

Parameters:

model - WorkflowModel to be used for the new Workflow instance.

data - WorkflowData to be attached to the new workflow instance.

metaData - Meta data assigned to the new Workflow.

Returns:

The Workflow of the newly started Workflow instance.

Throws:

WorkflowException - Thrown in case the workflow process cannot be started.

terminateWorkflow

void terminateWorkflow(Workflow instance)
                throws WorkflowException

Terminates the given Workflow instance.

Parameters:

instance - The Workflow instance that shall be terminated.

Throws:

WorkflowException - Thrown in case the workflow instance cannot be terminated.

resumeWorkflow

void resumeWorkflow(Workflow instance)
             throws WorkflowException

Resumes the given Workflow instance.

Parameters:

instance - The Workflow instance that shall be resumed.

Throws:

WorkflowException - Thrown in case the workflow instance cannot be resumed.

suspendWorkflow

void suspendWorkflow(Workflow instance)
              throws WorkflowException

Suspends the given Workflow instance.

Parameters:

instance - The Workflow of the workflow instance that shall be suspended.

Throws:

WorkflowException - Thrown in case the workflow instance cannot be suspended.

getActiveWorkItems

WorkItem[] getActiveWorkItems()
                       throws WorkflowException

All WorkItems assigned to an active Workflow instance and the respective user of the WorkflowSession will be returned.

Returns:

All WorkItems assigned to an active workflow and the respective users WorkflowSession.

Throws:

WorkflowException - Thrown in case an exception occurs while fetching the active WorkItems.

getActiveWorkItems

ResultSet<WorkItem> getActiveWorkItems(long start,
                                       long limit)
                                throws WorkflowException

All WorkItems assigned to an active Workflow instance and the respective user of the WorkflowSession will be returned.

Parameters:

start - Start index of the result set.

limit - Limit of the result set.

Returns:

All WorkItems assigned to an active workflow and the respective users WorkflowSession.

Throws:

WorkflowException - Thrown in case an exception occurs while fetching the active WorkItems.

getActiveWorkItems

ResultSet<WorkItem> getActiveWorkItems(long start,
                                       long limit,
                                       WorkItemFilter filter)
                                throws WorkflowException

All WorkItems assigned to an active Workflow instance and the respective user of the WorkflowSession will be returned.

Parameters:

start - Start index of the result set.

limit - Limit of the result set.

filter - filter for work items

Returns:

All WorkItems assigned to an active workflow and the respective users WorkflowSession.

Throws:

WorkflowException - Thrown in case an exception occurs while fetching the active WorkItems.

getAllWorkItems

WorkItem[] getAllWorkItems()
                    throws WorkflowException

All WorkItems assigned to a Workflow instance and assigned to the respective user of the WorkflowSession will be returned.

Returns:

All WorkItems assigned to a Workflow instance and the respective users WorkflowSession.

Throws:

WorkflowException - Thrown in case an exception occurs while fetching all WorkItems.

getAllWorkItems

ResultSet<WorkItem> getAllWorkItems(long start,
                                    long limit)
                             throws WorkflowException

All WorkItems assigned to a Workflow instance and assigned to the respective user of the WorkflowSession will be returned.

Parameters:

start - Start index of the result set.

limit - Limit of the result set.

Returns:

All WorkItems assigned to a Workflow instance and the respective users WorkflowSession.

Throws:

WorkflowException - Thrown in case an exception occurs while fetching all WorkItems.

getWorkItem

WorkItem getWorkItem(java.lang.String id)
              throws WorkflowException

Returns the WorkItem with the given ID assigned to a Workflow instance, but only if the respective users WorkflowSession} has access to it.

Parameters:

id - The ID of the WorkItem.

Returns:

The WorkItem with the given ID.

Throws:

WorkflowException - Thrown in case an exception is occurs while fetching the WorkItem.

getWorkflows

Workflow[] getWorkflows(java.lang.String[] states)
                 throws WorkflowException

Returns all Workflow instances that are in one of the given states and to which the WorkflowSession has access to.

Parameters:

states - The list of states used to select the Workflow instances.

Returns:

All Workflows that are in one of the given states and to which the WorkflowSession has access to.

Throws:

WorkflowException - Thrown in case an error occurred while retrieving the Workflows.

getWorkflows

ResultSet<Workflow> getWorkflows(java.lang.String[] states,
                                 long start,
                                 long limit)
                          throws WorkflowException

Returns all Workflows instances that are in one of the given states and to which the WorkflowSession has access to.

Parameters:

states - The list of states used to select the Workflow instances.

start - Start index of the result set.

limit - Limit of the result set.

Returns:

All Workflows that are in one of the given states and to which the WorkflowSession has access to.

Throws:

WorkflowException - Thrown in case an error occurred while retrieving the Workflows.

getAllWorkflows

Workflow[] getAllWorkflows()
                    throws WorkflowException

Returns all Workflows which the WorkflowSession has access to.

Returns:

All Workflows the WorkflowSession has access to.

Throws:

WorkflowException - Thrown in case an error occurred while retrieving the Workflows.

getWorkflow

Workflow getWorkflow(java.lang.String id)
              throws WorkflowException

Retrieve the Workflow instance with the given ID.

Parameters:

id - The ID of the Workflow instance that should be returned.

Returns:

The Workflow instance with the given ID or null, if no Workflow instance ID matches the given ID.

Throws:

WorkflowException - Thrown in case an unexpected error occurs while retrieving the Workflow.

complete

void complete(WorkItem item,
              Route route)
       throws WorkflowException

Completes the WorkItem for the assigned Workflow instance and assign to the next WorkflowNode according to the given Route.

Parameters:

item - The WorkItem to be completed.

route - The Route to the destination to be advanced.

Throws:

WorkflowException - Thrown in case an error is occurs while completing the WorkItem.

getRoutes

java.util.List<Route> getRoutes(WorkItem item)
                         throws WorkflowException

All Route to all possible destinations will be returned. Rules will be already executed, thus all routes that are active can be selected.

Parameters:

item - The WorkItem to retrieve routes from.

Returns:

All Routes to advance.

Throws:

WorkflowException - Thrown in case an error is occurs while evaluating the Routes.

getRoutes

java.util.List<Route> getRoutes(WorkItem item,
                                boolean expand)
                         throws WorkflowException

All Route to all possible destinations will be returned. Rules will be already executed, thus all routes that are active can be selected.

Parameters:

item - The WorkItem to retrieve routes from.

expand - Expands the group members if the destination points to a group. Means that not only the group is retourned as route but as well all group members.

Returns:

All Routes to advance.

Throws:

WorkflowException - Thrown in case an error is occurs while evaluating the Routes.

getBackRoutes

java.util.List<Route> getBackRoutes(WorkItem item)
                             throws WorkflowException

All Route to all possible already passed destinations will be returned. Rules will be already executed, thus all routes that are active can be selected.

Parameters:

item - The WorkItem to retrieve back routes from.

Returns:

All Routes to advance (back).

Throws:

WorkflowException - Thrown in case an error is occurs while evaluating the Routes.

getBackRoutes

java.util.List<Route> getBackRoutes(WorkItem item,
                                    boolean expand)
                             throws WorkflowException

All Route to all possible already passed destinations will be returned. Rules will be already executed, thus all routes that are active can be selected.

Parameters:

item - The WorkItem to retrieve back routes from.

expand - Expands the group members if the destination points to a group. Means that not only the group is retourned as route but as well all group members.

Returns:

All Routes to advance (back).

Throws:

WorkflowException - Thrown in case an error is occurs while evaluating the Routes.

newWorkflowData

WorkflowData newWorkflowData(java.lang.String payloadType,
                             java.lang.Object payload)

Creates a new WorkflowData instance based on the given data.

Parameters:

payloadType - The type of payload for the new WorkflowData instance.

payload - The payload object used for creating the new WorkflowData instance. WorkflowData instance.

Returns:

The new WorkflowData instance.

getDelegatees

java.util.List<Authorizable> getDelegatees(WorkItem item)
                                    throws WorkflowException

Returns all delegatees as Authorizable who are allowed to take over the WorkItem

Parameters:

item - The workitem

Returns:

The list of Authorizables who are allowed to act as delegatees.

Throws:

WorkflowException - in case the delegatees could not be retrieved for some reason

delegateWorkItem

void delegateWorkItem(WorkItem item,
                      Authorizable participant)
               throws WorkflowException,
                      java.security.AccessControlException

Delegates the WorkItem to the specified Authorizable.

Parameters:

item - the corresponding workitem

participant - the participant to delegate

Throws:

java.security.AccessControlException - if the given participant is not allowed to take over the workitem.

WorkflowException - in case the delegation fails in regards of persisting the "new" state.

getHistory

java.util.List<HistoryItem> getHistory(Workflow instance)
                                throws WorkflowException

The complete ordered list of HistoryItem s is returned for the given Workflow instance.

Parameters:

instance - Workflow instance

Returns:

List of HistoryItem s

Throws:

WorkflowException - in case the history item retrieval fails

updateWorkflowData

void updateWorkflowData(Workflow instance,
                        WorkflowData data)

Updates the workflow data of a running workflow instance to the given WorkflowData.

Parameters:

instance - The Workflow instance for which to update the data.

data - The WorkflowData for the update.

logout

void logout()

The logout method has to be called in order to clean up all jcr session references.

isSuperuser

boolean isSuperuser()

Checks for the workflow superuser

Returns:

true if the user is a workflow superuser

restartWorkflow

void restartWorkflow(Workflow workflow)
              throws WorkflowException

This method restarts a workflow instance that is in a "stale" state. means there is no workitem around. this could happen in case the eventing which controls the the script/java processes purges an event/job (there is the depending (serialized) workitem stored). The restart tries to start the workflow at the position right before the workitem got lost. Note: This is an administrative method and can only be used by a workflow superuser!

Parameters:

workflow - workflow

Throws:

WorkflowException - in case an error occurs