Home - camunda-community-hub/vanillabp-camunda7-adapter GitHub Wiki

This adapter connects a VanillaBP business application to Camunda 7, the embedded workflow engine. The engine runs inside your application's JVM and uses your application's database. The adapter calls your code for a task inside the engine's own transaction, unless you give the engine a datasource of its own. Operations which move a workflow forward run right after your transaction has committed. So they can be repeated when they lose a conflict with a concurrent change. See Transactional behavior.

The VanillaBP wiki describes everything which is not special to Camunda 7: workflow modules, workflow aggregates, the @WorkflowTask contract, BPMS migration, and the setup on Spring Boot and Quarkus. Read it first. This wiki only adds what a user of THIS adapter has to know:

1. Getting started
   The one dependency per platform, and the smallest configuration which runs.
2. Transactional behavior
   Which operations run after your transaction committed, and what still answers inside it.
3. Configuration
   The adapter's keys, what your BPMN model has to look like and what reaches the engine.
4. What becomes of a shared value
   What this engine stores as itself, the serialization format the rest needs, and what it costs to configure none.
5. Cockpit, Tasklist and Admin
   Camunda's web applications at /camunda, on Spring Boot.
6. Deviations
   Where this adapter does not deliver what VanillaBP promises.
7. What the adapter changes in the BPMN it deploys
   The listeners, the rewritten identifiers, the transaction boundaries and the business key a call activity passes on.
8. Supported Camunda version
   Which Camunda 7 this adapter pins, and what its end-of-life means for you.
9. Extending the adapter
   For an extension running inside the engine: where its hooks go and what the adapter answers.

Coming from VanillaBP 1? The platform wiki lists the keys of the version 1 Camunda 7 adapter one by one, and what each key became. It also lists the behaviours which changed: Migrating from VanillaBP 1 to 2. This wiki describes version 2 and does not repeat that list.

You need one dependency. It brings the platform-neutral core of the adapter and the VanillaBP Spring Boot integration with it:

<dependency>
  <groupId>org.camunda.community.vanillabp</groupId>
  <artifactId>camunda7-adapter-spring-boot</artifactId>
  <version>2.0.0</version>
</dependency>

VanillaBP and the adapter are both Quarkus extensions, so you add both of them:

<dependency>
  <groupId>io.vanillabp</groupId>
  <artifactId>vanillabp-quarkus-integration</artifactId>
  <version>2.0.0</version>
</dependency>
<dependency>
  <groupId>org.camunda.community.vanillabp</groupId>
  <artifactId>camunda7-adapter-quarkus</artifactId>
  <version>2.0.0</version>
</dependency>

On Quarkus the adapter runs in JVM mode and without Camunda's web applications, see Deviations.

The adapter provides the VanillaBP adapter type camunda7. If Camunda 7 is the only BPMS of your application, adding the dependency is all the configuration you need. You set no vanillabp.* property at all. VanillaBP finds the adapter on the classpath, and its id is the type camunda7. It finds your workflow modules by their descriptors. It reads their BPMN from the usual location classpath*:<workflow-module-id>/processes/camunda7.

The engine uses the application's datasource, so you do not have to point it at a database either. The exception is an application with SEVERAL datasources, see Configuration.

Anything else you may want to configure goes into the adapter's own section:

vanillabp:
  adapters:
    camunda7:
      history-time-to-live: P30D

Give the adapter instance a custom id when the id should not be the type, for example to run two Camunda 7 engines side by side. Then you have to set the type and the priority list:

vanillabp:
  prioritized-adapters:
    - c7
  adapters:
    c7:
      type: camunda7

That is all. The adapter builds the embedded engine on the application's DataSource and transaction manager. It creates the engine's schema at boot and deploys the BPMN files of every workflow module. All other keys are optional. The Configuration page describes them.

The application must have a DataSource and a transaction manager, because a Camunda 7 application always needs a database.

The engine does not get the BPMN files exactly as you wrote them. The adapter prepares them while it deploys them. None of this changes the model in your repository. (why)

• Listeners are added where VanillaBP needs to hear from the engine: the lifecycle of a task, every start event of a process, and the end of a workflow. A called process, declared in secondaryBpmnProcesses, gets no end listener. The listener on its start event only passes the caller's name on. A called process is a step of its caller's workflow, so its start and its end are not reported.
• Identifiers are rewritten when name-clash avoidance is set to use-prefix. This covers process ids and the names of messages, signals, errors and escalations. It covers the calledElement of a call activity, so that it still points at the renamed process. And it covers decision ids together with the decisionRef of a business rule task, so that the task still finds the renamed decision, also where the decisionRef is an expression (see Configuration). (why)
• Transaction boundaries are set while the engine parses the model, so the deployed XML does not show them. Service, send, business rule and script tasks get asyncBefore and asyncAfter. So each of them runs in a job and a transaction of its own. User tasks and receive tasks get asyncAfter only, and the asyncBefore of a user task is switched off. If you set one of these flags yourself on such an element, the adapter replaces it. The engine ignores the flags on a compensation handler. So all handlers of one compensation run in one transaction, and the deployment warns about it. (why)
• A call activity passes the business key on to the called process, where both processes work on the same workflow aggregate. Camunda 7 does not do that on its own. This adapter keeps the aggregate's id in the business key. Without it, the first task of the called process cannot find the aggregate. A call activity which names its process by an expression gets nothing written onto it, because the model does not say which process will be called. Instead, the adapter asks about the called process while it runs. So the caller's name still reaches it where both work on one aggregate (see decision 32). A called process with an aggregate of its own keeps its own identity. A camunda:in businessKey you modelled yourself always wins.
• A call activity says whether it continues the caller's business case. The adapter writes this as a camunda:property named vanillabp:sameWorkflowAggregate, wherever it passes the business key on. This property tells a running workflow how far the multi-instance context of a caller reaches, see The iteration a called process runs in.

All of this, and the transaction boundaries of Transactional behavior, applies to a process which one of your @WorkflowService classes claims. A process may also just sit in your file, marked with vanillabp.workflow-modules.<module>.workflows.<process>.implemented-externally: true. Such a process is deployed as you modelled it, except for the renamed identifiers of use-prefix. A process somebody else deployed into the same engine is not changed at all, and neither are its asyncBefore and asyncAfter (a process nobody claims).

This adapter uses Camunda 7.24.x. Camunda 7.24 is the last feature release of Camunda 7 (October 2025, LTS, long-term support). The community edition is end-of-life, and no more community releases are expected. VanillaBP's BPMS migration lets you move away from it without touching business code.