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

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

The adapter itself contributes no further configuration keys: 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. So VanillaBP's four-level configuration pattern has nothing to resolve here.

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.