JarCastingThe Imixs-Microservice
The Imixs-Microservice is running the Imixs-Workflow Engine into a microservice. This microservice can be bound to any business application, independent from the technology behind. Imixs-Workflow is an open source workflow engine for human-centric business process management (BPM). Human-centric BPM means to support human skills and activities by a task orientated workflow-engine. Read more about Imixs-Workflow here.
The Rest API
Imixs-Microservice provides a Rest API to interact with the Imixs-Workflow Engine. See the Imixs-Workflow Rest API for more information.
BPMN 2.0
The 'Business Process Model and Notation' - BPMN 2.0 is the common standard to describe a business process. BPMN was initially designed to describe a business process without all the technical details of a software system. As a result, a BPMN diagram is easy to understand and a good starting point to talk about a business process with technician as also with management people.
Imixs-Workflow supports the BPMN 2.0 standard and provides the free modeling tool - Imixs-BPMN. Imixs-BPMN takes the full advantage of all the capabilities of BPMN 2.0 and complements them with the features of a powerful workflow engine.
How to Install
Imixs-Microservice is based on the Jakarta EE and Eclipse Microprofile and can be deployed into any enterprise application server like JBoss/Wildfly, Payara or OpenLiberty. See the Imixs-Workflow deployment guide for further information.
Run with Docker
Imixs-Microservice provides also a docker image, making it easy to run the Imixs-Microservice out of the box in a Docker container. This container image can be used for development as also for productive purpose. The docker image is based on payara-micro which is optimized for cloud environments like Kubernetes, OpenShift or Docker-Swarm.
To start the Imixs-Microservice you just need to define a container stack with Docker Compose. A docker-compose.yml file is already part of the project and can be downloaded from here.
To start the service run:
$ docker-compose up
The Imixs Rest API is available under the following URL
http://localhost:8080/api
Authentication and Authorization
Imixs-Workflow is a Human-Centric workflow engine. This means that each actor is authenticated against the service. The Workflow Engine is based on the Java EE and so the authentication is also standardized and supports different authentication solutions like LDAP, Database, SSO and more.
The default Docker installation provides a set of predefined user accounts which can be used for testing purpose:
| User | Role | Password |
|---|---|---|
| admin | IMIXS-WORKFLOW-Manager | adminadmin |
| alex | IMIXS-WORKFLOW-Manager | password |
| marty | IMIXS-WORKFLOW-Author | password |
| melman | IMIXS-WORKFLOW-Author | password |
| gloria | IMIXS-WORKFLOW-Author | password |
| skipper | IMIXS-WORKFLOW-Author | password |
| kowalski | IMIXS-WORKFLOW-Author | password |
| private | IMIXS-WORKFLOW-Author | password |
| rico | IMIXS-WORKFLOW-Author | password |
You can add or change accounts by updating the property files:
- imixs-roles.properties
- imixs-users.properties
And of course you can configure a different custom security realm (e.g. LDAP).
The Imixs-Admin Client
When you start the docker-compose setup also an additional admin service will be started. The Imixs-Admin Client is a web tool to administrate a running instance of the Imixs-Workflow Engine.
You can open the Imixs-Admin Client from your browser with at the following location:
http://localhost:8888/
The connect URL to connect the Imixs-Admin Tool with your microservice is http://app:8080/api
Within the Imixs-Admin client you can manage your BPMN models and you can search and inspect running process instances. To learn more about all the Imixs-Admin client, see the official documentation.
How to Work With the Imixs-Microservice
After you have started the Imixs-Microservce a full featured Imixs-Workflow instance is ready to be used within your business application project. The following section includes some short examples how to create, process and verify a Imixs-Workflow instance.
NOTE: You need to authenticate against the rest service API. In this examples we will use the default user 'admin' with the default password 'adminadmin'.
How to Deploy a BPMN Model
Imixs-Microservice automatically loads a default BPMN model from the location defined by the environment variable 'IMIXS_MODEL' during the startup. You can also add or update a model created with Imixs-BPMN during runtime via the Imixs Rest API. See the following curl command:
curl --user admin:adminadmin --request POST -Tticket-en-1.0.0.bpmn http://localhost:8080/api/model/bpmn
An example model is included in the Imixs-Microservice project located at: /src/model/ticket-en-1.0.0.bpmn
NOTE: cURL isn't installed in Windows by default. See the Use Curl on Windows discussion on stackoverflow.
Verify Model
To verify if the model was deployed successfully you can check the model repository form your web browser:
http://localhost:8080/api/model
Create a new Process Instance
To create a new process instance you can POST a XML or an JSON Object to the Imixs-Microservice Rest API:
POST = http://localhost:8080/api/workflow/workitem
To create a valid workitem the following attributes are mandatory:
- $modelversion = the version of your model
- $taskid = the start task in your model
- $eventid = the initial event to be processed by the Imixs-Worklfow engine
See the following XML Example:
<document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<item name="$modelversion">
<value xsi:type="xs:string">1.0</value>
</item>
<item name="$taskid">
<value xsi:type="xs:int">1000</value>
</item>
<item name="$eventid">
<value xsi:type="xs:int">10</value>
</item>
<item name="_subject">
<value xsi:type="xs:string">some data...</value>
<value xsi:type="xs:string">more data...</value>
</item>
</document>
As you can see you can specify the data types for each value. This is an important function to distinguish between data types such as Integer, Float order Date.
The example below shows how to post a new Workitem in the XML format using the curl command. The request creates a new process instance with the $modelVerson 1.0, TaskID 10 and the inital EventID 10.
curl --user admin:adminadmin -H "Content-Type: application/xml" -H 'Accept: application/xml' -d \
'<document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<item name="$modelversion"><value xsi:type="xs:string">1.0</value></item>
<item name="$taskid"><value xsi:type="xs:int">1000</value></item>
<item name="$eventid"><value xsi:type="xs:int">10</value></item>
<item name="_subject">
<value xsi:type="xs:string">some data...</value>
<value xsi:type="xs:string">more data...</value>
</item>
</document>' \
http://localhost:8080/api/workflow/workitem
Once you created a new process instance based on a predefined model you got a set of data back form the workflow engine describing the state of your new business object which is now controlled by the workflow engine. This is called the workitem:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<data xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<document>
<item name="$created">
<value xsi:type="xs:dateTime">2020-02-08T15:00:08.798Z</value>
</item>
<item name="$creator">
<value xsi:type="xs:string">admin</value>
</item>
<item name="$editor">
<value xsi:type="xs:string">admin</value>
</item>
<item name="$modelversion">
<value xsi:type="xs:string">1.0</value>
</item>
<item name="$modified">
<value xsi:type="xs:dateTime">2020-02-08T15:00:08.798Z</value>
</item>
<item name="$taskid">
<value xsi:type="xs:int">1100</value>
</item>
<item name="$uniqueid">
<value xsi:type="xs:string">8d5ca28d-e891-465a-a187-ae5f31a5cc26</value>
</item>
<item name="$workflowgroup">
<value xsi:type="xs:string">Ticket</value>
</item>
<item name="$workflowstatus">
<value xsi:type="xs:string">Open</value>
</item>
<item name="$workflowsummary">
<value xsi:type="xs:string">
</value>
</item>
<item name="$workitemid">
<value xsi:type="xs:string">3f233e19-5d7a-42bd-a800-aeae7936a56e</value>
</item>
<item name="$writeaccess">
<value xsi:type="xs:string"></value>
</item>
<item name="_subject">
<value xsi:type="xs:string">some data...</value>
<value xsi:type="xs:string">more data...</value>
</item>
<item name="type">
<value xsi:type="xs:string">workitem</value>
</item>
</document>
</data>
The workitem includes the attribute '$uniqueid' which is used to identify the process instance later. Also workflow information like the current status or the editor is returned by the service.
There are several Resource URIs to request the state of a process instance. Using the $uniqueid returned by the POST method you can request the current status of a single process instance:
GET = http://localhost:8080/api/workflow/workitem/[UNIQUEID]
curl command:
curl --user admin:adminadmin \
-H "Accept: application/xml" \
http://localhost:8080/api/workflow/workitem/[UNIQUEID]
To change the status of a process instance you can post an updated version of your process instance together with the event to be processed:
POST = http://localhost:8080/api/workflow/workitem/[UNIQUEID]
<document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<item name="$eventid">
<value xsi:type="xs:int">10</value>
</item>
<item name="_subject">
<value xsi:type="xs:string">...some other business data...</value>
</item>
</document>
You can define any kind of business data to be stored together with the process instance.
Open the Task List
Each user involved in a business process has a personal task list (called the 'worklist'). You can request the task list for the current user by the following Rest API URL:
http://[YOURSERVER]/api/workflow/worklist
The result will include all workitems for the current user.
Task Lists
Imixs-Workflow provides several additional resources to request the task list for specific users or object types.
To request the Worklist for the current user 'admin' user you can call:
curl --user admin:adminadmin -H \
"Accept: application/xml" \
http://localhost:8080/api/workflow/tasklist/creator/admin
Find more details about the Imixs-Rest API here.
Using JSON
Imixs-Workflow supports both data formats - XML and JSON. It is recommended to use XML as this data format allows you to define data types. See the Imixs-Rest API Service how to use JSON objects.
Microservice SAGA Pattern
With the Microservice SAGA Pattern you can build a so called SAGA orchestrator to coordinate more complex business processes. The Imixs Project provides the sub project Imixs SAGA. This project extends the concepts of the Imixs-Microservice and allows the orchestration of multiple services within a microservice architecture.
Imixs-Microservice provides a docker image, making it easy to run the Imixs-Microservice out of the box in a Docker container. This container image can be used for development as also for productive purpose. To start the Imixs-Microservice in a docker container you can define a container stack with Docker Compose. Docker Compose is a tool for defining and running a stack of multiple Docker containers.
The following docker-compose.yml file defines the application stack consisting of a PostgreSQL database and a Imixs-Microservice service:
version: '3.3'
services:
db:
image: postgres:9.6.1
environment:
POSTGRES_PASSWORD: adminadmin
POSTGRES_DB: workflow
app:
image: imixs/imixs-microservice
environment:
WILDFLY_PASS: adminadmin
POSTGRES_USER: "postgres"
POSTGRES_PASSWORD: "adminadmin"
POSTGRES_CONNECTION: "jdbc:postgresql://db/workflow"
ports:
- "8080:8080"
To start the service run:
$ docker-compose up
The application can be accessed from a web browser at the following URL:
http://localhost:8080/
The image imixs/imixs-microservice is based on the Docker image imixs/wildfly. You can find details about the base image here.
Provide a Model
You can define a model file to be updloaded during startup of the service. See the following configuration which defines a custom model file to be loaded:
...
app:
image: imixs/imixs-microservice
environment:
WILDFLY_PASS: adminadmin
DEBUG: "true"
POSTGRES_USER: "postgres"
POSTGRES_PASSWORD: "adminadmin"
POSTGRES_CONNECTION: "jdbc:postgresql://db/workflow"
MODEL_DEFAULT_DATA: "/home/imixs/model/ticket-en-1.0.0.bpmn"
ports:
- "8080:8080"
- "9990:9990"
- "8787:8787"
volumes:
- ~/git/imixs-microservice/src/model/:/home/imixs/model/
In this example the model project directory is mapped as a volume to the service instance /home/imixs/model/
You can initialize provided models by calling the Rest API URL:
http://localhost:8080/api/setup
This will automatically reload the models from the defined location.
Development
You can use Imixs-Microservice also as a template for a custom workflow project. To build the project from the source code run the maven command:
$ mvn clean install
To build the Docker image locally from sources run:
$ mvn clean install -Pdocker
Dev Docker Image
The Imixs-Microservice project also includes a docker-compose-dev profile with additional settings and services. To run the Imixs-Microservice in developer mode run:
$ docker-compose -f docker-compose-dev.yml up
You can map a local deployment directory for hot-deployment and model soruces:
...
volumes:
- ~/git/imixs-microservice/src/model/:/home/imixs/model/
- ~/git/imixs-microservice/src/docker/deployments:/opt/wildfly/standalone/deployments/
...
Extend the Imixs-Micorsevice
If you plan to extend the Imixs-Microservice you just need to setup a Maven Overlay Project:
...
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-war-plugin</artifactId>
<version>2.4</version>
<configuration>
<webResources>
<resource>
<filtering>true</filtering>
<!-- this is relative to the pom.xml directory -->
<directory>${custom.webResources}</directory>
<includes>
<include>**/WEB-INF/*</include>
<include>/src/main/resources/*</include>
<!-- include any other file types you want to filter -->
</includes>
</resource>
</webResources>
<overlays>
<overlay>
<groupId>org.imixs.workflow</groupId>
<artifactId>imixs-microservice</artifactId>
</overlay>
</overlays>
</configuration>
</plugin>
</plugins>
....
</build>
.....
This will result in a new Microservice Project including the Imxixs-Microservice Core API. You can customize this project or add additional functionallity like Plug-Ins or Adapter Classes.
Debug
During development the wildfly runs in a debug mode listening on port 8787.
Initialize a Database Connection
The Imixs-Microservice expects a JPA database pool with the JNDI name 'imixs-microservice'. You can use any SQL database vendor. Just configure the JDBC database pool in your application server before your start the deployment.
The docker-compose.yml provided by this project already defines such a stack configuration located in /src/docker/conf/standalone.xml/
The Imixs Rest Client
To access the Imixs-Microservice form a Java application you can use the Imixs-Workflow RestClient provided by the Melman Project.
JUnit Tests
The Imixs-Microservice project provide a set of JUnit Tests. These tests can be used also as a starting point to learn how the RestService API works.
Monitoring
You can use a monitoring tool chain to monitor and analyze the behavior of your microservice. The tool chain in Imixs-Microservice is build up on Prometheus and Grafana.
To start the tool chain run:
$ docker-compose -f docker-compose-prometheus.yml up
This Docker Stack includes an additonal prometheus service and Grafana Service which allows you to monitor and analyze your business case. You can access the Grafana from your web browser:
http://localhost:3000
To configure the prometheus data source just add the Prometheus service endpoint in Grafana:
http://prometheus:9090/
Contribute
General information about Imixs-Workflow can be found on the project site. The docker image is available on Docker Hub.
If you have any questions concerning the Imixs-Microservice please see the Issue Tracker on Github
