In this short tutorial, I would like to show you how you can run a human cenctric 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 embedded 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 you 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 Imixs-Workflow engine.
Create your Workflow Model
Before we start we create a Workflow Model describing our business process. You create a 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 a 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 is a Jakarta EE service component. This means you can run the engine on any Jakarta EE compliant application server. Currently you can choose from the following servers:
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 an microservice. The Rest API is also used to upload your worfklow 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 Enterprse stack so there is no need to add any additional libraries. For the deployment of Imixs-Workflow, there are two points that are significant for a workflow engine. The persistence and the 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 a important aspect for a workflow engine. In Imixs-Workflow you need t authenticate users to be allowed 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-Relams 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 into 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 also use this also for your own project. A Docker container can be used for development as also for productive purpose. 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 setup 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 unqiue 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.
3 Replies to “Tutorial: Imixs-Workflow and Jakarta EE”