Stardust/Knowledge Base/API/JavaAPICookbook/Stardust Workflow Service in Action

Introduction

In this article, we will explain the capabilities of Stardust Workflow Service in details with examples. It is assumed that you are familiar with the modeling the processes with Stardust. If not please read the product documentation here first.
If you are using the Stardust in embedded mode, then it is likely that you will have to use this service extensively. The Workflow Service is the heart of Stardust Engine. Its core features include:

• Starting a process
• Executing an activities
• Activating, delegating, suspending and aborting activities
• Accessing workflow data

Example Process Model

We will use the following simple leave application process for this article.

 

Prerequisite

To reduce complexity, I assume following;

•  The Stardust is being used in embedded mode and user interaction is performed via embedding application UI. That is, you may invoke methods like starting a process or completing an activity when user chooses a command or link, or when submitting a form in the application. The responsibility to collect required data from user or from given context belongs to the application.
• We have reference to the initialized workflow service named, wfs.
• The above mentioned process model is already deployed.
• We have a user with account, john, associated with ‘Employee’ role.
• We have a user with account, smith, associated with ‘Manager’ role.

 The Workflow Service Operations

Starting a Process

The following code snippet shows how to start a process. You may execute this snippet, in this case, when user chooses to apply for the leave.

String processID = "LeaveApplicationProcess";
Map<String, String> initData = new HashMap<String, String>();
boolean isSynchronous = true;
ProcessInstance startedProcess = wfs.startProcess(processID, initData, isSynchronous);

Where;

• The first method parameter, processID, is ID of the process to be started. In the Stardust runtime there can be many different processes. A process is uniquely identified by the ID.
• The second parameter is contains the data to be passed for process being started. We will discuss this in details in a separate article ‘Handling In and Out Data with API’.
• The third Boolean parameter indicates whether to start a process in sync mode.
• If the process is successfully started, this method returns started process instance.

This operation will start the process and execute all non-interactive activities on the way. As soon as it encounters non-interactive activity, it will create that activity instance and suspends to its role work basket.
In our process, the first activity itself is a manual activity. Hence, the Stardust will create its instance and assign it to the ‘Employee’ role. The instance will be in the suspended state. Now, any user belonging to the Employee can activate and complete it.

 

Activating and completing an Activity

When an activity is created and assigned to a role, by default, it goes into suspended state. When a user belonging to the role chooses to work on the activity instance, it gets activated. So, you may say, activating an activity means choosing to work on it and the other way around.
The following code snippet shows how to activate and complete an activity instance in single operation.

long activityInstanceOID = 401L;
String context = null;
Map<String, ?> outData = new HashMap<String, String>();
int activateNextActivityFlag = WorkflowService.FLAG_ACTIVATE_NEXT_ACTIVITY_INSTANCE;
ActivityCompletionLog activityCompletionLog = wfs.activateAndComplete(activityInstanceOID, context, outData,
 activateNextActivityFlag);

Where;

• The first parameter, activityInstanceOID, is an OID of the activity which you want to activate and complete. I have hard-coded an activity OID. Normally, you will get this from user’s work-list or using query service or even may be cached by your embedding application.
• Second parameter is the context on which data mapping will be performed. The value of null maps the data in ‘default’ context. We will see more on data mapping in separate section bellow.
• Third parameter is the process data that activity will change.
• The last parameter is a flag that indicates whether to activate the activity immediately after completing the current one.

Note that activateAndComplete method returns an instance of ActivityCompletionLog. This contains the completed activity and possibly, next activated activity details. The Stardust will activate the next activity only if the next interactive activity exists, and current user can activate it.

The following code snippet shows how to activate and then complete an activity instance in separate operations.

ActivityInstance activityInstance = wfs.activate(activityInstanceOID);
ActivityCompletionLog activityCompletionLog = wfs.complete(activityInstance.getOID(), context, outData, 
 activateNextActivityFlag);

The following code snippet shows how to activate the next activity instance of the given process instance.

ActivityInstance activityInstance = wfs.activateNextActivityInstanceForProcessInstance(startedProcess.getOID());

Aborting an Activity

Sometimes, you need to abort an activity and the process to which it belongs. This could be for reasons that this process instance is no more required for the business.
The following code snippet shows how to abort an activity and effectively complete process instance.

 ActivityInstance abortedActivityInstance = wfs.abortActivityInstance(activityInstanceOID);

