Deviations

Deviations

Where this adapter does not deliver what VanillaBP's platform-wide contract promises. The list is longer than for a BPMS-specific adapter, which is the point of this adapter: it is built mock-first to find out what the Process-Engine-API would have to offer. Every entry has a full explanation in GAPS.md, which also names what would close it.

None of these gaps is a defect of an engine behind the API. They are properties of the API this adapter speaks.

Workflow modules cannot be kept apart by the engine

The API has no tenants, no namespaces and no per-deployment scope, so VanillaBP's default name-clash-avoidance mode by-adapter is rejected while deploying and you have to choose use-prefix or none, see Configuration. use-prefix works without engine support, at the price of the adapter rewriting the raw BPMN XML by element name, which covers the dialects it knows. GAPS 15

Only one adapter id of this type is possible

The engine is handed to the adapter as application-provided beans without any per-instance connection configuration, so two adapter ids of this type would talk to the very same engine and the boot fails with a guiding message. A migration between two engines behind the Process-Engine-API is therefore not expressible. GAPS 14

Workflow awareness cannot be probed

The correlation commands are final and cannot carry a PREFLIGHT_CHECK, so the adapter cannot ask whether a workflow exists and answers optimistically with a one-time guiding WARN. In a migration setup a wrong "yes" routes the operation to the wrong BPMS, so use this adapter as the only configured BPMS until the gap is closed. The same final classes are the reason message correlation has no phase one at all and travels with the default execution mode. GAPS 11 (why)

An unreachable engine looks like an unknown task

Command failures are untyped, so a failing task or user-task probe cannot be told apart from an engine which is down and maps to "unknown". This matters in migration setups only, where the answer decides which BPMS serves the operation. GAPS 10 (why)

The engine never reports a workflow it started itself

Timer, signal and conditional start events cannot be served: nothing in the API says "the engine just started this process", so VanillaBP could not build the workflow aggregate everything downstream is addressed by. A process carrying such a start event is rejected while deploying, with a message naming the element and the alternatives. GAPS 16

The end of a workflow is not reported

@WorkflowEnded methods are never called, because the API has no event, callback or subscription saying that an instance ended. Deploying WARNs naming the BPMN process; the workflow itself runs normally, which is why this is not a deployment failure. GAPS 17

A changed aggregate cannot be pushed

aggregateChanged throws in both phases, since the API modifies the payload of TASKS only and has no command whose subject is a running process instance. Phase one already refuses, so the application sees the failure at its call rather than in an outbox dispatch after the commit. Completing a task pushes the shared values, so a task the workflow waits at is the way out. GAPS 18

Processes have no version, only a tag

The API knows no version of a deployed process definition and no deployment order, so a version made of numbers, a range or a >/< boundary matches nothing and is reported once with a guiding message. An exact tag (version = "release-2024") works where the engine supplies the task-meta key processDefinitionVersionTag. Methods without the attribute serve every version, as everywhere else - and where the engine supplies no tag either, they are the ONLY methods a delivery reaches: a task whose every method names versions fails the delivery with a message saying so, rather than picking one of them. GAPS 19

Cancellations are not delivered

@TaskEvent CANCELED never arrives, for service tasks and user tasks alike: the subscription's termination callback carries the task ID and no aggregate reference, so the adapter cannot tell which workflow to notify. Details

A delivered task does not name its BPMN process

The adapter expects the engine to supply the BPMN process ID as the task meta entry bpmnProcessId. Without it a task definition used by several processes of one workflow module cannot be routed, which a guiding error explains, and the task definition then has to be unique across the module's processes. The mode use-prefix sidesteps this, since it scopes task definitions by their process anyway. GAPS 6

Messages are not deduplicated by the engine

The API offers no message id, so a redelivered dispatch correlates again where the outbox retries after a crash. This concerns correlations carrying a correlation id, which VanillaBP deduplicates engine-side on other BPMS. Model catch events idempotently where a duplicate correlation would matter. GAPS 11

Workflows have no observable timeline

The API has neither a repository nor a query/history API, so the viewer is answered from what THIS application version deployed: getProcessDefinitions reports the deployed process versioned by its deployment key, getBpmnXml the deployed resource byte for byte, and getWorkflowHistory the definition plus a null element history, the SPI's documented "not supported by the underlying BPMS". Three consequences: call activities cannot be drilled into, usedByElements is never filled, and a workflow running on a definition deployed by a PREVIOUS application version is served with the currently deployed model. GAPS 12 and GAPS 13

Older versions of a process cannot be checked

VanillaBP looks at the versions a BPMS still holds when an application starts and reports the task definitions of older versions no method serves any more. This adapter reports no version at all (the Process-Engine-API has no version notion, see Deviations above and GAPS.md no. 19), so the check is switched off here and outfaded-versions has nothing to name. A dropped task definition shows up the way it did before: when a workflow reaches it. Details

An overdue open task is only reported

VanillaBP measures how long a task left open by a @TaskId handler has been waiting and says so once it passed vanillabp.delivery.max-task-age, see an open task and how old it is. The API hands out a task subscription rather than a lock this adapter renews, so there is nothing to stop and no incident to raise instead: the report is all that happens here.

Concurrent branches of a workflow are not pointed out

A BPMN process holding more than one token has two branches writing the same workflow aggregate, and without a version attribute one of the two writes is lost without an error. Other adapters read their model while wiring and let VanillaBP warn about it. This adapter never holds a model, so it reports nothing and the hint stays silent here. Everything else works: a version conflict in the transaction VanillaBP owns is recognized, named by a guiding message and passed on to the engine as a failed task, and the four ways to avoid the collision are the same, see Two writers on one aggregate. GAPS 21