# Technical Paper: Imixs Workflow Engine

## A Comprehensive Analysis of the Open-Source BPMN 2.0 Workflow Engine

**Version:** 1.0  
**Date:** June 2025  
**Author:** Technical Documentation

---

## Executive Summary

The Imixs Workflow Engine is a powerful open-source BPMN 2.0 workflow engine built on the Jakarta EE platform, specifically designed for human-centric business processes. With its micro-kernel architecture, advanced security concepts, and native Jakarta EE integration, it provides a robust solution for modern Business Process Management (BPM) requirements.

### Core Features

- **BPMN 2.0 Standard Compliance** with event-driven modeling concept
- **Micro-Kernel Architecture** with plugin and adapter system
- **Enterprise Security** with multi-level access control
- **Jakarta EE Native** for scalability and vendor independence

---

## 1. Introduction

### 1.1 Project Overview

Imixs-Workflow is an open-source BPMN 2.0 workflow engine with modern API and plugin architecture that combines low-code modeling, enterprise security, and microservice deployment for Java business applications. The project focuses on human-centric workflows and differs from task-oriented engines through its event-based approach.

### 1.2 Architectural Vision

The goal of the open-source project is to reduce the complexity of business applications by providing a flexible framework for implementing business logic based on the BPMN 2.0 standard. The engine enables model-driven implementation of business logic, making changes possible without code modifications.

---

## 2. BPMN 2.0 Modeling

### 2.1 BPMN 2.0 Standard Support

Imixs-Workflow supports the BPMN 2.0 standard and simplifies the path to Low-Code-centric Business Process Management. The Business Process Model and Notation (BPMN 2.0) is an open standard for describing business processes that can be visualized in diagram editors and executed by BPMN 2.0-compliant process engines.

### 2.2 Event-Driven Modeling Concept

The Imixs engine implements a unique event-driven modeling concept:

- **Tasks** represent different states of a business process
- **Events** control transitions between states
- **Gateways** enable complex business rules and decisions

Imixs-Workflow is a human-centric business process management solution that uses an event-driven modeling concept. Within the process flow, events can be triggered either by human actors or services at each task.

### 2.3 Imixs-BPMN Modeler

The project provides a specialized modeler with Imixs-BPMN:

- **Open-BPMN Foundation**: Imixs-BPMN is based on the Open Source project Open-BPMN and extends this framework with aspects of a human-centric workflow model executable on the Imixs-Workflow Engine
- **Multi-Platform Support**: Integration in Visual Studio Code, Eclipse, or Web Browser
- **Extended BPMN Elements**: Special event elements for workflow-specific functionalities

### 2.4 Deployment and Model Management

The Imixs-Workflow Rest API provides a convenient way to upload a BPMN model or verify the deployment status of BPMN models. Models can be deployed both via the REST API and programmatically:

```java
import org.imixs.workflow.bpmn.BPMNModel;
import org.imixs.workflow.bpmn.BPMNParser;

BPMNModel model = BPMNParser.parseModel(file.getData(), "UTF-8");
modelService.importBPMNModel(model);
```

---

## 3. Micro-Kernel Architecture

### 3.1 Architectural Foundations

The Imixs-Workflow Adapter API is part of the microkernel architecture pattern and provides an extension mechanism to adapt the processing lifecycle of a BPMN Event. This architecture follows the Hexagonal Architecture Pattern and enables clear separation between core logic and external components.

### 3.2 Plugin System

The plugin system forms the heart of the extensible architecture:

#### 3.2.1 Plugin API

The Imixs Plugin-API is the general extension concept of the Imixs-Workflow Engine. Plugins implement three callback methods:

```java
public void init(WorkflowContext workflowContext) throws PluginException;
public ItemCollection run(ItemCollection document, ItemCollection event) throws PluginException;
public void close(boolean rollbackTransaction) throws PluginException;
```

#### 3.2.2 Two-Phase Commit Concept

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

### 3.3 Adapter System

The adapter system complements the plugin system for more specific use cases:

#### 3.3.1 Signal Adapter

