The WorkflowService

The WorkflowService is the Java EE implementation of the WorkflowManager interface from the core API. This service component allows to process, update and lookup workItems in the Imixs-Workflow engine.

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. The following example shows how a workitem can be processed using the WorkflowService component. 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.

  org.imixs.workflow.jee.ejb.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

The model version can also be specified as a regex.

  // 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'

After a new workitem is process the first time, it is under the control of the WorkflowService.

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.


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

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


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,


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 belgons 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,


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,


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,


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,


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,


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,

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:


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:

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