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.

1. Workflow modules cannot be kept apart by the engine
2. What the engine already holds cannot be checked
3. Only one adapter id of this type is possible
4. Workflow awareness cannot be probed
5. An unreachable engine looks like an unknown task
6. The engine never reports a workflow it started itself
7. The end of a workflow is not reported
8. A changed aggregate cannot be pushed
9. Processes have no version, only a tag
10. Cancellations are not delivered
11. A delivered task does not name its BPMN process
12. Messages are not deduplicated by the engine
13. Workflows have no observable timeline
14. Older versions of a process cannot be checked
15. An overdue open task is only reported
16. Concurrent branches of a workflow are not pointed out

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

What the engine already holds cannot be checked

When an application starts, VanillaBP asks a BPMS which of the identifiers it is about to deploy somebody else already holds - a process id of another application, a message name of a module deployed years ago - and warns about what it finds. The Process-Engine-API cannot be asked that, for any kind of identifier: there is nothing to search and no model to read, so this adapter says nothing rather than half of something.

What you do get is the check which needs no engine. While a workflow module deploys, the adapter reads the message names, signal names, error codes, escalation codes and task definitions out of its BPMN files, and VanillaBP warns where another workflow module of the same application ends up under one of those names. That matters most under the mode none, where nothing is prefixed, and most of all for a task definition: a task subscription of this API matches a task type for the whole engine, so two modules sharing one task definition means the subscription of one module takes the tasks of the other. The check reads the raw BPMN by element name, so it reaches the dialects the adapter knows, and a decision id stays out of it because this adapter cannot prefix one either. GAPS 24

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" would route the operation to the wrong BPMS, and VanillaBP does not let it come to that: this adapter reports that it cannot locate workflows, so a workflow module which prioritizes it next to another adapter ends the boot with a message naming the ways out. 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. A @WorkflowStartedByBpms method kept for a BPMN process id the application only declares (secondaryBpmnProcesses) is not judged either: VanillaBP would compare it against the start events of a version the engine still holds, and that model cannot be read here, so the check stays silent for such an id. 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. Everything else VanillaBP asks about a held version goes the same way, since no catalog is registered: its start events, the elements which can fork one of its workflows, and how many workflows still run on 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, for the version being deployed and for every older one the engine still runs workflows on. 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