Blog Posts bpmn-1-x Process Management

How to Handle Your Business Data

Blog: Imixs Workflow Blog

The Imixs-Workflow engine provides different ways how you can store and access business data within a business process. In the following short tutorial I will show up to ways how to do this.

Embedded Business Data

The most easies way to store your business data with Imixs-Workflow is to embed the data into a process instance. You can add any kind of data fields into a process instance before you process it with your workflow model:

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

This example adds the two custom items ‘_name’ and ‘_title’ to the workitem to be process. After the workitem was processed or later loaded from the workflow engine you can access and change this data again:

String name = workitem.getItemValueString("_name");

Java Server Faces

If you are developing a JSF Application than you can use the same technique in your JSF Page. See the following example:

<h:inputText value="#{workflowController.workitem.item['_name']}"/>

In the same way the data can be displayed in a page or view:

<h:dataTable value="#{viewHandler.getData(tasklistController)}" var="workitem">
<h:outputText value="#{workitem.item['_name']}" />

The Advantage

The advantage of embedding business data into a process instance is that your data is controlled by the workflow engine and your workflow model. For example the data is read and write protected according to the rules in your BPMN model. Also the data can directly be accessed in the model. For example by sending a E-Mail message:

Now lets see which alternatives you have.

Store Business Data Into a Datatable

An alternative to store your business data directly into the process instance is storing data in a separate data table. Imixs-Workflow is based on the Java Persistence API (JPA). And in this way you can also create and access your custom data entities. As the workflow engine already defines a JPA data pool it is easy to reuse this persitence unit for your own custom entities. See the following example:

@javax.persistence.Entity public class Customer implements { 
private static final long serialVersionUID = 1L;
private String firstName;
private String lastName;
public OrderItem() {
public String getFirstName() {
return firstName;
public void setFirstName(String firstName) {
this.firstName = firstName;
public String getLastName() {
return lastName;
public void setLastName(String lastName) {
this.lastName = lastName;
public UserId(String aid) { = aid;
@Id public String getId() {
return id;
protected void setId(String aID) {
id = aID;

This is an simple data entity holding an ID, a first and a last name. To store and access the item a EJB is used

public class CustomerService {
@PersistenceContext(unitName = "org.imixs.workflow.jpa")
private EntityManager manager;
public void updateUser(Customer customer) {
if ( manager.find(Customer.class, customer.getID())==null) {
} else {

In this simplified example the CustomerService EJB reuses the persistenceContext ‘org.imixs.workflow.jpa’ which is alredy defined by the Imixs-Worklfow engine.

To add the new entity class into the database just the persitence.xml file need to be extended by adding the new class name :

<persistence-unit name="org.imixs.workflow.jpa" transaction-type="JTA">

Now for the new entity a table in the existing database will automatically created during the deployment:

The Plugin API

With the help of the Imixs Plugin API the custom data can easily be integrated into a workflow.

public class CustomerPlugin extends AbstractPlugin {
@EJB CustomerService customerService;

@Override public ItemCollection run(ItemCollection documentContext, ItemCollection documentActivity) throws PluginException {
return documentContext;


By reusing the existing JPA context form the Imixs-Workflow engine it is quite easy to extend the database with custom tables. The JPA service EJB can be injected into a custom plugin and so an integration int your workflow model is also possible.


As you can see there a different ways to store business data together with the Imixs-Workflow engine. Using JPA gives you more control of data relation ships but is also more complex. The advantage of embedding data into the process instance is that this data is automatically read and write protected by the workflow engine. A combination of both can be a effective solution to store complex data aligned to your business process.

Leave a Comment

Get the BPI Web Feed

Using the HTML code below, you can display this Business Process Incubator page content with the current filter and sorting inside your web site for FREE.

Copy/Paste this code in your website html code:

<iframe src="" frameborder="0" scrolling="auto" width="100%" height="700">

Customizing your BPI Web Feed

You can click on the Get the BPI Web Feed link on any of our page to create the best possible feed for your site. Here are a few tips to customize your BPI Web Feed.

Customizing the Content Filter
On any page, you can add filter criteria using the MORE FILTERS interface:

Customizing the Content Filter

Customizing the Content Sorting
Clicking on the sorting options will also change the way your BPI Web Feed will be ordered on your site:

Get the BPI Web Feed

Some integration examples