The WorkflowService

The WorkflowService is the Jakarta EE implementation of the WorkflowManager interface from the core API. This is the central service component that allows you to process, update and lookup workItems.

How to Process a Workitem

Before a workitem can be processed by the WorkflowService, a process model need to be defined and deployed together with the workflow engine. See the section Imixs-BPMN Modeler for details about how to create a model and upload it into the workflow server. A workitem must provide at least the following properties:

  • $ModelVersion
  • $TaskID
  • $EventID

These properties are defining the workflow activity which should be processed by the workflowManager.

The following example shows how a new workitem can be creaetd and processed by injecting the WorkflowService component:

@Inject
WorkflowService workflowService;
//...
// create an empty workitem assigend to a model
ItemCollection workitem=new ItemCollection().model("1.0.0").task(100).event(10);
// assign business data
workitem.setItemValue("_name", "M. Alex");
workitem.setItemValue("_Titel", "My first workflow example");
	
// process the workitem
workitem=workflowService.processWorkItem(workitem);

The WorkflowService will automatically persist the workitem into the database and controls the status for future access.

The model version of a new WorkItem can either be specified by it's model version or as a regular expression:

// take best match for model version 1.x
ItemCollection workitem=new ItemCollection().model("(^1.)").task(100).event(10);

Another alternative to assign a new workitem with a model version is by specifying the $workflowgroup:

// create an empty workitem assigend to a workflow group
ItemCollection workitem=new ItemCollection().task(100).event(10);
// assign group
workitem.setItemValue(WorkflowKernel.WORKFLOWGROUP, "Invoice");
// assign the workitem to the latest version matching the workfow group 'invoice'
workitem=workflowService.processWorkItem(workitem);

The WorkflowService will automatically assign the first matching model version holding the given workflow group.

Worklist Methods

To get the current list of all workitems, the WorkflowService provides a set of methods. These methods provide different ways to read a worklist by categories. The WorkflowService returns only workitems in a result set if the user has read access. If a workitem is not accessible for the user, this workitem will not be included in the result-set. All result-sets can be ordered by modified or creation date.

getWorkListByCreator

The method getWorkListByCreator can be called to read the list of all workitems created by a specific user:

@Inject
org.imixs.workflow.jee.ejb.WorkflowService workflowService;
// get the first 10 workitem for the current user
Collection<ItemCollection> worklist=workflowService.getWorkListByCreator(null,10,0);
// get list for  a named user
Collection<ItemCollection> worklist=workflowService.getWorkListByCreator('manfred',10,0);

The WorkflowManager provides a paging mechanism to browse through long result-sets. The following example shows how to get 5 workitems from the tenth page

Collection<ItemCollection> worklist=workflowService.getWorkListByCreator(null,5,10);

getWorkList

The method returns a collection of workitems for the current user. A Workitem belongs to a user or role if the user has at least read write access to this workitem.

Collection<ItemCollection> list=workflowService.getWorkList();
//...

You can specify the type, the start position, the count and sort order of workitems returned by this method. The type of a workitem is defined by the workitem property ‘type’ which can be set before a workitem is processed.

String type="workitem";
Collection<ItemCollection> list=workflowService.getWorkList(0,-1,
	type,WorkflowService.SORT_ORDER_CREATED_DESC);
//...

getWorkListByAuthor

The method returns a collection of workitems belonging to a specified user. This filter can be set to a username or a user role defined by the application. A Workitem belongs to a user or role if the user has write access to this workitem. So the method returns workitems which can be processed by the user.

String type="workitem";
String user="manfred"
Collection<ItemCollection> list=workflowService.getWorkList(user,0,-1,
	type,WorkflowService.SORT_ORDER_CREATED_DESC);
//...

getWorkListByGroup

The method returns a collection of workitems belonging to a specified workflow group. The workflow group is defined by the workflow model and includes all process entities defined by a business process

String type="workitem";
String group="Ticketservice";
Collection<ItemCollection> list=workflowService.getWorkListByGroup(group,0,-1,
	type,WorkflowService.SORT_ORDER_CREATED_DESC);
//...

getWorkListByProcessID

The method returns a collection of workitems belonging to a specified $processID defined by the workflow model.

String type="workitem";
Collection<ItemCollection> list=workflowService.getWorkListByProcessID(2100,0,-1,
	type,WorkflowService.SORT_ORDER_CREATED_DESC);
//...

getWorkListByOwner

The method returns a collection of workitems containing a ‘$owner’ item belonging to a specified username. The ‘$owner’ item is typical controlled by the OwnerPlugin using the Imixs Workflow Modeler

String type="workitem";
String user="Manfred"
Collection<ItemCollection> list=workflowService.getWorkListByOwner(user,0,-1,
	type,WorkflowService.SORT_ORDER_CREATED_DESC);
//...

getWorkListByWriteAccess

The method returns a collection of workitems where the current user has at least writeAccess. This means the either the username or one of the user roles is contained in the $writeaccess property of each workitem returned by the method.

String type="workitem";
Collection<ItemCollection> list=workflowService.getWorkListByWriteAccess(0,-1,
	type,WorkflowService.SORT_ORDER_CREATED_DESC);
//...

getWorkListByRef

The method returns a collection of workitems belonging to a specified workitem identified by the attribute $UniqueIDRef.

String type="workitem";
Collection<ItemCollection> list=workflowService.getWorkListByRef(refID,0,-1,
	type,WorkflowService.SORT_ORDER_CREATED_DESC);
//...

Model Version Management

Each time a running process instance is updated, the WorkflowService compares the internal model version with the model versions provided by the model repository. In case the current model version is no longer available the WorkflowService automatically upgrades an active process instance to the latest version in the repository. Therefore the engine verifies the task ID (numprocessid) and the process name (txtworkflowgroup) with the corresponding models. This mechanism allows to upgrade process instances at run time to a newer version.

It is also possible to handle different versions of a model at the same time. In this case each process instance is processed by the model version from which it was started.

CDI Events

The WorkflowService EJB provides an Observer Pattern based on CDI Events. The events are fired when a workitem is processed. The Event is defined by the class:

org.imixs.workflow.engine.ProcessingEvent

The class ProcessingEvent defines the following event types:

  • BEFORE_PROCESS - is send immediately before a workitem will be processed
  • AFTER_PROCESS - is send immediately after a workitem was processed but before the document is saved.

This event can be consumed by another Session Bean or managed bean implementing the @Observes annotation:

@Stateless
public class WorkflowServiceListener {
	public void onEvent(@Observes ProcessingEvent processingEvent){
		ItemCollection workitem=processingEvent.getDocument();
		System.out.println("Received ProcessingEvent Type = " + processingEvent.getType());
	}
}

Evaluate the Next Task Element

The WorkflowService provides the method evalNextTask to evaluate the next BPMN task element based on a Event element. This method can be called by Plugins to get the outcome of the current processing step. If the event did not point to a new task, the current task will be returned. The method supports ‘conditional-events’ as well as ‘split-events’. A conditional-event contains the attribute ‘keyExclusiveConditions’ defining conditional targets (tasks) or adds conditional follow up events A split-event contains the attribute ‘keySplitConditions’ defining the target for the current master version (condition evaluates to ‘true’). See also the section How to Model…

// get next process entity
nextTask = workflowService.evalNextTask(adocumentContext, adocumentActivity);