Camunda، BPMN و موتور فرایندCamunda, BPMN & Workflow Engines

Backend job posts list it next to Spring Boot and Kafka in one short line: "familiarity with Camunda / BPMN is a plus". Most candidates skim past it, assuming it is a drawing tool for managers. That line is exactly where a senior interviewer finds out whether you know the difference between "a short request" and "a business process that lives for three weeks".

This chapter starts from zero: why a workflow engine exists at all, then BPMN 2.0 symbol by symbol, then the inside of the engine, then real Java code, and finally the question a senior interview is really about: when do you orchestrate, and when do you choreograph?

1. Why does a workflow engine exist at all?

1.1 What is a long-running process?

Most code you write is request-scoped: a request arrives, a few functions run, one transaction commits, and everything vanishes from memory. The state of the work is the stack.

"Issue an insurance policy" is not like that. Between step three and four a human has to approve — maybe tomorrow morning. If nobody approves within three days it must escalate. The call to the credit bureau may fail ten times and must be retried with backoff. If the customer withdraws, the work already done must be compensated. And six months later an auditor asks "who approved this, and when?".

That is a long-running, stateful business process: it outlives a request, it has state, it waits, and it must leave an audit trail.

Diagram: the lifetime of a request versus the lifetime of a process instance — عمر یک request در برابر عمر یک process instance.

flowchart LR
  subgraph R["Request-scoped service"]
    A1["HTTP in"] --> A2["validate"] --> A3["DB tx commit"] --> A4["HTTP out"]
  end
  subgraph P["Long-running process"]
    B1["Start: application received"] --> B2["Automated credit check"]
    B2 --> B3["Human approval - hours or days"]
    B3 --> B4["Timer: 3 days -> escalate"]
    B4 --> B5["Issue policy"]
    B5 --> B6["End + audit trail"]
  end

1.2 Why does hand-rolling it go wrong?

The path is always the same: a status column (NEW, APPROVED, …), a @Scheduled job picking up NEW rows every minute, then retry_count, next_retry_at, error_message, then escalated_at and a *_history table, then an admin page to see what is stuck. And on day five someone asks "if we change that condition, what happens to the instances mid-flight right now?" — and nobody has an answer.

1.3 What does an engine actually give you?

A workflow engine (Camunda, Flowable, Zeebe, Temporal…) ships with: an explicit executable model (one file that is both diagram and code), state persistence, wait states (standing still without holding a thread), timers, retries with backoff plus permanent failures turned into visible incidents, human tasks with queues and claiming, history and audit, and versioning and migration of running instances.

2. BPMN 2.0 symbol by symbol

BPMN stands for Business Process Model and Notation; version 2.0 is an OMG standard defining a graphical notation and an executable XML format at once. That is the key point: the .bpmn file your modeler produces is what the engine runs — the diagram is not documentation, it is the program. Read it like a metro map: stations (tasks), lines (sequence flows), junctions (gateways) and mid-journey events, with an imaginary train called a token moving along.

2.1 Pools and lanes

A pool is an independent participant: your organisation, the partner bank, the customer. Pools talk through message flows (dashed arrows), never sequence flows. A lane subdivides one pool: "clerk", "manager", "system".

The engine executes exactly one pool — yours; draw the counterparty as a black box. Lanes have no execution semantics but usually map to task assignment or candidate groups.

2.2 Events — start, end, and mid-flight

The circle's border gives the position: thin = start, double = intermediate (mid-path; it waits, i.e. catch, or fires, i.e. throw), thick = end of this branch. The icon inside gives the type:

2.3 Tasks — where the work happens

Do not fall in love with script tasks in production: you lose versioning, tests and code review, runtime errors land inside the engine, and in Camunda 7 running Groovy/JS opens a real attack surface — whoever can deploy a model can execute code. The rule: logic in code, decisions in DMN, the model is flow only.

2.4 Gateways — decisions and branching

A gateway is a diamond and it does no work; it only routes tokens.

Exclusive (XOR), marked ✕: exactly one path; the first condition that evaluates to true wins. Always add a default flow, otherwise the engine throws when nothing matches.

Diagram: an exclusive decision on order amount — تصمیم انحصاری بر اساس مبلغ سفارش.

flowchart LR
  S(("Start")) --> T1["Check order"]
  T1 --> G{"amount > 10000?"}
  G -- "yes" --> A["Manual approval"]
  G -- "no (default)" --> B["Auto approve"]
  A --> E(("End"))
  B --> E

