03 // Engine Gateway

BPMN Engine Support

Orchescala is designed to be engine-agnostic. The Gateway abstracts away the differences between BPMN engines and provides a unified REST API regardless of which engine runs your processes.

Supported Engines

Currently, Orchescala supports three BPMN engines:

EngineModuleClientDescriptionState
Camunda 7orchescala-engine-c7C7ClientThe classic Camunda Platform via REST APIProduction
Camunda 8orchescala-engine-c8C8ClientZeebe Engine via REST APIProof of Concept
Operatonorchescala-engine-opOpClientOperaton – the open-source Camunda 7 forkProof of Concept

Camunda 7

Camunda 7 is the classic, well-established BPMN engine with a REST API. Orchescala communicates via the community REST client library.

Authentication Options:

  • C7LocalClient – No authentication (local development)
  • C7BasicAuthClient – Username/password authentication
  • C7OAuth2Client – OAuth2 client credentials flow
// Local development
object MyC7Client extends C7LocalClient:
  val camundaRestUrl = "http://localhost:8080/engine-rest"

// Basic Auth
object MyC7Client extends C7BasicAuthClient:
  val camundaRestUrl = "http://localhost:8080/engine-rest"
  val username = "demo"
  val password = "demo"

Camunda 8

Camunda 8 (Zeebe) uses gRPC for command execution and REST for queries. Orchescala uses the official Camunda Java Client.

Authentication Options:

  • C8SaasClient – For Camunda 8 SaaS (OAuth2)
  • C8BearerTokenClient – For self-managed with Bearer token authentication
  • Direct client – For local development without authentication
// SaaS
object MyC8Client extends C8SaasClient:
  val zeebeGrpc = "https://xxx.zeebe.camunda.io:443"
  val zeebeRest = "https://xxx.operate.camunda.io:443"
  val audience = "zeebe.camunda.io"
  val clientId = "your-client-id"
  val clientSecret = "your-secret"
  val oAuthAPI = "https://login.cloud.camunda.io/oauth/token"

// Self-managed with Bearer token
object MyC8Client extends C8BearerTokenClient:
  val zeebeGrpc = "http://localhost:26500"
  val zeebeRest = "http://localhost:8080"

Messages - correlation:

POST /message/{messageName} takes the processInstanceId or the businessKey - the same for all engines: the processInstanceId wins, a businessKey is then ignored. Without both only a message start event can be triggered.

Camunda 8 correlates by the correlation key of the message. So the BPMN decides which of the two it takes:

<bpmn:message id="Message_Reset" name="my-process-reset">
  <bpmn:extensionElements>
    <!-- sent with processInstanceId -->
    <zeebe:subscription correlationKey="=string(camunda.processInstance.key)" />
    <!-- or sent with businessKey -->
    <!-- <zeebe:subscription correlationKey="=camunda.processInstance.businessId" /> -->
  </bpmn:extensionElements>
</bpmn:message>
  • camunda.processInstance.key is the own process instance - from Camunda 8.10, in every process.
  • camunda.processInstance.businessId is the businessKey - from Camunda 8.10. The Gateway starts the process (by its id or by message) with it as the instance's business id, not as a variable: shown and searchable in Operate, passed on to call activities (no input mapping needed; zeebe:calledElement businessId="=…" overrides it), and the workers get it with their job. At most 256 characters; a cluster that enforces unique business ids answers a second start with the same businessKey with 409 while the first instance runs.
  • Any variable works too: send its value as businessKey.

Start by message with a businessKey: the businessKey is the message's correlation key and business id. A running instance waiting for this message with it gets it (e.g. the event subprocess of the pattern «Einmalige Ausführung») - no process is started, the Gateway answers 409. Otherwise a new instance starts, also when another instance with the same businessKey runs.

Limit: if the start with key is refused (an instance started with it runs and waits for no such message), the message is sent again without correlation key, with the business id. Its instance may then be created on another partition, and is taken as started there. A message without key lands in a running instance only through an event with an empty correlation key ("") - with =camunda.processInstance.businessId that does not happen, with an empty correlation key it would give no 409.

Operaton

Operaton is the open-source fork of Camunda 7, maintained by the community. Since Operaton keeps the Camunda 7 REST API, Orchescala reuses the same client library internally.

