Build your Business App with BPMN 2.0

Blog: Imixs Workflow Blog

In this short tutorial I will explain how to build a business application with the Business Process Modelling Notation – BPMN. This approach differs from the usual data-centric approach as we focus on process management instead of data processing.

Data Processing vs. Process Management

When we follow the classical approach building a Data-Centric Business Application, we usually first design a data schema. The data schema defines what kind of data can be managed. The application allows us to create new data sets, edit existing data and of course search for data.

In a Process-Centric Business Application we instead first try to answer the question how data should be processed to give each actor the best access to information to reach a specific business goal. And this kind of question becomes more and more important in our today’s rapidly evolving business landscape. BPMN offers the perfect approach to model a workflow with its business goals from the beginning to the end. BPMN models can be created with various tools like for example the Open Source BPMN designer Open-BPMN.

One advantage of BPMN is that it does not only give all stake holders a more clear understanding about the process, a BPMN 2.0 Model can also be executed by a suitable process engine. This “low-code” or “model-driven” approach leads to a much more flexible way to implement business applications. Of course, data still plays an important role and workflow engines allow us to manage business data in various ways. So let’s see how this works…

Start with a Business Process…

First of all we have to think about the business process behind our business app. We need to focus on questions like:

Why do we need this kind of information?
Who is responsible to create the data?
How does the data need to be processed?
What do we expect to happen to our data?

As mentioned before a business process defines the way to achieve a concrete business goal. In a BPMN model we can describe this way form its beginning to the end. See the following example of a ‘Proposal Creation Process‘:

The BPMN model defines a Start (green) and End (red) event to mark the begin and end of the process. An Activity or Task Element (blue boxes in this diagram) defines a single step in a business process. This can also be a milestone to be reached. An event (blue circle) defines the transition into a new task or status. An event can be triggered external (e.g. ‘Order received form customer’) or by an actor (e.g. ‘Proposal created and submit for review’).

Business Rules

In addition we can define business rules to implement additional business logic. For example we can define that a Review in this process is only needed for Proposals with a bid amount over 1.000,00 EUR. For this you can define an Exclusive Gateway with conditional flows:

In this example the transition (Sequence Flow) between ‘Gateway-1’ and the ‘Review Task’ contains a condition like:

workitem.getItemValueDouble('amount')>=1000.0

A BPMN engine can evaluate these kind of conditions by different script languages based on the data provided in the workflow. The data can either be stored directly in the process instance, or defined as a reference to an external data source. There are a number of more elements defined in the BPMN 2.0 standard that allow the modeling even of much more complex business processes.

Run Your Business Process…

Now let’s see how we can start and control such a BPMN process in an application. There are various BPMN engines available and a lot of them are open source. See the list of awesome-workflow-engines maintained by @meirwah on Github.

In the following I use the Imixs-Workflow engine which supports BPMN 2.0 and provides a docker container to start out of the box without the need to write any code. With the Imixs-Microservice we can start the BPMN Workflow engine in a container. Just create a local docker-compose.yaml file with the following content:

services:
  imixs-db:
    image: postgres:13.11
    environment:
      POSTGRES_PASSWORD: adminadmin
      POSTGRES_DB: workflow-db  
  imixs-app:
    image: imixs/imixs-microservice:latest
    environment:
      TZ: "CET" 
      LANG: "en_US.UTF-8"  
      POSTGRES_USER: "postgres"
      POSTGRES_PASSWORD: "adminadmin"
      POSTGRES_CONNECTION: "jdbc:postgresql://imixs-db/workflow-db"
    ports:
      - "8080:8080"

…and start the service with:

$ docker compose up

The service comes with a short welcome page at: http://localhost:8080 and also provides a Rest interface at http://localhost:8080/api/openapi-ui/index.html. This web interface allows us to test various methods to create a workflow or to process existing ones.

Upload your Model

First we need to upload our model. For this we can use the curl command and post our BPMN file to the Rest Service endpoint:

$ curl --user admin:adminadmin --request POST 
-Tmy-model.bpmn http://localhost:8080/api/model/bpmn