Parallel (AND), marked +: all branches activate (fork) and the closing gateway waits for all of them (join). "Parallel" means several active tokens, not necessarily several threads.

Inclusive (OR), marked ○: every branch whose condition is true. Its join has to work out how many tokens are still coming, which makes it the most expensive gateway.

Event-based gateway: the path is chosen by whichever event arrives first — the standard "race between a message and a timeout" pattern.

Diagram: a race between the payment message and a timeout — مسابقهٔ بین پیام پرداخت و timeout.

flowchart LR
  T["Await payment"] --> EG{"Event-based gateway"}
  EG --> M["Message: payment received"]
  EG --> TI["Timer: PT30M"]
  M --> OK["Ship order"]
  TI --> CX["Cancel order"]

A mnemonic: XOR = "one of", AND = "all of", OR = "whichever qualifies", event-based = "whichever arrives first". In practice 90% of healthy models use only XOR and AND; a model full of inclusive gateways usually means unfinished analysis.

2.5 Sequence flows and conditions

Solid arrows are sequence flows and they define where tokens travel. Every outgoing flow of a gateway can carry a condition: in Camunda 7 written in JUEL (${amount > 10000}), in Camunda 8 in FEEL (=amount > 10000; the leading = means "this is an expression"). One flow may be the default: it carries no condition and is taken only when nothing else matched.

2.6 Boundary events — reacting to something mid-activity

A boundary event sits on the edge of a task or subprocess and reacts to something that happens while it runs. Interrupting (solid border) cancels the activity; non-interrupting (dashed border) leaves the activity untouched and spawns a new parallel token.

Real examples: an interrupting timer on "call the customer" (48 hours passed, close the case); a non-interrupting timer on "manager review" (remind every 24 hours, keep the task open); an error boundary on a service task (CREDIT_DENIED → rejection path); a message boundary ("cancel" arrived → tear everything down); a non-interrupting escalation on a subprocess (notify the manager, keep working); a compensation boundary registering the undo handler.

Diagram: a non-interrupting reminder next to an interrupting deadline — تایمر یادآوری غیرقطع‌کننده در کنار تایمر قطع‌کننده.

flowchart LR
  U["User task: manager review"] --> D["Decision recorded"]
  U -. "non-interrupting timer PT24H" .-> R["Send reminder"]
  R -. "loop back" .-> U
  U == "interrupting timer P3D" ==> ESC["Escalate to director"]

2.7 Subprocesses and call activities

• Embedded subprocess: groups elements into one rectangle. The value is not tidiness; it is that you can attach one boundary event to the whole group ("if the customer cancels during any of these five steps, cancel all of them") and scope variables.
• Event subprocess: dashed border, no incoming sequence flow; triggered by a message/timer/error/escalation start event. For "whenever this happens, do that" without cluttering the main path.
• Call activity: invokes another process by processId and waits for it — the main reuse mechanism. (Transaction subprocesses are not supported for execution in Camunda 8; build the same behaviour with a normal subprocess plus compensation.)

The choice is simple: if the fragment only makes sense inside this process → embedded; if it stands on its own or is owned by another team → call activity, at the cost of a separate process instance with a separate history.

2.8 Multi-instance — one activity, many times

Three vertical bars (parallel) or horizontal bars (sequential) under a task mean the activity runs once per element of a collection: "all three board members vote at once", or "three approval levels in order". A completion condition finishes early ("two approvals are enough"). In Camunda 8 it is configured with FEEL: inputCollection = =approvers, inputElement = approver, results in outputCollection.

3. The execution model — what is inside the box?

A process definition is the deployed BPMN file (like a class); a process instance is one execution of it (like an object). Every definition has a stable key (e.g. order-fulfillment) and a version incremented on each deployment. Old instances stay on their own version — a feature, not a bug, which is why after a year nine versions may be alive at once.

A token is the imaginary marker saying "the process is here", and it explains everything: a start event creates one; a parallel gateway turns one into N and the join turns N back into one; an end event consumes one, and when the last one is gone the instance is finished; a terminate end event destroys all tokens in its scope. In Camunda 7 each token is a row in ACT_RU_EXECUTION; in Camunda 8 state lives in the engine's internal store, but the model is identical.

