Skip to content
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Join the chat at Build Status License

The goal of this project is to provide components to interact with the Imixs-Workflow Rest API. These components are agnostic from an Imixs-Workflow Implementation and can be used in a microservice architecture. The components are based on Java JAX-RS and JAX-B.


Using Maven add the following dependencies to your project:

<!-- JEE Dependencies -->

Imixs-Melman is based on Jax-RS 2.0. So you may need to add the missing Java dependencies. For jUnit test you can add the following dependencys to test Jax-RS 2.0

<!-- JAX-RS 2.0 Test dependencies -->


These are examples how to use Imixs-Melman. For details see also the Imixs-Workflow Rest-API.

Initalization & Authentication

Each request against the Imixs-Workflow engine must be authenticated. For that reason Imixs-Melman provides some AuthenticatonRequestFilter.

// Init the workflowClient with a basis URL
WorkflowClient workflowCLient = new WorkflowClient("http://localhost:8080/office-rest/");
// Create a basic authenticator
BasicAuthenticator basicAuth = new BasicAuthenticator("admin", "adminadmin");
// register the authenticator

Get a Workitem by $UniqueID

// get document by UniqueID
ItemCollection document = workflowCLient.getWorkitem("f3357f0b-20de-40ca-8aa1-4b9f43759c0b");

Get a Resultlist of workitems

Imixs-Melman provides a set of getter methods to receive a list of workitems.

Get tasklist by Creator

// get task list by creator with maximum 5 elements.
List<ItemCollection> documents=workflowCLient.getTaskListByCreator("admin");

Get tasklist by Owner

List<ItemCollection> documents=workflowCLient.getTaskListByOwner("admin",5,0, null);

How to restrict the Result Set

Per default all WorkItems are returned with all available items. To restrict the returned WorkItem data to only a subset of items the property 'items' need to be specified:

// get task list by creator with maximum 100 elements with subset of items
List<ItemCollection> documents=workflowCLient.getTaskListByCreator("admin");

Also the page size and page index can be limited:

List<ItemCollection> documents=workflowCLient.getTaskListByCreator("admin");

Create a Workitem

To create a workitem, an ItemCollection have to be created first:

ItemCollection workitem=new ItemCollection();
workitem.replaceItemValue("type", "workitem");
workitem.replaceItemValue(WorkflowKernel.MODELVERSION, "1.0.0");
// add some data..
workitem.replaceItemValue("_subject","This is some test data....");
// process workitem
String unqiueID=workitem.getUniqueID();

Get Workflow Events by a Workitem

To get all valid workflow events for an existing process instance:

// load worktiem
ItemCollection workitem = workflowCLient.getWorkitem(uniqueID.get(), null);
// load event list
List<ItemCollection> events = workflowCLient.getWorkflowEventsByWorkitem(workitem);

Error Handling

The Melman Rest Client throws a RestAPIException in case an API error occurred. The Imixs RestAPIException inherits form the Imixs WorkflowException and provides methods to evaluate the error context and error code. See the following example:

try {
	workitem = workflowCLient.processWorkitem(workitem);
} catch (RestAPIException e) {
	// evaluate exception
	Assert.assertEquals("MODEL_ERROR", e.getErrorCode());
	Assert.assertEquals("WorkflowClient", e.getErrorContext());"ErrorMessage=" + e.getMessage());
You can’t perform that action at this time.