You can download the model from Github or you create a new file my-model.bpmn with the following content:



  
    
      
    
    
      
      
      
    
    
      
      
      
      
      
    
    true
  
  
    
      
    
    
    
    
  
  
    
  
  
    
      
        Task_2
        IntermediateCatchEvent_1
        StartEvent_1
        Task_1
        IntermediateCatchEvent_7
        Task_4
        EndEvent_1
        IntermediateCatchEvent_8
        
        TextAnnotation_2
        gateway_R0B00Q
        gateway_7zm0sw
      
    
    
      
        
          <![CDATA[subject ]]>
        
        
          true
        
        
        
      
      
      sequenceFlow_fCuqCw
      sequenceFlow_7jbDFQ
    
    
      SequenceFlow_12
      
    
    
      
        
          <![CDATA[Order submitted by $Editor]]>
        
        
          <![CDATA[20]]>
        
        
          false
        
        
        
        
      
      <b>Submit</b> a new ticket
      SequenceFlow_11
      SequenceFlow_3
      
    
    
      
    
    
      
        
          <![CDATA[subject ]]>
        
        
          true
        
      
      SequenceFlow_12
      
      sequenceFlow_BYx0Eg
      sequenceFlow_O00HWA
    
    
      
    
    
      SequenceFlow_1
      
    
    
      
    
    
      
        
          <![CDATA[subject ]]>
        
        
          
        
      
      Create a new ticket
      SequenceFlow_1
      SequenceFlow_11
      sequenceFlow_jspJig
    
    
      
    
    
      
        
          
        
        
          false
        
        
        
          
        
      
      
      sequenceFlow_Wn3NGw
      sequenceFlow_BYx0Eg
    
    
      
        
          <![CDATA[ticket solved by namcurrentEditor]]>
        
        
          false
        
        
        
          
        
      
      
      sequenceFlow_GNxY5A
      sequenceFlow_jspJig
    
    
      
      
    
    
      
      sequenceFlow_fCuqCw
      sequenceFlow_GNxY5A
      sequenceFlow_Wn3NGw
    
    
      
    
    
      
    
    
      
    
    
      
    
    
      
    
    
      
      SequenceFlow_3
      sequenceFlow_7jbDFQ
      sequenceFlow_O00HWA
    
    
      
      =1000.0]]>

We can also post the model via the Rest UI at the resource /api/model/bpmn/

The status of all available models can be verified at:

http://localhost:8080/api/model

Note: I use the userid ‘admin’ with the password ‘adminadmin’ here. More users with different roles are defined by this service. Find the details here.

Create a Process Instance

Now as the service is up and running, we can create our first process instance. For this we just need to post a XML Document containing the model information and our business data. We can use the Rest API Endpoint to post a new process instance at

POST: /api/workflow/workitem


	proposal-en-1.0
	1000
	10
	
		My first propsal...
	
	
		500.0

In this example I define the modelversion, the initial task and the event to be processed, as also some custom business data (subject and amount).

The workflow engine automatically executes the data according to our uploaded BPMN model. To verify the result we can check the tasklist with all process instances created by the user ‘admin’:

http://localhost:8080/api/workflow/tasklist/creator/admin

As you can see the workflow engine has processed our data and applies the status ‘Completed‘ to our new workflow instance. To test our business logic we can now change the amount to a value greater than 1.000,00 which will create another new process instance in the status ‘Review’ according to our business rule.

We can now easily change the process logic and add new tasks or business rules. All we have to do is to upload the new version of the BPMN model.

To update the data of an existing process instance we can now post the data together with the $uniqueid and the corresponding event from our model:


	8333c61c-b973-4591-aabf-ec92bd59d74b
	10
	
		Baker Street 221b.

The field $uniqueid is returned by the first creation of a new workflow instance and can be used as a reference for further processing steps. The Workflow engine will verify each event according to the assigend model. We can also use the uniqueID to fetch the data from the workflow engine, e.g. to display the data in a web interface.

How to Integrate BPMN into your App?

In this tutorial, I have deliberately omitted the design of a web interface because I wanted to focus on the business logic. When using a Rest API – as in this example – the workflow engine can be integrated into an application easily by using different frontend technologies. In addition, there are often other ways to connect a BPMN engine to your own application depending on the framework used by the engine. For example a lot of Open Source Engines are based on Java and can be integreated by common build tools like Maven or Gradle.

For example you can integrate the Imixs Workflow engine into a Jakarta EE app with the following dependencies:

...
	
		org.imixs.workflow
		imixs-workflow-engine
		${org.imixs.workflow.version}
	
	
		org.imixs.workflow
		imixs-workflow-index-lucene
		${org.imixs.workflow.version}
	
...

… and call the engine within your code using the CDI Framework like this:

@Inject
private org.imixs.workflow.engine.WorkflowService workflowService;

ItemCollection workitem=new ItemCollection().model("proposal-en-1.0").task(1000).event(10);
// assign some business data...
workitem.setItemValue("amount",500.0);
// process the workitem
workitem = workflowService.processWorkItem(workitem);

This code example is equal to the Rest API call in the example above.

Data Integration

Another aspect is the way you handle your business data. In my example code I embedded the business data directly into the workflow instance.

But of course in some szenarious it may be usefull to just store a reference to an external dataset

or reference the workflow instance inside your data processing application by extending the data schema.

Conclusion

In summary, incorporating BPMN 2.0 into your business application development offers a structured and efficient way to handle your business processes. The ability to visually model workflows not only simplifies the design and management of complex systems but also enhances collaboration across teams. By using tools like Imixs-Workflow, you can easily implement BPMN 2.0 standards, ensuring that your business applications are both scalable and adaptable. Embracing BPMN 2.0 can lead to more organized, transparent, and effective business operations, setting the stage for greater success and growth.