Each instance carries a name -> value map of variables, and variables have scope: a variable created inside a subprocess disappears when that subprocess ends, unless you explicitly write it to the parent scope.

A job is "work the engine must do later, asynchronously": a timer that must fire, an async service task, a message to throw. The job executor is a thread pool that picks it up: (1) acquisition — due jobs are queried; (2) locking — locked by writing LOCK_OWNER_ and LOCK_EXP_TIME_ under optimistic locking, so two cluster nodes never grab the same job; (3) execution — handed to worker threads; (4) failure — on exception retries is decremented and the job re-queued; (5) incident — at zero retries an incident is created and the job stops until a human intervenes.

Diagram: the lifecycle of a job from creation to incident — چرخهٔ عمر یک job از ساخت تا incident.

stateDiagram-v2
  [*] --> Created
  Created --> Acquired: due date reached
  Acquired --> Executing: locked by worker
  Executing --> Done: success
  Executing --> Failed: exception
  Failed --> Created: retries > 0
  Failed --> Incident: retries = 0
  Incident --> Created: retries reset by operator
  Done --> [*]

Alongside the runtime tables there are history tables: which activity started and finished when, what a variable became, who claimed a task. Camunda 7 offers four levels — none, activity, audit (default) and full — and full also records every variable update, the fastest way to blow up your database.

4. Camunda 7 versus Camunda 8/Zeebe — honestly

Read this carefully: in an interview it shows whether someone has worked with it or only heard the name.

Camunda 7 is an embedded engine: a Java library that runs inside your own Spring Boot application and keeps its state in a relational database — sharing the same DataSource and the same transaction as your code.

Camunda 8 differs: the Zeebe engine is a distributed broker working on replicated partitions like Kafka, keeping state in a log plus a local RocksDB, and needing no relational database to execute. An exporter pushes reporting data into a secondary storage (Elasticsearch, OpenSearch, or from 8.8 an RDBMS) that Operate and Tasklist read. Your application is a client speaking gRPC/REST.

Diagram: the two architectures side by side — دو معماری کنار هم.

flowchart TB
  subgraph C7["Camunda 7 - embedded"]
    APP["Spring Boot app<br/>engine as a library"] --> DB[("Relational DB<br/>ACT_RU_* / ACT_HI_*")]
    APP --- COCK["Cockpit / Tasklist webapps"]
  end
  subgraph C8["Camunda 8 - orchestration cluster"]
    W["Your Spring Boot app<br/>job workers - client only"] -- "gRPC / REST" --> Z["Zeebe brokers<br/>partitions + replicas"]
    Z -- "exporter" --> SS[("Secondary storage<br/>ES / OpenSearch / RDBMS")]
    SS --> OP["Operate / Tasklist"]
  end

Three things really change for a Java developer, and all three hurt. The shared transaction disappears: a Camunda 7 JavaDelegate could write your database and a process variable and commit both together; now you write idempotency and reach for patterns like the outbox (see ms-data). Direct queries against engine tables end, so every report becomes an API call. And the error model changes, from an exception in the same transaction to explicitly failing a job with retries and backoff.

5. Java integration — Camunda 7

5.1 Embedding in Spring Boot

<dependency>
  <groupId>org.camunda.bpm.springboot</groupId>
  <artifactId>camunda-bpm-spring-boot-starter</artifactId>
  <version>7.24.0</version>
</dependency>
<!-- add ...-starter-webapp for Cockpit/Tasklist, ...-starter-rest for the REST API -->

Every .bpmn or .dmn file under src/main/resources is auto-deployed at startup.

camunda:
  bpm:
    database:
      schema-update: false         # false in production; run the official scripts via Flyway
    history-level: audit
    job-execution:
      enabled: true
      core-pool-size: 5
      max-pool-size: 20
      queue-capacity: 10
      lock-time-in-millis: 300000
      max-jobs-per-acquisition: 3

schema-update: true is development-only: in a rolling deployment two app versions would change the schema at once. In production run the official per-version SQL scripts through your migration tool — the discipline of spring-data-tx and cicd-pipelines.

5.2 Service tasks: three ways to attach code

Option one — JavaDelegate (classic, inside the same JVM):

import org.camunda.bpm.engine.delegate.DelegateExecution;
import org.camunda.bpm.engine.delegate.JavaDelegate;
import org.camunda.bpm.engine.delegate.BpmnError;

