Imixs-Workflow Microservice

Imixs-Workflow provides a flexible Rest Service API to be used in any kind of modern microservice architecture.

Model your Business Process with BPMN

Read more....


Protect your Business Data

Read more....


Build your Workflow Application on Java EE

Read more....

The Microservice Architecture

Imixs-Workflow provides a Rest Service API to encapsulates the Imixs-Workflow Engine into a microservice. In this architectural style the workflow engine can be bound to any business application, independent from the technology behind. Business logic can be changed without changing a single line of code.

Running With Docker

Imixs-Workflow can be run in a Docker container, making it easy to to start with. To start a Imixs-Workflow Service, a container stack can be created with Docker Compose. Docker Compose is a tool for defining and running a stack of multiple Docker containers. With a single command, you create and start your own configuration defined in a docker-compose.yml file :

$ docker-compose up
See the Imixs-Microservice project for more information about how to use Imixs-Workflow with Docker.

The Rest API

Imixs-Workflow provides a Rest API to interact with the Imixs-Workflow Engine. Business objects can be created, updated and read in JSON or XML format.

How To Upload a BPMN Workflow Model

A Imixs-Workflow model can be created with the Imixs-BPMN modeler and deployed with the following curl command:

$ curl --user USERID:PASSWORD --request POST \
-Tmodel.bpmn http://localhost:8080/workflow/rest-service/model/bpmn
Imixs-Workflow validates the model and creates a model representation within the Imixs-Workflow engine. The model status can be verified from a we browser:
http://HOST:PORT/workflow-service/model

How to Create and Manage a Process Instance

A new process instance based on a BPMN Workflow model can be created and managed via the Rest API. The following example illustrates how to create a new process instance by using the media type 'JSON'.

POST = http://localhost/workflow/rest-service/workflow/workitem.json

To create a valid process instance the following attributes are mandatory:

  • $modelversion = the version of a deployed model
  • $processid = the start process (task)
  • $activityid = the activity to be processed by the engine

See the following JSON Example based on the JAX-RS Jersey API:

 {"item":[
     {"name":"type","value":{"@type":"xs:string","$":"workitem"}},
     {"name":"$modelversion","value":{"@type":"xs:string","$":"1.0.0"}},
     {"name":"$processid","value":{"@type":"xs:int","$":"10"}}, 
     {"name":"$activityid","value":{"@type":"xs:int","$":"10"}}, 
     {"name":"_subject","value":{"@type":"xs:string","$":"Some data.."}}
   ]}  

Once a new process instance was created, Imixs-Workflow returns a new data object describing the state of the new business object - called the 'workitem':

{"item":[
   {"name":"$uniqueid","value":{"@type":"xs:string","$":"141cb98aecc-18544f1b"}},
   {"name":"$modelversion","value":{"@type":"xs:string","$":"my-model-definition-0.0.2"}},
   {"name":"$processid","value":{"@type":"xs:int","$":"2000"}},
   {"name":"namcreator","value":{"@type":"xs:string","$":"admin"}}, 
   {"name":"namcurrenteditor","value":{"@type":"xs:string","$":"admin"}}, 
   {"name":"namowner","value":{"@type":"xs:string","$":"admin"}}, 
   {"name":"$isauthor","value":{"@type":"xs:boolean","$":"true"}},
   {"name":"_subject","value":{"@type":"xs:string","$":"JUnit Test-0001"}}, 
   {"name":"txtworkflowstatus","value":{"@type":"xs:string","$":"New ticket created"}}, 
   {"name":"txtworkflowresultmessage","value":{"@type":"xs:string","$":""}}
  ]}

The workitem includes the attribute '$uniqueid' which identifies the process instance for later processing. Also workflow information like the current status or the owner of a running process instance are returned by the service.

To change the status of a process instance a workitem can be updated and send back to the workflow engine by the POST method. The workflow engine will process the workitem based on the corresponding workflow activity (event) defined in the BPMN model. See the following example which updates the atributes '_subject' and '_customdata' and triggers the BPMN event with the id:1.

POST = http://localhost/workflow/rest-service/workflow/workitem.json
 {"item":[
     {"name":"$uniqueid","value":{"@type":"xs:string","$":"141cb98aecc-18544f1b"}},
     {"name":"$activityid","value":{"@type":"xs:int","$":"1"}}, 
     {"name":"_subject","value":{"@type":"xs:string","$":"Some usefull data.."}}
     {"name":"_customdata","value":{"@type":"xs:string","$":"Some data.."}}
   ]}  

A workitem is a flexible data structure and can define any kind of data to be stored together with the process instance.

See the section Imixs-Workflow Rest API to learn more about this feature.

back