Tutorial: Imixs-Workflow and Jakarta EE

In this short tutorial, I would like to show you how you can run a human-centric workflow engine on Jakarta EE. Jakarta EE is the successor of Java EE and like the previous version, Jakarta EE offers you a full stack Java platform for enterprise applications. The Open Source Workflow Engine Imixs-Workflow is based on this platform from the early beginning of Java EE.

Imixs-Workflow provides you with a powerful, scalable and transactional workflow engine for Java Enterprise Applications. You can embed the workflow engine in your Jakarta EE project or run the engine as a Microservice based on Jakarta EE.

The idea of the project is to move most of the usual business logic into a model. As a result, you can change and optimize your application in a model-driven way. The project supports the Business Process Modeling Notation (BPMN 2.0). BPMN enables you to describe your business process from different perspectives. You can describe the organizational aspects just to give people an understanding of your process. And you can as well model the technical details to execute your process with the Imixs-Workflow engine.

Create your Workflow Model

Before we start we create a Workflow Model describing our business process. You create an Imixs-Workflow model with the Eclipse-based modeling tool Imixs-BPMN. In Imixs-Workflow the process status is described with the BPMN element 'Task'. The status change between the Task elements is defined by BPMN element 'Event'.

For each task element, you can define the responsibilities and access control list (ACL). When you later start the workflow, each process instance will be automatically assigned to the roles defined by your model.

You can download an example model from the Imixs-Microservice project on Github.

The Workflow Engine

Imixs-Workflow acts as a service within the Jakarta EE component model. This means you can run the engine on any Jakarta EE compliant application server. Currently, you can choose from the following servers:

• JBoss/Wildfly
• Payara
• Open Liberty
• Apache TomEE

You can integrate the Imixs-Workflow engine into your project just by adding the corresponding maven dependency.

<dependency>
  <groupId>org.imixs.workflow</groupId>
  <artifactId>imixs-workflow-engine</artifactId>
  <version>${org.imixs.workflow.version}</version>
</dependency>
<dependency>
  <groupId>org.imixs.workflow</groupId>
  <artifactId>imixs-workflow-jax-rs</artifactId>
  <version>${org.imixs.workflow.version}</version>
</dependency>

Take a look at the release list to find out the latest version.

The component imixs-workflow-jax-rs provides a Rest API. With this API you can run Imixs-Workflow as a microservice. The Rest API is also used to upload your workflow model into the workflow engine. You can read more about the Rest API of Imixs-Workflow here.

Lucene Search

A workflow engine typically manages unstructured data in the form of documents. The full-text search of Lucene is used to search this data. You need to add the lucene search engine as well with the following maven dependencies:

<dependency>
  <groupId>org.apache.lucene</groupId>
  <artifactId>lucene-core</artifactId>
  <version>7.5.0</version>
</dependency>
<dependency>
  <groupId>org.apache.lucene</groupId>
  <artifactId>lucene-analyzers-common</artifactId>
  <version>7.5.0</version>
</dependency>
<dependency>
  <groupId>org.apache.lucene</groupId>
  <artifactId>lucene-queryparser</artifactId>
  <version>7.5.0</version>
</dependency>

The Deployment

Now its time to deploy your application. Jakarta EE offers you a full Java Enterprise stack so there is no need to add any additional libraries. For the deployment of Imixs-Workflow, there are two points that are significant to a workflow engine: persistence and security.

Persistence

In Jakarta EE data can easily be stored into a database using the Java Persistence API (JPA). For this purpose, it is necessary to specify a data source. This can be done within your Application Server. Any standard SQL database can be used here.

For example, in the Wildfly Application Server you can define a data-source from the web admin interface:

To link this data source with your application, a JPA descriptor named 'persistence.xml' need to be added into your application:

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="1.0" xmlns="http://java.sun.com/xml/ns/persistence">
	<persistence-unit name="org.imixs.workflow.jpa" transaction-type="JTA">	
		<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>	
		<jta-data-source>jdbc/imixs-microservice</jta-data-source>
		<jar-file>lib/imixs-workflow-engine-${org.imixs.workflow.version}.jar</jar-file>
		<properties>
			<!-- target-database Auto MySQL PostgreSQL  -->
			<property name="eclipselink.target-database" value="Auto" />
			<property name="eclipselink.ddl-generation" value="create-tables" />
			<property name="eclipselink.deploy-on-startup" value="true" />
		</properties>				
	</persistence-unit>