@Component("checkCreditDelegate")   // the bean name is what the EL expression resolves
public class CheckCreditDelegate implements JavaDelegate {

  private final CreditClient creditClient;

  public CheckCreditDelegate(CreditClient creditClient) { this.creditClient = creditClient; }

  @Override
  public void execute(DelegateExecution execution) {
    String customerId = (String) execution.getVariable("customerId");
    CreditResult result = creditClient.score(customerId);

    if (result.score() < 500) {
      // business error: caught by an error boundary event
      throw new BpmnError("CREDIT_DENIED", "score=" + result.score());
    }
    execution.setVariable("creditScore", result.score());
  }
}

The task references it as camunda:delegateExpression="${checkCreditDelegate}", usually together with camunda:asyncBefore="true" and camunda:retryTimeCycle="R5/PT30S".

Option two — an expression straight onto a bean, with no delegate class: camunda:expression="${notificationService.notifyCustomer(execution.getVariable('customerId'))}" together with camunda:resultVariable="notificationId" to store the return value.

Option three — External Task (the recommended production choice):

<bpmn:serviceTask id="Task_CheckCredit" name="Check credit"
                  camunda:type="external"
                  camunda:topic="credit-check" />

5.3 Why external tasks scale better

With a JavaDelegate your code runs inside the engine's transaction: a job executor thread is held until your HTTP call returns; a 30-second service dries up the pool and stalls every process. Code and engine must also share a JVM and a deployment.

External tasks invert the model: the engine says "there is work on topic credit-check", and a worker pulls it from outside, takes a lock, does the work and reports back. The benefits: deployment isolation (another service in another language, scaled independently), natural backpressure (a slow worker just makes jobs queue up), fault isolation (a worker crash does not take the engine down; the lock expires and the work returns), and a tunable lockDuration for genuinely long work.

Diagram: the fetch-and-lock cycle of an external task — چرخهٔ fetch-and-lock در external task.

sequenceDiagram
  participant W as External worker
  participant E as Camunda 7 engine
  W->>E: POST /external-task/fetchAndLock (topic, lockDuration)
  E-->>W: list of locked tasks + variables
  W->>W: call downstream system
  alt success
    W->>E: POST /external-task/{id}/complete (variables)
  else technical failure
    W->>E: POST /external-task/{id}/failure (retries, retryTimeout)
  else business error
    W->>E: POST /external-task/{id}/bpmnError (errorCode)
  end

With the official Spring Boot starter (org.camunda.bpm.springboot:camunda-bpm-spring-boot-starter-external-task-client):

import org.camunda.bpm.client.spring.annotation.ExternalTaskSubscription;
import org.camunda.bpm.client.task.*;

@Component
@ExternalTaskSubscription(topicName = "credit-check", lockDuration = 20000)
public class CreditCheckHandler implements ExternalTaskHandler {

  private final CreditClient creditClient;

  public CreditCheckHandler(CreditClient creditClient) { this.creditClient = creditClient; }

  @Override
  public void execute(ExternalTask task, ExternalTaskService service) {
    String customerId = task.getVariable("customerId");
    try {
      CreditResult r = creditClient.score(customerId);
      if (r.score() < 500) {
        service.handleBpmnError(task, "CREDIT_DENIED", "score too low");
        return;
      }
      service.complete(task, Map.of("creditScore", r.score()));
    } catch (TransientException e) {
      int retriesLeft = task.getRetries() == null ? 3 : task.getRetries() - 1;
      long backoffMs = (long) Math.pow(2, 3 - retriesLeft) * 10_000L;   // 10s, 20s, 40s
      service.handleFailure(task, e.getMessage(), stackTraceOf(e), retriesLeft, backoffMs);
    }
  }
}

camunda:
  bpm:
    client:
      base-url: http://camunda:8080/engine-rest
      worker-id: credit-worker-1
      max-tasks: 10
      lock-duration: 20000
      async-response-timeout: 20000   # long polling

async-response-timeout is long polling: the worker sends one request and the server holds it open until work arrives or the timeout expires. Without it, workers poll every few hundred milliseconds; across 20 workers and 5 topics that saturates the engine database with pointless queries — the first thing to check when tuning Camunda 7.

5.4 Transaction boundaries and async continuations — the most important part of Camunda 7

