com.adobe.granite.workflow

Interface WorkflowSession

All Superinterfaces:

Adaptable

@ProviderType
public interface WorkflowSession
extends Adaptable

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, Participant participant) Delegates the WorkItem to the specified Principal.
void	deleteModel(java.lang.String id) Deletes the given WorkflowModel.
void	deployModel(WorkflowModel model) Deploys a new or modified WorkflowModel.
ResultSet<InboxItem>	getActiveInboxItems(long start, long limit, InboxItemFilter filter) Retrieves all the active InboxItems assigned to user for this WorkflowSession instance.
ResultSet<InboxItem>	getActiveInboxItems(long start, long limit, java.lang.String itemSubType, InboxItemFilter filter) Retrieves all the active InboxItems assigned to user for this WorkflowSession instance.
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, boolean expand) All Route to all possible already passed destinations will be returned.
java.util.Iterator<Participant>	getDelegates(WorkItem item) Returns all delegates as Participant 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, boolean expand) All Route to all possible destinations will be returned.
default java.util.Set<java.lang.String>	getUsersExplicitlySharingItems() Provides the set of users, who have explicitly shared some of their inbox items with the current user Returns null if there is no user matching above criterion
default java.util.Set<java.lang.String>	getUsersSharingInbox() Provides the set of users, who have shared their entire inbox with the current user Returns null if there is no user matching above criterion
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.
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
default void	lock(InboxItem item) Locks the shared InboxItem.
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.
default void	returnItem(InboxItem item) Returns the inbox item to previous assignee
default void	share(InboxItem item, java.util.Set<java.lang.String> userIds) Shares the InboxItem with provided list of users.
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.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.

Methods inherited from interface org.apache.sling.api.adapter.Adaptable

adaptTo

Method Detail

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 - for workflow models

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)
                            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:

filter - for workflow models

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.

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.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. e

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.

getActiveInboxItems

ResultSet<InboxItem> getActiveInboxItems(long start,
                                         long limit,
                                         InboxItemFilter filter)
                                  throws WorkflowException

Retrieves all the active InboxItems assigned to user for this WorkflowSession instance. Use this method instead of getActiveWorkItems(long, long, com.adobe.granite.workflow.exec.filter.WorkItemFilter) ()} if you wish to retrieve both WorkItems (which is an InboxItem) and InboxItems from other InboxItem providers

Parameters:

start - Start index of the result set. zero based, pass 0 to start at beginning

limit - Limit of the result set. pass -1 for no limit.

filter - filter for inbox items

Returns:

a ResultSet of Inbox Items

Throws:

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

getActiveInboxItems

ResultSet<InboxItem> getActiveInboxItems(long start,
                                         long limit,
                                         java.lang.String itemSubType,
                                         InboxItemFilter filter)
                                  throws WorkflowException

Retrieves all the active InboxItems assigned to user for this WorkflowSession instance. The provided filter can also specify user whose items the current user has access to. Use this method instead of getActiveWorkItems(long, long, com.adobe.granite.workflow.exec.filter.WorkItemFilter) ()} if you wish to retrieve both WorkItems (which is an InboxItem) and InboxItems from other InboxItem providers

Parameters:

start - Start index of the result set. zero based, pass 0 to start at beginning

limit - Limit of the result set. pass -1 for no limit.

itemSubType - The sub-type of the inbox item.

filter - filter for inbox items

Returns:

a ResultSet of Inbox Items

Throws:

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

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,
                                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 returned 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,
                                    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 returned 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.

getDelegates

java.util.Iterator<Participant> getDelegates(WorkItem item)
                                      throws WorkflowException

Returns all delegates as Participant who are allowed to take over the WorkItem

Parameters:

item - The workitem

Returns:

The list of Participants who are allowed to act as delegates.

Throws:

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

delegateWorkItem

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

Delegates the WorkItem to the specified Principal.

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

getUsersSharingInbox

default java.util.Set<java.lang.String> getUsersSharingInbox()
                                                      throws WorkflowException

Provides the set of users, who have shared their entire inbox with the current user Returns null if there is no user matching above criterion

Returns:

A set containing ids of users

Throws:

WorkflowException

getUsersExplicitlySharingItems

default java.util.Set<java.lang.String> getUsersExplicitlySharingItems()
                                                                throws WorkflowException

Provides the set of users, who have explicitly shared some of their inbox items with the current user Returns null if there is no user matching above criterion

Returns:

A set containing ids of users

Throws:

WorkflowException

share

default void share(InboxItem item,
                   java.util.Set<java.lang.String> userIds)
            throws WorkflowException

Shares the InboxItem with provided list of users. Only the current assignee can share the provided inbox item. This method should be used for explicitly sharing an inbox item.

Parameters:

item - The inbox item to be shared.

userIds - The list of authorizableIds of the users with whom item has to be shared.

Throws:

WorkflowException - Thrown in case an error occurs while sharing the inbox item.

lock

default void lock(InboxItem item)
           throws WorkflowException

Locks the shared InboxItem. The item should not be already locked and the current user should have sufficient access to lock the item (i.e. it should be assigned to the current user or it should be shared with the current user)

Parameters:

item - The inbox item to be locked.

Throws:

WorkflowException - Thrown in case an error occurs while locking the inbox item.

returnItem

default void returnItem(InboxItem item)
                 throws WorkflowException

Returns the inbox item to previous assignee

Parameters:

item - The inbox item to be returned.

Throws:

WorkflowException - Thrown in case an error occurs while returning the inbox item.