Imixs-Workflow Microservice
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


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.

The Imixs-Microservice project encapsulates the Imixs-Workflow Engine into a RESTful web service interface. The Imixs-Microservice can be bound to any business application, independent from the technology behind. In this architectural style the business logic can be changed without changing a single line of code.

A business process can be described by a BPMN Model using the Eclipse based Imixs-Workflow-Modelling Tool. Business data can be created, published and processed either in XML or JSON format.

See also [Marin Fowlers Blog)( for further information about the concepts of microservices.


Imixs-Workflow is based on the Java EE specification and can be deployed into any Java EE compatible application server like GlassFish or JBoss/Wildfly. See the deployment guide for further information.


Imixs-Microservice provides also a docker image. This makes is easy to run the Imixs-Microservice in a Docker container. See the docker section below.

Imixs-Admin Client

The Imixs/Imixs-Microservice image contains the latest version of the Imixs-Admin Client. The Imixs-Admin Client can be used to administrate a Imixs-Workflow instance

Initalize User DB

After the first deployment the database is initialized automatically with a default model (ticket.bpmn) and the default user 'admin' with the default password 'adminadmin'.

You can initialize the internal UserDB manually by calling the setup URL


You can add additional accounts or change the default account later using the 'User-REST service' interface.

How to Deploy a BPMN Model

After you have setup the Imixs-Workfow Microservice you can deploy a workflow Model. A workflow model can be created using the Imixs-BPMN eclipse Plugin. A workflow Model can be deployed into the Imixs-Microservice using the 'Model-REST service' interface. You can deploy the default 'Ticket Workflow' using the following curl command:

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

The example model is included in the Imixs-Microservice project located at: /src/main/resources/ticket.bpmn

Verify Model

To verify if the model was deployed successfully you can check the deployed model version with the Rest API:


If no model version is yet deployed, you can create and upload a new BPMN Model using the Imixs-BPMN-Modeller.

How to Manage a Process Instance

The following section includes some short examples how to create, process and verify a workflow instance managed by the Imxis-Workflow Microservicve. See the Imixs-Workflow Project for more information.

NOTE: you need to authenticate against the rest service. Use the default user 'admin' and the default password 'adminadmin' to test

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:


The result will include all workitems for the current user.

Create a new Process Instance

To create a new process instance you can POST a JSON Object to the Imixs-Microservice in the following way

POST = http://localhost/imixs-microservice/workflow/workitem

To create a valid workitem the following attributes are mandatory:

  • $modelversion = the version of your model
  • $processid = the start process
  • $activityid = the activity to be processed

See the following Example:

 {"name":"_subject","value":{"@type":"xs:string","$":"Some usefull data.."}}

The example below shows how to post a new Workitem in JSON Format using the curl command. The request post a JSON structure for a new workitem with the $modelVerson 1.0.0 , ProcessID 10 and ActivityID 10.

curl --user admin:adminadmin -H "Content-Type: application/json" -d \
       '{"item":[ \
                 {"name":"type","value":{"@type":"xs:string","$":"workitem"}}, \
                 {"name":"$modelversion","value":{"@type":"xs:string","$":"1.0.1"}}, \
                 {"name":"$processid","value":{"@type":"xs:int","$":"1000"}}, \
                 {"name":"$activityid","value":{"@type":"xs:int","$":"10"}}, \
         ]}' \

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:

   {"name":"_subject","value":{"@type":"xs:string","$":"JUnit Test-6476"}}, 

The workitem includes the attribute '$uniqueid' wich is used ot identify the process instance later. Also workflow information like the current status or the owner is returend by the service.

There are serveral Resouce 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/workflow/rest-service/workflow/workitem/[UNIQUEID]

curl command:

curl --user admin:adminadmin \
      -H "Accept: application/json"  \

To change the status of a process instance you simply need to post uniqueid together with the next workflow activity defined by your workflow model

POST = http://localhost/workflow/rest-service/workflow/workitem/[UNIQUEID]

     {"name":"_subject","value":{"@type":"xs:string","$":"Some usefull data.."}}
     {"name":"_customdata","value":{"@type":"xs:string","$":"Some more data.."}}

Within the object you can define any kind of data to be stored together with the process instance.

Task Lists

Imixs-Workflow provides several 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/json" \

Find more details about the Imixs-Rest API here

JUnit Tests

The Imixs-Microservice project provide a set of JUnit Tests. These tests can be used also as a starting point to see how the RestService API works.

User Management

The Imixs-Microservice provides a user managemetn service to store user credentials into the existing database connection (jdbc/imixs-microservice). This service is recommended for test and development only.

The userManagement service provides a rest API to create a new user or update an existing account. The service expects a JSON structure with the user id, groups and password:


Example curl command:

curl --user admin:adminadmin -H "Content-Type: application/json" -d \
       '{"item":[  \
            {"name":"type","value":{"@type":"xs:string","$":"profile"}}, \
            {"name":"txtname","value":{"@type":"xs:string","$":"USER_NAME"}}, \
            {"name":"txtpassword","value":{"@type":"xs:string","$":"USER_PASSWORD"}}, \
            {"name":"txtgroups","value":{"@type":"xs:string","$":"IMIXS-WORKFLOW-Author"}} \
         ]}' \

Imixs-Microservice provides a Docker Container to be used to run the service on a Docker host. The docker image is based on the docker image imixs/wildfly.

1. Build the image

To build the artifact run the maven command:

mvn clean install -DskipTests

To build the docker image run:

docker build --tag=imixs/imixs-microservice .

2. Run with docker-compose

You can start the Imixs-Microservice docker container with the docker-compose command:

docker-compose up

Note: this command will start two container, a postgreSQL server and a Wildfly Server.

For further details see the imixs/wildfly docker image.

3. Development

During development the docker container can be used with mounting an external deployments/ folder:

docker run --name="imixs-microservice" -d -p 8080:8080 -p 9990:9990 \
     -e WILDFLY_PASS="admin_password" \
     -v ~/git/imixs-microservice/deployments:/opt/wildfly/standalone/deployments/:rw \


Imixs-Microservice needs a postgreSQL database to be run. To start both containers a docker-compose script is provided to simplify the startup. The following example shows the docker-compose.yml for imixs-microservice. You can customize this .yml file to your needs:

  image: postgres
    POSTGRES_PASSWORD: adminadmin
    POSTGRES_DB: imixs01

  image: imixs/imixs-microservice
    WILDFLY_PASS: adminadmin
    - "8080:8080"
    - "9990:9990"
    - postgres:postgres

Take care about the link to the postgres container. The host name 'postgres' is needed to be used in the standalone.xml configuration file in wildfly to access the postgres server for the database pool configuration.