The Camunda 7 engine advances from one wait state to the next inside a single transaction. A wait state is where it persists state and returns control: user tasks, receive tasks, timers, event-based gateways, external tasks.

So if ten service tasks sit between two user tasks, all ten run inside the transaction that called startProcessInstance, and if the tenth throws, all ten roll back — while the external APIs you already called do not, leaving you inconsistent. The fix is an asynchronous continuation: camunda:asyncBefore="true" or camunda:asyncAfter="true" tells the engine "commit here, create a job, and let the job executor do the rest later".

Diagram: transaction boundaries with and without async continuations — مرزهای تراکنش با و بدون async continuation.

flowchart LR
  subgraph TX1["One transaction - risky"]
    S1(("Start")) --> A1["Charge card"] --> A2["Reserve stock"] --> A3["Send email"] --> U1["User task"]
  end
  subgraph TX2["Split with asyncBefore"]
    S2(("Start")) --> B1["Charge card"]
    B1 -.->|"commit / job"| B2["Reserve stock"]
    B2 -.->|"commit / job"| B3["Send email"]
    B3 --> U2["User task"]
  end

Practical rules: asyncAfter after every external call that cannot be rolled back; asyncBefore on the branches after every parallel gateway, otherwise both branches run sequentially on one thread in one transaction and you get no real parallelism; and asyncBefore on the first activity of request-started processes so the caller gets a fast response.

5.5 Messages, correlation, timers and retries

Correlation answers "which running instance does this incoming message belong to?":

runtimeService.createMessageCorrelation("PaymentConfirmed")
    .processInstanceBusinessKey(orderId)     // or .processInstanceVariableEquals("orderId", orderId)
    .setVariable("paidAt", Instant.now().toString())
    .correlateWithResult();

Timers are ISO-8601: timeDuration (PT30M, P3D), timeDate (an instant such as 2026-09-01T09:00:00Z) and timeCycle (R3/PT1H, or a cron expression). Retry with backoff is declared on the activity and can list several intervals:

<bpmn:serviceTask id="Task_CallProvider" camunda:type="external" camunda:topic="provider"
                  camunda:asyncBefore="true">
  <bpmn:extensionElements>
    <camunda:failedJobRetryTimeCycle>R3/PT10S,R3/PT5M,R2/PT1H</camunda:failedJobRetryTimeCycle>
  </bpmn:extensionElements>
</bpmn:serviceTask>

Three attempts 10 seconds apart, then three 5 minutes apart, then two an hour apart — then an incident. That is the exponential backoff you built in resilience, expressed declaratively without a single line of code.

5.6 Testing processes

With org.camunda.bpm.assert:camunda-bpm-assert you test a process like a state machine:

import static org.camunda.bpm.engine.test.assertions.bpmn.BpmnAwareTests.*;

@Test
void shouldRejectWhenCreditDenied() {
  when(creditClient.score(any())).thenReturn(new CreditResult(300));

  ProcessInstance pi = runtimeService.startProcessInstanceByKey(
      "order-fulfillment", Map.of("customerId", "C-1", "amount", 5000));

  assertThat(pi).isWaitingAt("Task_CheckCredit");
  complete(externalTask());                    // simulate the worker
  assertThat(pi).hasPassed("EndEvent_Rejected").isEnded();
}

Write one test per decision path (approved, rejected, timeout, cancelled) and cover delegates/workers with plain unit tests. Driving the whole happy path against a real service is slow and brittle — the testing pyramid holds for BPMN too (see testing).

6. Java integration — Camunda 8

In Camunda 8 your application is a client, not the engine's host. The plain client is io.camunda:camunda-client-java with the CamundaClient class:

try (CamundaClient client = CamundaClient.newClientBuilder()
        .grpcAddress(URI.create("http://localhost:26500"))
        .restAddress(URI.create("http://localhost:8080"))
        .build()) {

  client.newDeployResourceCommand().addResourceFromClasspath("order-fulfillment.bpmn").execute();

  client.newCreateInstanceCommand()
        .bpmnProcessId("order-fulfillment").latestVersion()
        .variables(Map.of("orderId", "O-1001", "amount", 12_500))
        .execute();
}

With Spring Boot it is cleaner:

<dependency>
  <groupId>io.camunda</groupId>
  <artifactId>camunda-spring-boot-starter</artifactId>
  <version>8.8.9</version>
</dependency>

