Repository navigation
BPMS adapters
A BPMS adapter connects VanillaBP to a concrete BPMS (business process management system). Your business
code never depends on it. You add the adapter as a dependency, configure it below
vanillabp.adapters.<id> and reference it in vanillabp.prioritized-adapters. Everything else stays
the same across all BPMS. Several adapters may be active at the same time. This is the basis of
BPMS migration.
-
Available BPMS adapters
Which adapters exist, how each of them behaves, and where its own documentation is. -
The dependency to add
The Maven coordinates per BPMS and platform, and why the VanillaBP BOM does not manage their versions. -
What happens if you forget the adapter
The message VanillaBP writes while booting, and the case where Quarkus reports the gap instead. -
Adapters are not the only thing that plugs in
What an extension is, where its configuration lives, and the one you can look at. -
What is documented in the adapter's wiki?
Which parts of the documentation only the adapter can write, so you know where to look for what.
No BPMS in the house yet? Then start with choosing a BPMS. It compares what the adapters can tell VanillaBP and what each engine asks of your application. The list below is the short answer to "which ones are there".
| BPMS | Adapter type | Characteristics | Documentation |
|---|---|---|---|
| Camunda 7 | camunda7 |
embedded engine; delivers tasks in its own transaction, moves workflows on after your transaction committed | Wiki · Repository |
| Camunda 8 | camunda8 |
remote cluster, eventually consistent | Wiki · Repository |
| bpm-crafters Process-Engine-API | process-engine-api |
BPMS-agnostic API, treated as remote BPMS | Wiki · Repository |
An up-to-date list is also published at https://www.vanillabp.io.
A BPMS which is not in that table needs an adapter written for it. The guide for that is
ADAPTER-AUTHORS.md.
It covers the two interfaces an adapter implements, what the VanillaBP core does for the adapter so that no
adapter builds it twice, and what an adapter promises with its answers. It is written for the team which builds
an adapter, not for an application which uses one.
| BPMS | Spring Boot artifact | Quarkus extension |
|---|---|---|
| Camunda 7 | org.camunda.community.vanillabp:camunda7-adapter-spring-boot |
org.camunda.community.vanillabp:camunda7-adapter-quarkus |
| Camunda 8 | org.camunda.community.vanillabp:camunda8-adapter-spring-boot |
org.camunda.community.vanillabp:camunda8-adapter-quarkus |
| Process-Engine-API | io.vanillabp:process-engine-api-adapter-spring-boot |
io.vanillabp:process-engine-api-adapter-quarkus |
Give the dependency a version of its own. Adapters are released on their own schedule, so the VanillaBP BOM does not manage their versions, on purpose. On Spring Boot the adapter also brings VanillaBP's Spring Boot integration along. So besides the workflow module, the adapter is the only VanillaBP dependency your application needs.
Several adapters at the same time are allowed. BPMS migration is built on this.
Nothing runs, and VanillaBP says so while the application boots:
No VanillaBP BPMS adapter found in classpath! A workflow module was found (a 'META-INF/workflow-module'
marker file), but no adapter which could run its workflows - and on Spring Boot an adapter is also what
brings VanillaBP's Spring Boot integration, which is missing as well.
Add a BPMS adapter as a dependency of your application. Which adapters exist, and the Maven coordinates
of each one, is listed at
https://github.com/vanillabp/adapter-platform-integration/wiki/BPMS-adapters
Adding several adapters is what migrating from one BPMS to another needs - VanillaBP runs them side by
side.
Their versions are NOT managed by the VanillaBP BOM: BPMS adapters are released on their own schedule,
so name a version of your own.
On Quarkus the same message asks for an adapter extension and points at the table above for its name. An application which brings no workflow module at all is not reported. It has nothing to run.
That message comes from the core extension vanillabp-quarkus-integration. So this extension has to be
part of the module which builds the application. If it is missing too, no VanillaBP code takes part in
the build. Quarkus then reports the gap in its own words, as an unsatisfied dependency for type
io.vanillabp.spi.process.ProcessService. The
Quarkus integration
page shows that error and which dependencies belong where.
Besides the BPMS adapter, an extension may take part in deploying your workflow modules. It joins the deployment after the adapter has read and deployed a model, and it sees that same model. It wires its own concerns against the model, and it starts and stops together with the adapter. It never talks to the BPMS for VanillaBP. That stays the adapter's job.
An extension may bring annotations of its own. Your workflow service then has methods which VanillaBP
itself knows nothing about. The same scan which finds your @WorkflowTask methods also finds them. What
such a method means is described by the extension, not by this wiki. When an extension reports something
to a system outside your application, it writes that report into the
phase-two outbox your application already
has. So the report is sent once your transaction committed, and it is repeated until it arrives. A
receiver which is down causes a delay, but the report is not lost.
Configuration lives in the places the VanillaBP core reserves for an extension. These places are
the levels a setting is written at. An extension
reads both halves of that ladder. One half is the four levels of a setting which is not about a BPMS. The
other half is the four levels which name one adapter, because an application may run two adapters and has
to be able to tell them different things. That makes eight positions. vanillabp.extensions.<extension>.*
is the most general one and
vanillabp.workflow-modules.<module>.workflows.<workflow>.tasks.<task>.adapters.<adapter>.extensions.<extension>.*
the most specific. They merge key by key like every other setting.
Reading both halves needs one rule which the ladder does not have: which of the two wins when both say something. The level is checked first. Inside a level, what is said for the adapter wins over what that level says in general. So what a workflow says for all adapters wins over what the workflow module told one of them. And what the workflow told that one adapter wins over what the workflow itself says. What one adapter is told never reaches the other one.
The extension's own documentation says which keys are below it. An extension which brings no
configuration of its own from earlier versions has nothing to do for any of this. VanillaBP binds
vanillabp.extensions.<extension> itself, as flat text. It hands that section over as it was written and
declares nothing inside it.
An extension may instead bring a section of the tree of its own, and one does. The Business Cockpit reads
vanillabp.cockpit.* and the cockpit sections of a workflow module. Its version 1 read the same places,
so an application which upgrades to version 2 keeps its configuration. Such an extension binds that part
of the tree itself. It uses the same overlay a BPMS adapter uses for keys of its own: a
@ConfigurationProperties("vanillabp") class on Spring Boot, a second @ConfigMapping(prefix = "vanillabp")
on Quarkus. VanillaBP neither reads those keys nor knows them. On Quarkus the overlay is what stops a
key below vanillabp from ending the startup.
If you want to look at a concrete extension, take the
VanillaBP Business Cockpit. It reports the user tasks and
the workflows of your modules to a cockpit server, and users work on their tasks there. Your application
says what the cockpit shows about each of them by writing details providers. Its platform-neutral half
extensions-commons lives in the cockpit's own repository and knows no BPMS. The half which knows one
comes in one repository per BPMS. Its wiki has the dependency, the keys and what that engine is able to
tell the cockpit:
Camunda 7,
Camunda 8 and the
Process-Engine-API.
If you come from version 1, the section Business Cockpit on
the migration page says what an upgrade changes.
As a user of an extension, you only add its dependency and configure it as its own documentation
describes. Building one is a different matter. The mechanism (ExtensionWiringService, ordering, model
matching) is documented for contributors in
migration-adapter/README.md.
That module is the part of VanillaBP which knows about all configured adapters and elects between them, see
the glossary. An application configures nothing about it.
Three things, and only that adapter can tell you each of them. Everything else is behavior which is the same on every BPMS. This wiki describes it, and the adapter wikis do not repeat it.
Its Configuration page lists the dependencies to add, the minimal configuration and the adapter's
own keys below vanillabp.adapters.<id>.*. Where a key varies by scope, it also lists it below workflow
module, workflow and task, see Configure the adapters.
The page also says what your BPMN model has to look like for that BPMS: which attribute names a task
definition, what a message event needs, and which parts of the workflow aggregate reach the BPMS.
Its What becomes of a shared value page is about the values your aggregate shares, after VanillaBP has flattened them. It says what that BPMS does with them: which of them it stores as they are, what the rest needs, how your application influences that, and what happens if you say nothing. Every adapter wiki asks these four questions in the same order, so you can read two BPMS side by side.
Its Deviations page lists where that adapter does not deliver what this wiki promises, one sentence
each, with an outlook if there is one. The reasons for a deviation are in the README.md of the adapter
repository, and the entry links it.
