Home

VanillaBP adapter for the bpm-crafters Process-Engine-API

This adapter connects a VanillaBP business application to the bpm-crafters Process-Engine-API. The Process-Engine-API does not depend on one BPMS. Like VanillaBP, it is an API which no single vendor owns. It works at a lower level, though: you send it commands, while VanillaBP describes your process in aspects of your business code. An adapter built on top of it can reach every BPMS the Process-Engine-API supports.

Experimental, mock-first. We develop the adapter against an in-memory fake of the Process-Engine-API. Feature by feature, this shows where VanillaBP or the Process-Engine-API needs an extension. We collect these findings in GAPS.md, and the Deviations page links its entries.

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

1. Getting started
   The dependencies per platform, and the smallest configuration which runs.
2. Configuration
   The adapter's keys, how to plug in a real engine and what your BPMN model has to look like.
3. What becomes of a shared value
   Why this is the one adapter which cannot tell you what an engine stores, and what to measure instead.
4. Deviations
   Where this adapter does not deliver what VanillaBP promises, which is a longer list than elsewhere.
5. Why an adapter against the Process-Engine-API?
   What this adapter is for, and why we build it against a fake first.

Getting started

Spring Boot

<dependency>
  <groupId>io.vanillabp</groupId>
  <artifactId>process-engine-api-adapter-spring-boot</artifactId>
  <version>2.0.0</version>
</dependency>

Quarkus

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

<dependency>
  <groupId>io.vanillabp</groupId>
  <artifactId>vanillabp-quarkus-integration</artifactId>
  <version>2.0.0</version>
</dependency>
<dependency>
  <groupId>io.vanillabp</groupId>
  <artifactId>process-engine-api-adapter-quarkus</artifactId>
  <version>2.0.0</version>
</dependency>

Minimal configuration

The adapter brings the VanillaBP adapter type process-engine-api. VanillaBP finds your workflow modules by their descriptors. It reads their BPMN from the conventional location classpath*:<workflow-module-id>/processes/process-engine-api. Two things you have to configure yourself:

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

You have to choose a name-clash-avoidance mode. The Process-Engine-API cannot keep workflow modules apart on its own, so this adapter cannot serve VanillaBP's default by-adapter. See Deviations. You may leave out the adapter id of the example above if you use the id process-engine-api. That id is the type itself, so it needs neither type nor the priority list.

By default the adapter runs against the in-memory mock engine which comes with it. To run against a real implementation, provide your own beans of the Process-Engine-API interfaces. See Configuration.

The adapter treats the Process-Engine-API as a remote BPMS, so the application also needs a phase-two outbox. The outbox holds the calls to the BPMS until your own transaction has committed. It works out of the box with JPA, JDBC and MongoDB, see Configure the transaction outbox.

Why an adapter against the Process-Engine-API?

Some features cannot be expressed through the Process-Engine-API. We document each such gap in GAPS.md, and an adapter for one particular BPMS can fill it. This adapter uses only the plain Process-Engine-API artifact. It uses none of the existing platform implementations or adapters of the Process-Engine-API. They bind to a platform and take their configuration in a different way than VanillaBP does. The Process-Engine-API is written in Kotlin but works fully with Java. The adapter is pure Java; the Kotlin standard library comes in as a dependency of the Process-Engine-API.