camunda:
  client:
    mode: self-managed
    auth:
      method: none
    grpc-address: http://localhost:26500
    rest-address: http://localhost:8080
    worker:
      defaults:
        max-jobs-active: 32
        timeout: PT1M
        retry-backoff: PT10S
    deployment:
      enabled: true

import io.camunda.spring.client.annotation.JobWorker;
import io.camunda.spring.client.annotation.Variable;
import io.camunda.client.api.response.ActivatedJob;
import io.camunda.client.api.worker.JobClient;

@Component
public class CreditWorker {

  // constructor injection of creditClient and providerClient omitted

  // job type defaults to the method name unless you set it; the return value becomes process variables
  @JobWorker(type = "credit-check")
  public Map<String, Object> checkCredit(@Variable String customerId) {
    return Map.of("creditScore", creditClient.score(customerId).score());
  }

  // full control over failure handling and backoff
  @JobWorker(type = "call-provider", autoComplete = false)
  public void callProvider(JobClient jobClient, ActivatedJob job) {
    try {
      providerClient.send(job.getVariablesAsMap());
      jobClient.newCompleteCommand(job).execute();
    } catch (BusinessRejection e) {
      jobClient.newThrowErrorCommand(job)              // reaches an error boundary event
               .errorCode("PROVIDER_REJECTED")
               .errorMessage(e.getMessage())
               .execute();
    } catch (TransientException e) {
      jobClient.newFailCommand(job)
               .retries(job.getRetries() - 1)
               .retryBackoff(Duration.ofSeconds(30))
               .errorMessage(e.getMessage())
               .execute();
    }
  }
}

A worker has exactly three answers: complete (done), fail (a technical failure, with retries and backoff; when retries reaches zero an incident is raised) and throwError (a business error handled at the BPMN level).

Message correlation uses the message name plus a correlationKey, and messages are buffered on the broker for timeToLive — so unlike Camunda 7, a message arriving before the process is not necessarily lost:

client.newPublishMessageCommand()
      .messageName("PaymentConfirmed")
      .correlationKey("O-1001")          // matched against the correlation variable in the model
      .messageId("payment-evt-77")       // used for deduplication
      .timeToLive(Duration.ofMinutes(30))
      .variables(Map.of("paidAt", "2026-08-13T10:00:00Z"))
      .execute();

Testing uses the official Camunda Process Test library (io.camunda:camunda-process-test-spring for Spring, camunda-process-test-java for the plain client): annotate the test class with @CamundaSpringProcessTest and assert with CamundaAssert.assertThat(instance).isActive().hasActiveElements("Task_ManualApproval").

For local development, Camunda 8 Run starts everything with ./c8run start; Operate is at http://localhost:8080/operate, the gateway on port 26500.

7. DMN — separating the decision from the flow

DMN (Decision Model and Notation) is BPMN's sibling standard for modelling business rules, and its workhorse is the decision table: input columns, output columns, one rule per row.

The hit policy says what happens when several rows match:

In Camunda 7 table expressions can be JUEL or FEEL; in Camunda 8 only FEEL. A FEEL input entry looks like [18..30], >= 1000, not("VIP"), or "GOLD","SILVER".

In Camunda 7 you can evaluate a table directly with decisionService.evaluateDecisionTableByKey("insurance-rate").variables(...).evaluate(), or wire it into the model with a business rule task:

<bpmn:businessRuleTask id="Task_Rate" name="Determine rate"
                       camunda:decisionRef="insurance-rate"
                       camunda:resultVariable="rateResult"
                       camunda:mapDecisionResult="singleEntry" />

In Camunda 8 the same task binds to a decision via the Zeebe extension (decisionId, resultVariable), and .dmn files deploy with the same newDeployResourceCommand.

The senior rule: DMN is for decisions, not for flow. A table returning "the name of the next step" hides the process and makes the BPMN model lie. Return a business value — a rate, a risk band, an approver group — and branch on it in a gateway.

8. Orchestration or choreography? BPMN or saga?

• Orchestration: a central component knows what comes next and commands the services — a conductor.
• Choreography: no centre; each service publishes an event and others react — dancers hearing the music.

Diagram: central commands versus reacting to events — دستور مرکزی در برابر واکنش به رویداد.