- **Event-Specific Binding**: In contrast to the Plugin API, the SignalAdapter is bound to a single Event within a BPMN 2.0 model. This allows fine-grained configuration
- **Early Execution**: Execution before the plugin processing lifecycle

#### 3.3.2 Generic Adapter

- **Model-Independent Execution**: General business logic independent from the BPMN model
- **CDI Integration**: The Imixs-Workflow Adapter API also supports CDI. In this way, an EJB or Resource can be injected into an adapter class by the corresponding CDI annotation

### 3.4 Hexagonal Architecture Implementation

With the two interface definitions 'Imixs-Plugin' and 'Imixs-Adapter', you can separate individual functionality from the core business logic managed by the Imixs-Workflow engine. This architecture provides:

- **Ports**: Interface definitions for extension points
- **Adapters**: Concrete implementations of the interfaces
- **Core Business Logic**: Protected in the inner hexagon

---

## 4. Security Concept

### 4.1 Multi-Level Security Model

Imixs-Workflow provides you with a powerful security model to protect your business data based on individual workflow models. The Imixs-Workflow engine supports you with a multi-level security model for fine-grained access control.

### 4.2 Access Control Lists (ACL)

The ACL system enables:

- **Status-Specific Authorization**: You can define an access control list (ACL) for every single process status within your workflow model. The ACL will automatically be applied by the Imixs-Workflow engine to a running process instance
- **Runtime Adaptation**: Security settings can be changed at runtime
- **Model-Driven Security**: No hard-coded security logic required

### 4.3 Jakarta EE Security Integration

The implementation is based on the Java Authentication and Authorization Service (JAAS), which is part of the Jakarta EE specification. Any authentication and authorization framework supported by your application server environment can be integrated.

#### 4.3.1 Container-Managed Security

- **Standardized Authentication**: Integration with Jakarta EE Security APIs
- **Vendor Independence**: Runs on all Jakarta EE-compatible servers
- **OIDC Support**: Modern Single Sign-On solutions

#### 4.3.2 Programmatic Security

- **API-Based Control**: Programmatic access control via Java APIs
- **Role-Based Authorization**: Integration with Jakarta EE role concepts
- **Custom Identity Stores**: Extensible authentication sources

### 4.4 Transparent Security Architecture

With this security concept of Imixs-Workflow, security is defined by a well-documented process model and no longer needs to be hard-coded. This provides:

- **Documented Security Policies**: Security as part of the BPMN model
- **Auditable Permissions**: Traceable access control
- **Business-User Friendly**: Security rules adjustable without programming

---

## 5. Jakarta EE Platform

### 5.1 Jakarta EE Foundation

Imixs-Workflow is a native Jakarta EE workflow engine providing transaction management, JPA persistence, and container-managed security out of the box. Built for modern cloud environments, it seamlessly integrates into your microservice architecture while maintaining full Jakarta EE compliance.

### 5.2 Enterprise-Grade Functionalities

#### 5.2.1 Transaction Management

- **Container-Managed Transactions**: Automatic transaction control
- **Two-Phase Commit**: Secure processing across plugin boundaries
- **Rollback Mechanisms**: Error handling with automatic rollback

#### 5.2.2 Persistence Layer

- **JPA Integration**: By using the Java Persistence API (JPA), the workflow engine is database independent and can be used with any relational SQL database
- **Vendor Independence**: Support for all JDBC-compatible databases
- **Clustering Support**: Multi-node deployments possible

#### 5.2.3 Application Server Support

Supported platforms:

- **WildFly**: With the latest version of Imixs-Workflow (6.2.0), we upgraded to GraalVM 24.1.2 and Wildfly 29.0.1-Final-JDK-17
- **Payara**: Full compatibility
- **Open Liberty**: Eclipse MicroProfile support
- **Apache TomEE**: Lightweight Jakarta EE implementation

### 5.3 Microservice Architecture

Imixs-Workflow provides a RESTful API to integrate the Imixs-Workflow engine into a microservice architecture. In such an architecture, the Imixs-Workflow engine can be deployed as a separate microservice managing human-centric workflow tasks.

#### 5.3.1 REST API

