The Microservice Architecture

The Imixs-Workflow Rest API allows you to encapsulate the Imixs-Workflow engine into a single service within a modern Microservice Architecture. In this way, you can connect the Imixs-Workflow engine to any kind of business application, regardless of the technology behind it. You can change your business logic without changing a single line of code.

Running With Docker

Imixs-Workflow can be run in a Docker container, which makes it easy for you to start with. A Imixs-Workflow microservice 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

The Imixs-Workflow Rest API allows you 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

Before you start, you need to define a workflow model. Use the Imixs-BPMN modeler to create your model. To deploy your model, use the Rest Model Service. The following example hows you you deploy a model with the curl commandline tool:

$ 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

After you have created and deployed your model, you can start and and manage a process instance via the Rest API. You can provide data in XML or in JSON format.

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 by the Imixs-Worklfow engine, 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":"$task","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, you can update it and send it back to the workflow engine by the POST method. The workflow engine will process the workitem based on the corresponding workflow event defined in the BPMN model. See the following example which updates the attributes '_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":"$event","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.