flowchart TB
  subgraph O["Orchestration"]
    ENG["Workflow engine"] --> S1["Payment"]
    ENG --> S2["Inventory"]
    ENG --> S3["Shipping"]
  end
  subgraph CH["Choreography"]
    P["Payment"] -- "PaymentCaptured" --> BUS[["Event bus"]]
    BUS --> I["Inventory"]
    I -- "StockReserved" --> BUS
    BUS --> SH["Shipping"]
  end

BPMN is not a competitor to the saga pattern; it is one way to implement it. Saga (built in ms-data) says: split a distributed transaction into local transactions with a compensating action for each. The orchestration-based variant in BPMN is exactly that: a compensation boundary event on each activity plus a compensation throw event, with the engine compensating only the activities that actually ran, in reverse order.

Diagram: an orchestrated saga with compensation handlers — saga با compensation در BPMN.

flowchart LR
  A["Reserve stock"] --> B["Charge card"] --> C["Book courier"] --> D{"All ok?"}
  D -- "no" --> X(("Throw compensation"))
  A -. "compensate: release stock" .-> CA["Release stock"]
  B -. "compensate: refund" .-> CB["Refund payment"]
  C -. "compensate: cancel booking" .-> CC["Cancel courier"]
  D -- "yes" --> E(("End"))

9. Operations — where projects die

9.1 Monitoring and incidents

The operations tool is Cockpit in Camunda 7 and Operate in Camunda 8; both render instances on the diagram, highlight the active token and list incidents. Common actions: retry a job, change a variable, cancel an instance, and modification — moving a token to another activity by hand.

But a dashboard is not enough. At minimum five metrics belong in monitoring with alerts: open incidents (anything older than 15 minutes should page someone), age of the oldest due job (over 5 minutes means the job executor is behind), active instances per definition (steady growth means instances that never finish), process duration at P95 (SLA breaches) and history table size.

For Camunda 7 this query can be wired straight into monitoring — the jobs that have turned into incidents:

SELECT j.id_ AS job_id,
       j.process_instance_id_,
       j.retries_,
       j.duedate_,
       left(j.exception_msg_, 200) AS error
FROM   act_ru_job j
WHERE  j.retries_ = 0
ORDER  BY j.duedate_ NULLS LAST
LIMIT  50;

SELECT j.id_ AS job_id,
       j.process_instance_id_,
       j.retries_,
       j.duedate_,
       SUBSTR(j.exception_msg_, 1, 200) AS error
FROM   act_ru_job j
WHERE  j.retries_ = 0
ORDER  BY j.duedate_ NULLS LAST
FETCH  FIRST 50 ROWS ONLY;

To see how many old versions are still alive, write the same style of query against act_ru_execution joined to act_re_procdef, filtered by e.parent_id_ IS NULL and grouped by key_ and version_.

9.2 Migrating running instances

You have three options: drain (let them finish — the simplest and safest), cancel and restart (only when there are no side effects), or migration.

// Camunda 7
MigrationPlan plan = runtimeService
    .createMigrationPlan(sourceDefinitionId, targetDefinitionId)
    .mapEqualActivities()                       // elements with equal ids are mapped automatically
    .mapActivities("Task_OldName", "Task_NewName")
    .updateEventTriggers()                      // rebuild timers and subscriptions
    .build();

runtimeService.newMigration(plan)
    .processInstanceQuery(runtimeService.createProcessInstanceQuery()
        .processDefinitionId(sourceDefinitionId))
    .executeAsync();                            // as a batch, not one transaction

The Camunda 8 equivalent is a single command: client.newMigrateProcessInstanceCommand(key).migrationPlan(targetProcessDefinitionKey).addMappingInstruction("Task_OldName", "Task_NewName").execute().

mapEqualActivities() only works if element ids stayed stable — hence meaningful ids from day one. And always rehearse a migration against a copy of the production database first; a wrong one strands instances in impossible states.

9.3 Performance and database growth — cheat sheet

# Camunda 7 — nightly history cleanup
camunda:
  bpm:
    generic-properties:
      properties:
        historyCleanupBatchWindowStartTime: "02:00"
        historyCleanupBatchWindowEndTime: "05:00"
        historyCleanupDegreeOfParallelism: 2
        historyTimeToLive: P30D

In Camunda 8 the equivalent is managing secondary storage: retention policies on the Elasticsearch/OpenSearch indices or the RDBMS tables, plus monitoring their size. The rule is the same: no data stays forever unless you explicitly decided it should.

10. Interview questions