The following code snippet shows how to indicate the scope of process abortion.

 AbortScope abortScope = AbortScope.SubHierarchy;
 abortedActivityInstance = wfs.abortActivityInstance(activityInstanceOID, abortScope);

Here, the AbortScope parameter value AbortScope.SubHierarchy indicates that;

• If the activity being aborted is a sub process, then the sub process and the sub process hierarchy will be aborted but the process continues as usual. That is, the process continues as if the sub process completed successfully though in reality is aborted.
• If the activity being aborted is not a sub process, then only that activity is aborted and process continues as usual.

Whereas, the value of AbortScope.RootHierarchy, indicates that;

• The process abortion is performed starting from the root process instance. All alive activities in the process hierarchy will be aborted.

Delegating an Activity

You may delegate an activity instance to a specific user, participant or default performer.

The following code snippet shows how to delegate an activity to a specific user.

long userOID = 233L; 
wfs.delegateToUser(activityInstanceOID, userOID);

The following code snippet shows how to delegate an activity to a model participant.

String performerID = "Project";
wfs.delegateToParticipant(activityInstanceOID, performerID);

The following code snippet shows how to delegate an activity to the default performer.

wfs.delegateToDefaultPerformer(activityInstanceOID);

Where, you will get the details of user or participant by querying the Stardust runtime and choosing the appropriate the user or participant.

Suspending an Activity

Sometimes, you may work on an activity halfway and need to stop your work for some reasons, then you can suspend the activity to either your own work basket, default performer, other participant or any other specific user.

Here is code snippet to suspend an activity to a model participant;

Map<String, ?> outData =new HashMap<String, String>();
String participantID = "Project";
wfs.suspendToParticipant(activityInstanceOID, participantID,context, outData);

Here is code snippet to suspend an activity to the default performer;

wfs.suspendToDefaultPerformer(activityInstanceOID);

Here is code snippet to suspend an activity to a specific user;

wfs.suspendToUser(activityInstanceOID, userOID);

Where, you will get the details of user or participant by querying the Stardust runtime and choosing the appropriate the user or participant.

Fetching the User Work List

When a user logs into the system, generally you want to present then their work-list. A work-list is consists of activities assigned directly to the user and to roles that he belongs to.

Here is the code snippet to fetch user’s private work-list;

WorklistQuery privateWorkListQuery = WorklistQuery.findPrivateWorklist();
wfs.getWorklist(privateWorkListQuery);

Here is the code snippet to fetch user’s complete work-list;

WorklistQuery completeWorklistQuery = WorklistQuery.findCompleteWorklist();
wfs.getWorklist(completeWorklistQuery);

Handling Process Data

In this section, we will see how to change the data during operations like completing and suspending an activity, fetching and updating the process data via data paths.

As per our leave application process above, suppose we are completing an ‘Apply Leave’ activity. We can see that this activity updates the following process data;

• from date
• to date
• reason for leave

The following code shows how to change the process data while completing the activity.

String processID = "LeaveApplicationProcess";
Map<String, String> initData = new HashMap<String, String>();
boolean isSynchronous = true;
ProcessInstance startedProcess = wfs.startProcess(processID, initData, isSynchronous);
 
 
String context=null;
Map<String, String> outData =new HashMap<String, String>();
int activateNextActivityFlag = WorkflowService.FLAG_ACTIVATE_NEXT_ACTIVITY_INSTANCE;
 
outData.put("FromDate", "19/05/2012");
outData.put("ToDate", "30/05/2012");
outData.put("LeaveReason", "I am going out to the Hawaii for holidays.");
 
ActivityInstance activityInstance = wfs.activateNextActivityInstanceForProcessInstance(startedProcess.getOID());
ActivityCompletionLog activityCompletionLog = wfs.complete(activityInstance.getOID(), context, outData, 
 activateNextActivityFlag);

The following code snippet shows how to fetch the data path representing the process data. For more information on data paths, refer to the Stardust product documentation.

long processInstanceOID = 783L;
Object inDataPathValue = wfs.getInDataPath(processInstanceOID, "leaveReasonInDataPath");

The following code snippet shows how to change the out data path value, effectively changing the referenced process data.

long processInstanceOID = 783L;
wfs.setOutDataPath(processInstanceOID, "leaveReasonOutDataPath", "going to the Hawaii beach resort!");