[bug] Embedded adapter: process state and domain state can diverge on rollback

[emaarco]

When using the embedded adapter, any engine interaction — starting a process, correlating a message to a running instance, or sending a signal — inside a @Transactional method does not participate in that transaction. If the transaction rolls back, the engine write is already committed — leaving the system in an inconsistent state where the engine has advanced but the corresponding business object was never persisted.

Same issue as bpm-crafters/process-engine-adapters-cib-seven#30 — tracked separately per adapter.

Steps to reproduce

• Library version: (current)
• JDK version: 17
• Operating system: any
• Complete executable reproducer: see inline code below
• Steps:
  1. Use the embedded adapter in a Spring Boot application (engine and application share the same database).
  2. Inside a single @Transactional service method: save a domain object and perform any engine interaction (start a process, correlate a message, send a signal).
  3. Let the method fail (exception) after the engine call.

@Transactional
fun createOrder(): Order {
    val saved = orderRepository.save(Order.createNew())
    orderProcessPort.orderCreated(saved.id) // any engine call: start, correlate, signal
    throw IllegalStateException("Simulated failure — expect full rollback")
}

Expected behaviour

Because the application and engine share one database, both writes — the domain object and the engine state change — should participate in the same transaction. If the transaction rolls back, neither write is persisted. This all-or-nothing guarantee is one of the main reasons to run an embedded engine in the first place.

Actual behaviour

Only the domain write is rolled back. The engine write is already committed and takes effect regardless. Depending on where in the process lifecycle the call happens this can mean:

• a process instance is started for a business object that does not exist,
• a message correlation advances a running process whose triggering business action was never saved,
• a signal moves the process forward while the application-side state is gone.

In all cases the process and the domain model are now out of sync. Any subsequent engine activity (user tasks, timers, service calls) will operate on missing or stale data and likely cause further errors downstream. In short: what should be a clean rollback turns into silent data corruption.

Technical root cause: all affected API implementations wrap the engine call in CompletableFuture.supplyAsync { } without an explicit Executor, which causes it to run on a separate thread (ForkJoinPool.commonPool()). Spring's transaction context is thread-bound (via ThreadLocal) and is therefore not visible to that thread. The engine call opens and commits its own independent transaction, bypassing the caller's rollback. Per the CompletableFuture javadoc, the no-executor overload always uses ForkJoinPool.commonPool().

// e.g. StartProcessApiImpl.kt, StartProcessByMessageCmd branch
CompletableFuture.supplyAsync {       // ← no Executor → runs on ForkJoinPool, outside the caller's transaction
    runtimeService
        .createMessageCorrelation(cmd.messageName)
        .setVariables(payload)
        .correlateStartMessage()
        .toProcessInformation()
}

Affected classes in c7-embedded-core:

• StartProcessApiImpl — all startProcess variants (lines 27, 56)
• CorrelationApiImpl.correlateMessage (line 28)
• SignalApiImpl.sendSignal (line 25)

[emaarco]

For a possible fix direction see the corresponding comment on the CIB Seven issue: bpm-crafters/process-engine-adapters-cib-seven#30

[zambrovski]

Have you seen the transactional support implemented on the worker level? Are you aware of that?
https://bpm-crafters.github.io/process-engine-api-docs/snapshot/process-engine-worker/docs/process-engine-worker.html#transactional-support

[emaarco]

I'm aware of the transactional support on the worker level, but I don't think it addresses this issue fully. The problem isn't about workers completing external tasks — it's about commands sent to the engine from application code, specifically: starting a process, correlating a message, or sending a signal.

These calls typically originate from REST/GraphQL controllers that invoke a @Transactional use-case. Inside that transaction, the use-case calls adapter APIs like CorrelationApiImpl, which internally delegates to CompletableFuture.supplyAsync { .. } — running the engine call on a separate thread, outside the transaction context.

Looking at the codebase, I just noticed that the completeTask implementation in the service task API (Cib7ServiceTaskCompletionApiImpl) already handles this correctly. It executes the engine call synchronously on the caller's thread and returns a pre-completed future:

Is this what you mean with your comment when you are writing about "support on the worker-level"?

override fun completeTask(cmd: CompleteTaskCmd): CompletableFuture<Empty> {
    // ... engine call happens right here, on the calling thread
    externalTaskService.complete(cmd.taskId, workerId, cmd.get())
    // ...
    return CompletableFuture.completedFuture(Empty)
}

My suggestion is to apply exactly this pattern to the other API implementations (StartProcessApiImpl, CorrelationApiImpl, SignalApiImpl) — replace the supplyAsync calls with synchronous execution and return completed futures instead.

That way, these engine calls naturally participate in the caller's transaction, just like completeTask already does.

I've drafted this in PR #31 of cib-seven:
bpm-crafters/process-engine-adapters-cib-seven#31