- **JAX-RS Implementation**: Standardized REST services
- **JSON/XML Support**: Flexible data formats
- **OpenAPI Documentation**: Automatically generated API documentation

#### 5.3.2 Container-Native Deployment

- **Docker Support**: The Imixs Process Manager allows you to start within seconds. It comes with a Docker image that can be deployed locally or in a containerized environment like Docker Swarm or Kubernetes
- **Kubernetes Integration**: Native cloud deployment options
- **Horizontal Scaling**: Automatic load distribution

### 5.4 Integration Capabilities

Jakarta EE is designed to support the integration of various enterprise components and systems using a robust architecture that facilitates seamless communication and collaboration. Technologies like the Java API for RESTful Web Services (JAX-RS), Java Message Service (JMS), or Jakarta Security 3.0 provide essential building blocks for developing scalable and interoperable enterprise applications.

---

## 6. Technical Architecture

### 6.1 Core Components

#### 6.1.1 Workflow Kernel

- **Event Processing**: Central event processing
- **State Management**: State management for process instances
- **Plugin Orchestration**: Coordination of plugin execution

#### 6.1.2 Model Service

- **BPMN Parser**: XML-based model processing
- **Model Validation**: Consistency checking of process models
- **Version Management**: Multiple model versions in parallel

#### 6.1.3 Document Service

- **Process Instances**: Management of workflow instances
- **Data Storage**: Flexible data structures
- **History Tracking**: Complete audit trails

### 6.2 Performance and Scaling

With its micro-container architecture, Jakarta EE offers features for building scalable and high-performance enterprise applications, a critical aspect for BPM systems that often need to manage a substantial volume of concurrent processes and user interactions.

#### 6.2.1 Clustering

- **Session Replication**: State synchronization between nodes
- **Load Balancing**: Automatic load distribution
- **Failover**: High availability scenarios

#### 6.2.2 Caching

- **Second-Level Cache**: JPA-based caching strategies
- **Process Instance Cache**: Optimized access to active processes
- **Model Cache**: Fast access to BPMN definitions

### 6.3 Monitoring and Management

- **JMX Integration**: Management Bean support
- **Health Checks**: Jakarta EE Health Check API
- **Metrics**: MicroProfile Metrics integration
- **Logging**: Structured log output

---

## 7. Advanced Functionalities

### 7.1 Machine Learning Integration

With its latest version, the Open Source Workflow Engine Imixs-Workflow fully integrates the AI Framework SpaCy v3.1. The integration is based on the Imixs Micro Kernel architecture, which allows modern model-based development.

#### 7.1.1 Imixs-ML Adapter

- **NLP Integration**: Natural Language Processing functionalities
- **Entity Recognition**: Automatic extraction of business data
- **Training Model Integration**: Self-learning systems

### 7.2 Stream Analytics

Based on the Imixs micro-kernel architecture, a business process can be extended with various adapter or plugin modules providing additional functionality. The Imixs-ML Adapter, for example, provides a generic API to integrate various ML frameworks like spaCy or Apache mxnet.

### 7.3 Event Streaming

In an event-based workflow engine like Imixs-Workflow, the different states of a business process are described as Tasks. The transition from one state to the next is described by Event elements. Events can be triggered by consuming a Kafka streaming event, as well as by external services or human actors.

---

## 8. Deployment Options

### 8.1 Traditional Deployment

#### 8.1.1 Application Server Deployment

- **WAR/EAR Deployment**: Classic enterprise deployment methods
- **Shared Libraries**: Optimized resource utilization
- **Hot Deployment**: Development-friendly updates

### 8.2 Cloud-Native Deployment

#### 8.2.1 Docker Containerization

```yaml
version: "3.1"
services:
  app:
    image: imixs/imixs-microservice
    environment:
      POSTGRES_CONNECTION: "jdbc:postgresql://db/workflow"
    ports:
      - "8080:8080"
```

#### 8.2.2 Kubernetes Orchestration

Imixs-Office-Workflow offers a container-based architecture that fits perfectly into any kind of Kubernetes clusters:

- **Helm Charts**: Standardized Kubernetes deployments
- **ConfigMaps**: Externalized configuration
- **Persistent Volumes**: Database and index persistence

