Workflow Engine

A hexagonal architecture-based workflow engine for managing dynamic business processes with multi-tenant support.

• Java 21 with Spring Boot 3.5.9
• Flowable 7.0.1 – Process engine & workflow orchestration
• PostgreSQL / H2 – Data persistence
• Lombok – Code generation & reduction
• MapStruct – DTO mapping
• SpringDoc OpenAPI – API documentation & Swagger UI

Declarative workflow engine supporting:

• Dynamic workflow definition creation and deployment
• Tenant-isolated workflow instances
• State-driven step transitions
• Built-in request traceability
• BPMN deployment & versioning

• Dynamic Workflow Designer – Create workflows with custom steps and transitions without code
• Multi-Tenancy – Complete tenant isolation via X-Tenant-ID header (defaults to tenant)
• Request Tracing – Trace requests across systems using X-Request-Id and X-Correlation-Id headers (auto-generated)
• BPMN Support – Export/download generated BPMN definitions; manage multiple versions per process key
• Frozen Data Indicators – Track immutable data fields at each workflow step
• State Management – Query workflow state, available transitions, and enforce valid step progression

Example API Calls:

# Get all versions of a workflow
GET /api/v1/workflows/config/{workflowId}/versions

# Get BPMN for specific version
GET /api/v1/workflows/config/{workflowId}/versions/2/bpmn

Example API Calls:

# List all active workflow instances
GET /api/v1/workflows?status=ACTIVE&sort=startTime,desc

# Get available transitions for an instance
GET /api/v1/workflows/{instanceId}/transitions

All endpoints support optional headers for traceability and multi-tenancy:

• X-Tenant-ID – Tenant identifier (defaults to tenant)
• X-Request-Id – Unique request ID for tracing (auto-generated)
• X-Correlation-Id – Business correlation ID (auto-generated)

Multi-Tenancy: Workflows are tenant-isolated. Same process key can exist in multiple tenants.

Request Tracing: Headers are echoed back in responses for traceability. Use X-Correlation-Id for business transaction tracking across systems.

POST /api/v1/workflows/config
Content-Type: application/json
X-Tenant-ID: tenant

{
  "name": "Task Management Workflow",
  "description": "Generic workflow for task management",
  "steps": [
    {
      "stepCode": "CREATE",
      "stepName": "Create Task",
      "sequenceOrder": 1,
      "isStartStep": true,
      "frozenDataIndicators": []
    },
    {
      "stepCode": "REVIEW",
      "stepName": "Review Task",
      "sequenceOrder": 2,
      "frozenDataIndicators": ["taskData"]
    },
    {
      "stepCode": "APPROVE",
      "stepName": "Approve Task",
      "sequenceOrder": 3,
      "frozenDataIndicators": ["taskData", "reviewNotes"]
    },
    {
      "stepCode": "COMPLETE",
      "stepName": "Complete Task",
      "sequenceOrder": 4,
      "isEndStep": true,
      "frozenDataIndicators": ["taskData", "reviewNotes", "approvalData"]
    }
  ],
  "transitions": [
    {
      "transitionCode": "CREATE_TO_REVIEW",
      "fromStep": "CREATE",
      "toStep": "REVIEW"
    },
    {
      "transitionCode": "REVIEW_TO_APPROVE",
      "fromStep": "REVIEW",
      "toStep": "APPROVE"
    },
    {
      "transitionCode": "APPROVE_TO_COMPLETE",
      "fromStep": "APPROVE",
      "toStep": "COMPLETE"
    }
  ]
}

POST /api/v1/workflows/config/{id}/start
Content-Type: application/json

{
  "businessKey": "TASK-2024-001",
  "variables": {
    "title": "Implement new feature",
    "priority": "HIGH",
    "assignee": "john.doe"
  }
}

• API Docs – Available at /api-docs (JSON) and /swagger-ui.html (interactive)
• Flowable Docs – Flowable User Guide
• Spring Boot Docs – Spring Boot Documentation
• BPMN Standard – OMG BPMN Specification

Implements Hexagonal Architecture with clear separation:

• Domain Layer – Core business logic and ports
• Application Layer – Use cases orchestrating domain
• Infrastructure Layer – Adapters (REST, Flowable, Persistence)