</persistence>

This file is simply placed in the META-INF/ folder of your application or microservice. Note that in this example I use EclipseLink as a JPA provider which need to be part of your server setup.

Security

Security is the second notable aspect of Imixs-Workflow. Users need to be authenticated to access the workflow engine. On the other hand, Imixs-Workflow protects your business data in a perfect way. Like the persistence also the security is part of Jakarta EE and can be fully managed in your application server. This means you can use different authentication modules like Database-Realms, LDAP-Realms or simple File-Realms.

The following example shows the definition of a file-realm in the Wildfly Application Server using again the web admin interface:

The security realm is typically mapped by a deployment descriptor like the jboss-web.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<jboss-web>
   <security-domain>imixsrealm</security-domain>
   <context-root>imixs-microservice</context-root>
</jboss-web>

This descriptor is placed in the WEB-INF/ folder. You can find a complete project setup in the Imixs-Microservice project on Github. You can use this project as a template for your own application.

Docker Support

The Imixs-Microservice project on Github provides a docker image. This makes it easy to run the Imixs-Microservice out of the box in a Docker container. You can use this image for your own project. A Docker container can also be used as a productive tool for development. To build the Docker container run:

$ mvn clean install -Pdocker

To start the Imixs-Microservice as a docker container you only need to define a container stack description with Docker Compose. Docker Compose is a tool for defining and running a stack of multiple Docker containers. The following docker compose file includes a Postgres database service and the Jakarta EE Application server Wildfly:

version: '3.1'
services:
  db:
    image: postgres:9.6.1
    environment:
      POSTGRES_PASSWORD: adminadmin
      POSTGRES_DB: workflow
  app:
    image: imixs/imixs-microservice
    environment:
      WILDFLY_PASS: adminadmin
      DEBUG: "true"
      POSTGRES_USER: "postgres"
      POSTGRES_PASSWORD: "adminadmin"
      POSTGRES_CONNECTION: "jdbc:postgresql://db/workflow"
    ports:
      - "8080:8080"
      - "9990:9990"

With a single command, you create and start all the services with your own configuration defined in the docker-compose.yml file:

$ docker-compose up

Testing the Workflow Engine

After you have set up your project and application server you can deploy and test your application. As mentioned earlier, Imixs-Workflow includes a Rest API. Via this API you can transfer the model you created earlier. The following example shows how to upload the model with the 'curl' command:

curl --user admin:adminadmin --request POST -Tticket.bpmn http://localhost:8080/imixs-microservice/model/bpmn

The curl command includes the userId/password to authenticate against the workflow engine with the security realm we defined earlier in our application server.

You can verify the status of your service by the following URL:

http://localhost:8080/imixs-microservice/model

Starting a New Process Instance

With the Imixs-Rest API, you can now start a new process instance based on your model definition. This can be done with a JSON request. See the following curl example:

curl --user admin:adminadmin -H "Content-Type: application/json" -H "Accept: application/json" -d \
       '{"item":[ \
                 {"name":"type","value":{"@type":"xs:string","$":"workitem"}}, \
                 {"name":"$modelversion","value":{"@type":"xs:string","$":"1.0.1"}}, \
                 {"name":"$taskid","value":{"@type":"xs:int","$":"1000"}}, \
                 {"name":"$eventid","value":{"@type":"xs:int","$":"10"}}, \
                 {"name":"txtname","value":{"@type":"xs:string","$":"test-json"}}\
         ]}' \
         http://localhost:8080/imixs-microservice/workflow/workitem.json

This will create a new process instance with some business data (item 'txtname'='test-json'). The Imixs-Workflow engine will now add automatically processing information and returns a unique identifier. See more about "How to manage business data" on the project home.

You can test the newly created running process instances also by a URL:

http://localhost:8080/imixs-microservice/workflow/tasklist/creator/admin

Conclusion

With this brief insight, I have shown how you can develop and operate a highly scalable workflow engine with Jakarta EE. The advantage of this platform is that many parts for a business application are already available and do not need to be installed manually. This simplifies the development of business applications and offers much more possibilities to run and operate modern applications.

On the other hand, the Imixs-Workflow engine offers a model-driven approach to keep business logic flexible. This opens up a multitude of possibilities for realizing complex business processes in an easy and flexible way.