Hexagonal Architecture in Imixs-Workflow

The hexagonal architecture is a design pattern introduced by Dr. Alistair Cockburn.
A hexagon is a closed body and according to his pattern, an application is assumed to be a hexagon. Whatever is relevant to the business logic of an application gets to reside inside the hexagon and the rest is arranged outside. In this way, the business logic can be easily tested without worrying too much about external factors. So and this matches perfectly into the world of microservices.

Well, the outside part of the hexagon can interact with the inside world, and vice-versa, via the concept of ‘ports & adapters.’ In a Java application you typically have this ports defined by your interfaces. The Implementation of those ports (interfaces) are than called the adapter. That’s the concept in short.

How Is the Hexagonal Architecture Achieved in Imixs-Workflow?

With in the Imixs-Workflow engine we have two interface definitions defining the ports in a Hexagonal Architecture View:

  • The Plugin API
  • The Adapter API

The Plugin

The Imixs Plugin-API is the general extension concept of the Imixs-Workflow Engine.
Each workflow model can import a different set of plugins to provide different functionality. A plugin provides business logic to control the processing life-cycle of a process instance, as also platform specific technical functionality, to exchange data with its surrounding environment.

For example a plugin can apply a business rule, send an E-Mail notification, or import business data from an external microservice. The Imixs-Workflow project already provides a set of plug-ins which covers a lot of standard functionality of a workflow engine. See the section Plugin-API for further information.

The Imixs Plugin-API defines three call-back methods, called by the Workflow Engine in one single transaction during the processing life-cycle. This is the concept of a two-phase commit (2PC).

public void init(WorkflowContext workflowContext) 
                  throws PluginException;

public ItemCollection run(ItemCollection document,ItemCollection event) 
                  throws PluginException;

public void close(boolean rollbackTransaction) 
                  throws PluginException;

Plugins are a powerful way to extend the behavior of a business workflow and can be easily added into a workflow model.

The Adapter

As an alternative to a the Plugin-API, in Imixs-Workflow business logic can also be implemented in an Adapter class. An adapter is bound to a single event and can be used for a more fine grained process control. Similar to the Plugin, an Adapter can exchange data with an external Microservice API. In different to the Plugin API the Adapter API is bound to a single Event within a BPMN 2.0 model. This allows a more fine grained configuration.

The Interface definition of an Adapter is quite simple:

public ItemCollection execute(ItemCollection document,ItemCollection event) 
                       throws AdapterException;

As in the Plugin API an adapter receives a full copy of the business data collected by the workflow engine and also information about the current event. This allows an adapter to easily fit into the current business process.

Read more about the Imixs Adapter API here.


To sum it up, the hexagonal architecture is an efficient methodology in the form of ports (interfaces) and adapters, which easily and effectively keep the core logic separated from the outside of the application.

The hexagonal architecture is part of the core concepts in Imixs-Workflow. With the two interface definitions ‘Imixs-Plugin’ and ‘Imxis-Adapter’ you can separate individual functionality from the core business logic managed by the Imixs-Workflow engine. In the world of Microservices this pattern provides a way to connect services and solve the problem of inter process communication (ICP) in a clear architectural style.

Leave a Reply

Your email address will not be published. Required fields are marked *