Configuration

Configuration

Two things have to fit for this adapter: its properties and your BPMN model.

1. The adapter's properties
2. Which engine does it talk to?
3. Keeping workflow modules apart
4. The BPMN model for this adapter
5. What reaches the engine
6. What a subscription asks for

The adapter's properties

The adapter is configured at VanillaBP's canonical per-adapter location vanillabp.adapters.<id>.* (see Configure the adapters):

vanillabp:
  prioritized-adapters:
    - pea
  adapters:
    pea:
      type: process-engine-api
      name-clash-avoidance: use-prefix   # or 'none' - this adapter has no default

Key	Default	Description
type	the adapter id	must be process-engine-api; may be omitted if the adapter id already IS process-engine-api
name-clash-avoidance	—	use-prefix or none. VanillaBP's default by-adapter cannot be served here, so the mode has to be chosen, see below
fetch-variables	derived	which payload variables a task subscription asks the engine for. Resolvable per workflow module, workflow and task, most specific wins. derived is the variable holding the workflow aggregate's id plus every variable a @TaskParam of the served tasks names; all is the complete payload of the process instance. Same key and same two values as on Camunda 8, see below

How to reach a BPMS is the concern of the Process-Engine-API implementation you plug in, and it is configured by that implementation's own means. Timeouts and retry behavior are properties of the underlying engine as well - including what becomes of a task whose transaction failed, for instance because another branch of the workflow changed the workflow aggregate in between (two writers on one aggregate): VanillaBP owns that transaction, logs the guiding message and passes the exception on, and whether the engine retries the task or leaves it to somebody is that engine's answer.

Only ONE adapter id of this type can be configured, see Deviations.

Which engine does it talk to?

By default the adapter runs against the in-memory mock engine io.vanillabp.pea.mock.InMemoryProcessEngine shipped with it, which is useful for tests and for exploring the adapter without any infrastructure. Provide your own beans of the Process-Engine-API interfaces to replace it:

• Spring Boot: any bean of the respective interface replaces the mock.
• Quarkus: any non-default CDI bean of the respective interface replaces the mock (the mock is a @DefaultBean).

On startup each workflow module's BPMN resources are parsed (one entry per <bpmn:process isExecutable="true">) and deployed via the Process-Engine-API's DeploymentApi.

Keeping workflow modules apart

The Process-Engine-API has no isolation mechanism of its own, so of VanillaBP's name-clash-avoidance modes two remain and one has to be configured:

Mode	Supported?
by-adapter	no, and it is VanillaBP's default, so this adapter fails the boot naming the workflow module and the two alternatives. You have to choose actively
use-prefix	yes. The adapter rewrites the deployed BPMN itself: process ids, call-activity references, message and signal names, escalation and error codes, task definitions and user-task form references
none	yes. Nothing is scoped, so your identifiers have to be unique across all workflow modules

Prefixing is transparent: your BPMN files, business code and configuration keep the plain identifiers. Only the engine behind the Process-Engine-API sees the prefixed ones, and the adapter translates them back when a task is delivered. Prefixed task definitions carry their BPMN process as well (<workflow module>__<bpmn process>__<task definition>), which is what makes a task deliverable without the engine naming its process, see Deviations.

The BPMN model for this adapter

The Process-Engine-API does not define how a BPMN task names its implementation, so this adapter adopts the Camunda 8 convention (GAPS.md, entry 7). Model with the Camunda Modeler (Camunda 8 / Cloud diagrams); which elements are actually executed is defined by the engine behind the API.

Element	What names the task definition	Notes
service, send, business-rule and script task	the zeebe:taskDefinition type	defaults to the @WorkflowTask method's name
user task	the EXTERNAL zeebe:formDefinition reference	subscribed with TaskType.USER; a matching method is an optional notification handler
message catch event, message boundary event, receive task	the message name	correlated by the aggregate's ID, or by the correlation id where one is passed

Version boundaries of @WorkflowTask(version = ...) work with a version TAG only, see Deviations. Start events the engine fires on its own are rejected while deploying, see Deviations.

A task delivered twice runs your handler once

The Process-Engine-API is a remote BPMS: the adapter reports a task as completed AFTER the local transaction was committed, so an engine which never learned that result hands the task out again. VanillaBP identifies such a delivery by the task ID the engine reports - the same ID on every redelivery of that task, a different one for the next task - and answers a repeated delivery with the outcome it recorded when the handler ran, instead of invoking the @WorkflowTask method a second time. What that covers, and what stays your business, is described with the feature itself: a repeated delivery.

What reaches the engine

The Process-Engine-API is treated as a remote BPMS: the engine can only evaluate what the payload carries. The default of this adapter is therefore that everything is shared, unless you exclude it with @NoSyncWithBPMS (see workflow aggregates).

The shared attributes travel as the payload of every command the adapter sends on behalf of a workflow: the start commands, the completion of a task at the end of a @WorkflowTask method (completeTaskByError for a TaskException included), completing or canceling an asynchronous task, completing a user task and correlating a message. The payload of the completion at the end of a @WorkflowTask is what makes a gateway directly behind that task work.

Independent of the annotations the workflow aggregate's ID is always part of the payload, named after the aggregate's ID attribute: the API has no business-key slot, so that value is how VanillaBP finds the workflow again. Message correlation follows the same rule as everywhere, no message content travels, only the aggregate state.

What a subscription asks for

The other direction. A SubscribeForTaskCmd names the payload variables the subscriber wants, and naming none means the engine hands over everything the process instance holds. That is what this adapter did until VanillaBP 2.0, and it is the same waste Camunda 8 warns about: your @WorkflowTask method is served the workflow aggregate out of your own database, so a delivery carrying a copy of that data pays for something nobody reads.

The adapter names the set instead, per subscription:

• the variable holding the workflow aggregate's id, named after your aggregate's id attribute - the delivery finds your aggregate by it;
• every variable a @TaskParam of the methods serving that task asks for. VanillaBP reads those names off your annotations while it wires your application, which is the only place they exist: this adapter never sees a BPMN model of the deployed process. So the set follows your code - adding a parameter to a method is all it takes for its variable to travel with the delivery.

One subscription serves a task definition across the BPMN processes of a workflow module, so its set is the union over everything it serves; two processes whose aggregates have differently named id attributes both work. The set is sorted, so it stays the same across restarts of one application version.

fetch-variables: all brings the old behaviour back, and a @TaskParam does not need it: the name it spells out is part of the set. What is left for it is a variable reaching a handler under a name no annotation carries. Such a read is not silently answered with a null - it fails the delivery with a message naming the variable, the set and the property, and the engine behind the API applies its retry semantics.

Where no workflow service serves a BPMN process, the id variable cannot be named, and the subscription asks for everything rather than for a set which may be missing what its handler needs.

Every subscription logs what it asks for when it opens. When somebody reports a variable their handler no longer sees, that line answers the first question.