Authentication Options:

  • OpLocalClient – No authentication (local development)
  • OpBasicAuthClient – Username/password authentication
  • OpOAuth2Client – OAuth2 client credentials flow
// Local development
object MyOpClient extends OpLocalClient:
  val operatonRestUrl = "http://localhost:8080/engine-rest"

Unified Architecture

All three engines implement the same ProcessEngine trait, which defines a common interface for process operations:

ProcessEngine (trait)
├── processInstanceService     – Start processes, query variables
├── historicProcessInstanceService – Query process history
├── historicVariableService    – Query historic variables
├── incidentService            – Manage incidents
├── jobService                 – Query and manage jobs
├── messageService             – Correlate messages
├── signalService              – Broadcast signals
└── userTaskService            – Query and complete user tasks

Each engine provides its own implementation:

  • C7ProcessEngine → uses the Camunda 7 REST API
  • C8ProcessEngine → uses the Camunda 8 Java Client (gRPC + REST)
  • OpProcessEngine → uses the Operaton REST API

Gateway: Automatic Engine Routing

The Engine Gateway (GProcessEngine) sits on top of the engine-specific implementations. It enables you to run multiple engines simultaneously and routes each request to the correct engine automatically.

How Routing Works

  1. Try all configured engines – The Gateway tries each engine in sequence until one succeeds.
  2. Cache the result – Once a process instance is found on a specific engine, the mapping is cached (15 minutes, max 100 entries) so subsequent requests go directly to the right engine.
  3. Heuristic optimization – For known process instance IDs, the Gateway can often determine the engine type without querying:
    • UUID format (e.g., f150c3f1-13f5-11ec-936e-0242ac1d0007) → likely Camunda 8
    • Numeric format (e.g., 12345) → likely Camunda 7 / Operaton

Configuration Example

import orchescala.gateway.*
import orchescala.engine.*
import orchescala.engine.c7.C7Client
import orchescala.engine.c8.C8Client

object MyGatewayApp extends GatewayServer:

  def config: GatewayConfig = DefaultGatewayConfig(
    engineConfig = DefaultEngineConfig(),
    workerConfig = DefaultWorkerConfig(DefaultEngineConfig()),
    gatewayPort = 8888
  )

  // Configure which engines are available
  override def c7Clients: Seq[C7Client] = Seq(myC7Client)

  override def c8Clients: Seq[C8Client] = Seq(myC8Client)

With this setup, the Gateway provides a single REST API that transparently handles processes on Camunda 7/ Operaton and Camunda 8.

Worker Support per Engine

Workers also have engine-specific implementations, following the same pattern:

EngineWorker ModuleDescriptionState
Camunda 7orchescala-worker-c7External Task workers via Camunda 7 WorkerProduction
Camunda 8orchescala-worker-c8Job workers via Camunda 8 WorkerProof of Concept
Operatonorchescala-worker-opExternal Task workers via Operaton WorkerProof of Concept

All workers share the same base Worker abstraction from orchescala-worker, so your business logic remains engine-independent.

Worker Forwarding

The Gateway supports forwarding worker requests to remote Worker applications via HTTP. This allows you to deploy workers as independent microservices.

The EngineConfig.workerAppUrl function determines where a worker request should be sent, based on the topic name. If it returns None, the worker is executed locally.

// Default: forward to microservice based on topic name
workerAppUrl = topicName =>
  Some(s"http://${topicName.split('-').take(2).mkString("-")}:5555")

// Local development: all workers run locally
workerAppUrl = _ => Some("http://localhost:5555")

Adding a New Engine

The modular architecture makes it straightforward to add support for additional BPMN engines. The key steps are:

  1. Implement ProcessEngine – Provide implementations for all service traits (ProcessInstanceService, UserTaskService, etc.)
  2. Create a Client – Define a client trait for connection management
  3. Register in the Gateway – Add the new engine to the GProcessEngine configuration
  4. Implement Workers (optional) – Provide engine-specific worker implementations

The shared orchescala-engine module defines all interfaces, ensuring that any new engine integrates seamlessly with the existing Gateway, API documentation, and simulation infrastructure.