How to Handle Your Business Data

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

@EJB
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
workitem=workflowService.processWorkItem(workitem);

This example adds the two custom items ‘_name’ and ‘_title’ to the workitem to be processed. 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 which adds a custom input field:

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

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

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

The Advantage

The advantage of embedding business data into a process instance is that your data is controlled by the workflow engine. 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 you have access to your custom fields:

Now lets see which alternatives you have.

Store Business Data Into a Datatable

An alternative to embed your business data into the process instance is storing the 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 own custom data entities. As the workflow engine already defines a JPA data pool it is easy to reuse this persistence unit for your own custom entities. See the following example:

@javax.persistence.Entity public class Customer implements java.io.Serializable { 
  private static final long serialVersionUID = 1L; 
  private String firstName; 
  private String lastName; 
  public OrderItem() {
    super(); 
  } 
  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) {
   this.id = 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 data a simple EJB is used:

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

In this simplified example the CustomerService EJB reuses the persistenceContext ‘org.imixs.workflow.jpa‘ which is already defined by the Imixs Workflow 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">
....
<jar-file>lib/imixs-workflow-engine-${org.imixs.workflow.version}.jar></jar-file>
<class>myexample.Customer</class>
...

Now during the deployment, a new table in the existing database will be automatically created :

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 {  
   ....    
   customerService.updateUser(myCustomer);  
   return documentContext; 
  }
}

Advantage

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 into a workflow model is also possible.

Conclusion

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 an effective solution to store complex data aligned to your business process.