Rewrite Home, the platform pages, BPMS migration and Workflow modules in plain English
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lxo4MXbp6VPoDkUrTBNXJ1
VanillaBP owns four tables, and decision 16 says so (446)
The housekeeping table came with the night window, so Home and the migration page
count four now. Observability drops the number. The two links to decision 16 follow
its new heading.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RVEfP4rFpf8XUVXB9CFuL7
Name the Camunda 8 adapter in the community hub
The Camunda 8 adapter lives in camunda-community-hub/vanillabp-camunda8-adapter,
so the links point there.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RVEfP4rFpf8XUVXB9CFuL7
Name the Camunda 7 adapter in the community hub
The Camunda 7 adapter lives in camunda-community-hub/vanillabp-camunda7-adapter.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RVEfP4rFpf8XUVXB9CFuL7
docs: the application names the workflow it did not start
Starting workflows described the state before stories 504 and 653. It said VanillaBP
builds the aggregate of a workflow the BPMS started, that the process instance key or the
trigger time becomes its id, and that a workflow can arrive with a business key of
somebody else's choosing. None of that is true any more.
The page now says what the code does. A @WorkflowStartedByBpms method returns the
workflow aggregate, and that aggregate names the workflow. The BPMS holds the name
afterwards: Camunda 7 as the business key, Camunda 8 and the Process-Engine-API as the
process variable named after the id attribute. Every start is then read from the state of
the workflow: a name with an aggregate is our own start, no name is a start past
VanillaBP, and a name no aggregate carries is refused.
The trigger carries no time, and the section which recommended taking one is gone. The
method is required where the BPMS fires a start event by itself; a plain or message start
event is judged when somebody uses it, not at boot.
Timers and Migrating from version 1 said the same old thing in one sentence each and
follow along, the first one also to the renamed section.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0168Fox39crp8dfWkZ9W84Ub
Merge remote-tracking branch 'origin/wiki/wave-77-compensation-and-states'
# Conflicts:
# Home.md
docs: a timer has a page of its own
The three forms a BPMN timer takes, the three places it can sit in, and what
reaches the model when the time comes out of the workflow aggregate. Says what
VanillaBP does not do here: no timer API, and no adapter reads the date, the
duration or the cycle.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0168Fox39crp8dfWkZ9W84Ub
docs: the event subprocess, and the two things which hang on it
Two statements of ours come from this construct: the warning about a
second writer on the aggregate, and the end which reports COMPLETED
although it reads like a cancelation. Both were written down, the
construct behind them was not.
Story 469.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0168Fox39crp8dfWkZ9W84Ub
docs: what compensation is, and what VanillaBP adds to it
A compensation handler is an ordinary @WorkflowTask on every adapter, and
nothing in the code or in the wikis said so. The page says what the
deployment does with such a handler, what the handler is given, and why
VanillaBP promises nothing about the order the handlers run in.
Story 466.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0168Fox39crp8dfWkZ9W84Ub
docs: one word for the reader, and eight places for a setting
The glossary now names both words for the same thing: the core calls it an
extension, its own documentation calls it an adapter sitting next to the BPMS
adapter. The migration page says adapter and points at the glossary.
The configuration paragraph said two places. There are eight: four levels, each
of them again for one adapter. Checked against
MigrationAdapterProperties#resolveForExtension, migration-adapter/README.md and
decision 53. It also says now that the core reads from the general towards the
specific, and that an extension without a section of its own has nothing to do
for it, which leaves the Business Cockpit's own section as the exception it is.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RYPiyZ32jQQhqYKx44cw23
docs: there are three tables VanillaBP owns
The payload table came with the outbox, so the count on four pages was one
short. Home, Quarkus-integration and Observability only count the tables, so
they now count three. Migrating-from-version-1 names them, so it names the
payload table as well.
The Quarkus outbox section named the outbox table alone while the Spring Boot
one names both, so a reader of that page could find only two of the three
names. It now names the payload table too.
The heading of decision 16 carries the same wrong number and is not touched
here, because the links to its anchor would break with it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RYPiyZ32jQQhqYKx44cw23
docs: phase two is a moment, not a BPMS call
Phase one is your transaction, phase two is everything which runs after its commit.
The names say when work runs and not who runs it, so a call to a BPMS is one kind of
phase-two work and an operation an extension registered for itself is another.
The glossary of the home page, the integration SPI table, the extensions page and the
outbox section of both platform pages now say the same thing, so a reader meets one
definition instead of two.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RYPiyZ32jQQhqYKx44cw23
docs: what an extension does, and in which order
Wave 10 gave an extension three things the wiki did not describe: a
contract may say it never writes the workflow aggregate, the order of
the keys an invocation offers decides which method runs, and an adapter
runs before every extension while extensions are not ordered against
each other.
The new page collects what an extension author needs. The pages about
workflow aggregates and about ordering point at it instead of repeating
it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Re2yjHbaFRvnHyW61E3sao
docs: one page for running more than one node
What a team needs before it starts a second instance was spread over three pages,
and the synthesis was left to the reader. It stands in one place now, and the
three pages keep the long explanations and link to it.
The correction worth reading twice: a shared election cache is not a requirement
for several nodes. Routing never depends on the cache, an entry is a hint, so
five nodes cost up to five questions to the BPMS instead of one and nothing else.
Where it does bite is the record which says that VanillaBP itself started a
workflow, because that is what buys the patience while an eventually consistent
BPMS catches up. A node which lacks it does not wait a shorter time, it does not
wait at all, and the call raises WorkflowNotFoundException. That needs a remote
BPMS, an operation inside its visibility window and a node other than the one
which started the workflow, all three at once - which is why the page says who
has to care and who does not.
Story 197.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XjxJNwTRcKzTmXCwLU7Wi4
docs: the integration SPI page starts with what it is for
The page opened with the direction of the API, which reads like something every
application has to implement. What the reader needs first is that VanillaBP
already answers these questions and that this is the way to answer one of them
differently, which most applications never do. The direction follows in the
second paragraph, where it is a detail rather than the headline. Home entry and
glossary say the same thing now.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XjxJNwTRcKzTmXCwLU7Wi4
docs: the page is called integration SPI
The artifact is io.vanillabp:vanillabp-integration-spi, so the wiki calls the
thing what its coordinate calls it instead of inventing a second name. Page
renamed, all links and the glossary entry follow.
The adapter SPI is gone from the wiki: it is nothing a reader of these pages
implements. Where the start instant explains its own name, the reason is now
VanillaBP's rather than an SPI the page never introduces.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XjxJNwTRcKzTmXCwLU7Wi4
docs: a page for the business SPI, testing parked
The wiki mentioned the business SPI and the two support modules without ever
saying what they are or why they exist. Business-SPI.md answers both: the two
APIs and their directions, why these interfaces are released with the platform
instead of with the SPI for Java, the five contracts an application may
implement, and how the artifact reaches a build. Linked from Home, the
migration page, both platform pages and the aggregates page.
Migrating from version 1 no longer mentions states version 2 passed through on
its way, and no longer names the Process-Engine-API adapter: version 1 had no
support for that BPMS, so nobody upgrades from it.
Testing.md moves to parked/Testing.md.txt. GitHub creates a page for every file
with a markup extension, so the .txt keeps it out of the wiki's page list while
the text stays in the history until the reworked testing strategy arrives with
the blueprints.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XjxJNwTRcKzTmXCwLU7Wi4
docs: a page about testing a workflow module
"How do I test this" is a first-week question and the wiki had no answer, while the material was
spread over a skill, an adapter and the blueprints. The new page walks the three kinds a developer
meets in the order they meet them: a workflow service tested with a hand-written double of
ProcessService, the module booted against the in-memory engine of the Process-Engine-API adapter,
which proves everything except the model itself, and a test against a real BPMS as the blueprints
write it. Every class, dependency and property named on it was read in the code first.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XjxJNwTRcKzTmXCwLU7Wi4
docs: the guide is linked, the boundary is named
Two answers existed and were not reachable from where the question comes up. Somebody weighing an
adapter for another BPMS found the adapter guide only by browsing the repository, so the adapter
page and the glossary link it and say who it is written for. And no page said who may complete a
user task or read the viewer API, which is a question VanillaBP does not answer at all: it
authorizes nothing and publishes no endpoint, the connection an adapter opens to its BPMS being
the one security surface it does own.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XjxJNwTRcKzTmXCwLU7Wi4
docs: every page opens with what to do and carries a table of contents
A reader who has never used VanillaBP met the reasoning for a rule before the rule
itself, and had no way of telling how far to read before writing a first workflow.
The pages now start with the sentence somebody can act on and keep the background
where it belongs, further down. Nothing was deleted; what explains a rule moved
behind it.
Every page gained a numbered table of contents in the shape Home and the Spring Boot
page already used, so a reader sees the sections and what each of them answers before
scrolling. Where a first heading only repeated the title GitHub shows above the page,
it is gone and the page starts with its first sentence.
Home is now ordered the way a newcomer needs it, and what VanillaBP is sized for
became a page of its own: it answers a question somebody asks before they start, not
one they trip over in the middle of the introduction. The architecture picture from
the repository's diagrams folder is embedded there, linking to its Excalidraw source.
The horizontal rules of the workflow-module pages are gone, the heading is the
separator everywhere else. Hints are written as sentences rather than marked with a
label, headings sit at one depth per page, and the paragraphs written by hand over
the last months were brought to the tone of the rest without changing a single
statement they make.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
docs: what VanillaBP is sized for, and the shared cache as the lever
Home says it where a reader decides whether this is their framework: business processes whose
steps are minutes and days apart, implemented in high quality at a price a normal project can
afford, and deliberately not a stream of thousands of operations per second. That trade is
behind several rules in this wiki, the most visible one being that VanillaBP asks the BPMS
which engine holds a workflow instead of keeping a register of its own.
BPMS-migration says what to do when that asking gets expensive, next to the bean which does
it: shared, the node which started the workflow writes the association and every other node
reads it, so the BPMS is asked once per workflow rather than once per workflow and node. The
entries stay hints, so a stale one still costs a walk and never a wrong route.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CvgyhjwTEh834mwbptZZxh
docs: a rule says where its decision is written down
Five decision logs hold 61 entries, the wikis linked none of them, and 22 of the 42
objections an outside review raised were already answered in one. A reader who wondered why
a rule is what it is had no way there short of reading source repositories.
So a rule carries a (why) link now, pointing at the numbered entry which decided it. Home
says once what the links are and where the logs live, and the form is the same on every page
of every wiki: an inline link at the end of the sentence stating the rule. Numbers are handed
out once and never reused, so the links keep resolving.
The rules the review named are linked first - the outbox on Camunda 7, probing per operation,
the two retentions, sharing aggregate values, the Camunda 8 correlation key - and the
remaining entries follow wherever a page states their rule. BPMS-adapters also says in one
sentence what the module migration-adapter is, which it linked without explaining.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CvgyhjwTEh834mwbptZZxh
docs: a page for readers who have to pick an engine first
The comparison a newcomer needs existed twice, in the contributor skills and in the review
guide, and neither is published. Choosing-a-BPMS carries it now: one row per property, one
column per adapter, plus what the review found missing - when the shared values reach the
BPMS and what a crash between commit and command leaves behind, what identifies a delivery,
whether the age of an open task is measured at all, and whether the adapter can tell that a
workflow is unknown to it or has to guess. Three of those rows decide how much an
application has to carry itself, so they are repeated below the table in prose.
Underneath it, one short section per question somebody arrives with: a Camunda 7 in
production, a Camunda 8 cluster, or nothing to run an engine on yet.
Home links it from the adapters entry and BPMS-adapters from the top, both in the words a
reader without a BPMS would use.
Home also gets the glossary the wiki was missing. It defines the terms a user meets while
reading it - adapter id, election, the outbox, the delivery log - and stays out of the
contributor vocabulary, which the repositories document.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CvgyhjwTEh834mwbptZZxh
docs: what an operator gets to see while VanillaBP delivers
Story 92. New page listing every meter with the question it answers, the health
endpoint per platform and the six MDC keys with a log pattern to paste. The
metric which tells a quiet system from a stalled one comes first, because that
is the one somebody looks for at three in the morning.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K7HLKaJvVpdCiSYxhwHJTc
docs: how workflows are started, by you and by the BPMS
New page describing both ways a workflow comes into being: your application
handing over the aggregate, and the BPMS starting a process on its own by a
timer, signal or conditional start event. The latter names the ID rules, the
optional @WorkflowStartedByBpms method and what each BPMS can serve.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Unify the wording of all pages
Two passes over the wiki:
1. The pages written earlier (workflow modules, workflow aggregates, the
platform integration intros) were aligned with the wording of the newer
ones: grammar and typo fixes, consistent terminology (process = the BPMN
model, workflow = one execution; message names instead of event names)
and active voice instead of impersonal constructions.
2. All pages were revised to read less like generated text: em dashes in
prose replaced by proper punctuation, promotional phrasing and filler
removed, boldface and inline-header lists reduced to where they aid
scanning.
Two corrections found on the way: the Quarkus workflow-module page pointed
at the "main Spring Boot application module", and the property precedence
lists of the two platform pages are sorted in opposite directions, which is
now stated (Spring Boot: highest first, Quarkus: lowest first, matching the
config source ordinals 250/251/255/256).
No configuration key, behavior or example was changed.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Extensions belong to contributor documentation (story 29 follow-up)
The Extensions page documented a mechanism only someone BUILDING an integration needs -
that is contributor documentation and now lives in migration-adapter/README.md.
BPMS-adapters gained a short section instead: besides the adapter, an extension may take
part in deploying workflow modules (the VanillaBP Business Cockpit as the example), users
only add its dependency, and building one is documented in the migration adapter's README.
The Home entry is gone with the page.
Add the V1 migration guide and the extensions page (story 29)
- **Migrating from VanillaBP 1 to 2** (new page, linked from Home): what stays (business
code, aggregates, BPMN models - Camunda 8 models even byte-identical), then every
required change with before/after - Java 21 / Spring Boot 4 / Quarkus 3.37, the renamed
adapter artifacts, the moved AggregatePersistenceAware import, the
META-INF/workflow-module descriptor (version 1 derived the module id from
spring.application.name respectively the config file name), default-adapter →
prioritized-adapters, adapter settings moving to vanillabp.adapters.<id>.* incl. a
key-by-key table (also naming the V1 keys with no V2 equivalent), the removed
ProcessService overloads, @BpmnProcess.primary, the @Transactional that has to GO from
workflow services, and the default methods of the two SPIs. Plus the behavior
differences (two-phase start, error contract, election, namespaced definition ids,
aggregate sync, the Camunda 8 cancelUserTask gap) and a five-step checklist.
- **Extensions** (new page, linked from Home): what an extension is, the two pipeline
steps it participates in, matching by model AND context type, ordering incl. the
reverse shutdown order, that an extension owns its own SPI (Business Cockpit as the
example), and how to register one on both platforms.
- Both platform pages: the outbox section gained the missing `retention` key and a "What
the outbox guarantees" block (idempotency keys, DONE instead of delete, at-least-once,
blocked entries as an operations duty).
- Workflow-modules: fixed an unclosed code fence and a link that pointed at GitHub's
/_edit URL.
Document the viewing API (story 26)
New page 'Viewing workflows': the three read-only ProcessService methods, the
call-activity drill-down via the secondary history context, the opaque
(adapter-namespaced) process definition ids and the guiding errors - linked
from Home.