### 8.3 Microservice Architecture

Imixs Micro is a lightweight distributed workflow management system based on the Imixs-Workflow technology. This system can be used, for example, as a workflow service in an industrial production plant.

---

## 9. Development Best Practices

### 9.1 Model-Driven Development

Imixs-Workflow is a BPMN workflow engine. BPMN gives you the perfect place to describe your business process including the workflow, responsibilities, and business rules. Even if you are an experienced Java developer, try to describe your business process in the BPMN model first.

### 9.2 Plugin Development Guidelines

```java
public class MyPlugin extends AbstractPlugin {
    @Override
    public ItemCollection run(ItemCollection workitem, ItemCollection event)
            throws PluginException {
        // Validate and aggregate
        double budget = workitem.getItemValueDouble("budget");
        if (budget <= 0) {
            throw new PluginException(MyPlugin.class.getName(),
                "INPUT ERROR", "Please enter the Budget.");
        } else {
            workitem.setItemValue("budget", Math.round(budget));
        }
        return workitem;
    }
}
```

### 9.3 Signal Adapter Pattern

Try to use SignalAdapters instead. The Imixs-Workflow Engine provides a Cross-Function-API based on CDI Events:

```java
public class DemoAdapter implements org.imixs.workflow.SignalAdapter {
    @Inject
    ModelService modelService;

    @Override
    public ItemCollection execute(ItemCollection document, ItemCollection event)
            throws AdapterException {
        // Business logic implementation
        return document;
    }
}
```

---

## 10. Comparative Analysis

### 10.1 Imixs vs. Camunda

While Camunda remains a strong choice for developer-led process automation, Imixs-Workflow offers a distinct alternative for organizations seeking to empower their business users.

#### 10.1.1 Architectural Differences

- **Imixs**: Jakarta EE-based, human-centric
- **Camunda**: Spring-based, developer-oriented

#### 10.1.2 Target Audiences

- **Imixs**: Business users and business departments
- **Camunda**: Developer teams and IT departments

### 10.2 Technology Positioning

Jakarta EE, formerly known as Java EE, represents the industry standard for enterprise computing and brings significant benefits to Imixs-Workflow's architecture. At its core, Jakarta EE's container-managed approach ensures optimal resource handling and transaction management with minimal configuration overhead.

---

## 11. Conclusion and Outlook

### 11.1 Summary of Core Strengths

The Imixs Workflow Engine is distinguished by the following core competencies:

1. **BPMN 2.0 Compliance** with extended human-centric functionalities
2. **Micro-Kernel Architecture** for maximum extensibility and flexibility
3. **Enterprise Security** with model-driven security policies
4. **Jakarta EE Native** for scalability and vendor independence

### 11.2 Application Scenarios

The engine is particularly suitable for:

- **Human-Centric Business Processes** with complex approval workflows
- **Regulatory Compliance** processes with audit requirements
- **Document Management** systems with workflow integration
- **Case Management** applications

### 11.3 Technology Roadmap

Future development focuses on:

- **Cloud-Native Features**: Extended Kubernetes integration
- **AI/ML Integration**: Enhanced Machine Learning capabilities
- **Low-Code/No-Code**: Simplified business user interfaces
- **Event Streaming**: Extended integration with event-driven architectures

### 11.4 Community and Ecosystem

Imixs Workflow is an open source project and we sincerely invite you to participate in it. There are different ways how you can do that. Join the Imixs Workflow Project now on GitHub. The active community ecosystem provides continuous development and support.

---

## Bibliography

1. Imixs-Workflow Official Documentation. (2025). https://www.imixs.org/
2. Imixs-BPMN Modeler Documentation. (2025). https://www.imixs.org/sub_modeler.html
3. Jakarta EE Security Specification. (2025). https://jakarta.ee/
4. Business Process Model and Notation (BPMN) 2.0. Object Management Group.
5. Imixs-Workflow GitHub Repository. (2025). https://github.com/imixs/imixs-workflow

---

**Appendix A: API References**  
**Appendix B: Configuration Examples**  
**Appendix C: Performance Benchmarks**  
**Appendix D: Migration Guidelines**