Rewrite thirteen shorter pages in plain English Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Lxo4MXbp6VPoDkUrTBNXJ1
Blueprints 12: injected beans are named after their role Code examples now call the ProcessService bpms and the use case service loanApproval, the names the blueprints use from now on. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RVEfP4rFpf8XUVXB9CFuL7
A message starts only the process of its own ProcessService The page on message correlation says what startWorkflowByMessage refuses, quotes the exception and the sentence of the start for an adapter which cannot be checked, and says which adapter decides during a migration. The migration page lists it among the behaviours which differ from version 1. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NGP1Z1mjfXKxCgHzecPvuX
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(correlation): the mode a broadcast is scoped by is named and linked The sentence about the consequences of `none` said "the mode" without saying which one, at the end of a page about signals where several settings had been mentioned. It names the name-clash-avoidance mode now and links the section explaining it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CvgyhjwTEh834mwbptZZxh
docs(correlation): the correlation runs on the BPMS, not on every BPMS "AFTER your commit on every BPMS" reads as if the correlation ran on all of them. What the bullet promises is when it runs; that it holds for an embedded engine too is the sentence after it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CvgyhjwTEh834mwbptZZxh
docs: adapter-specific notes move to the adapter which owns them A platform page says what every BPMS has to deliver and where they differ; how one BPMS does it is that adapter's wiki. Several pages carried the second kind. Message correlation lost the Camunda 8 section about what a repetition costs. What stays is the rule underneath it: a BPMS may deduplicate on its own, in a window VanillaBP neither sets nor shortens, and whether that happens is on the adapter's wiki. The Camunda 8 wiki carries the detail now, including the log line naming both readings of a refusal. The model-side table keeps one clause per adapter instead of the recipe, the phase-one list keeps the comparison and leaves the reasoning to the Camunda 8 page, which gained the section explaining why the cluster is not asked, and the signal table says what a broadcast reaches rather than which client command sends it. Workflow tasks stops naming the Camunda 8 property behind an overdue task, the Camunda 7 wiring which completes a task too early, and the two version-tag attributes; in all three the message and the adapter's wiki say it. Workflow modules replaces the two bullets about what a BPMS says about a tenant with the rule and a pointer. BPMS migration replaces the Camunda-8 and Camunda-7 prerequisites of a side-by-side setup with what every BPMS is asked and links both. Observability drops two Camunda 8 examples which illustrated platform rules. Aggregate synchronisation keeps the comparison of what ignoring the recommendation costs but links the Camunda 7 page for the serialization format. The comparisons themselves stay, on purpose: which BPMS reports what, what identifies a delivery, what a model needs so it correlates. That is what a reader comes to the platform wiki for. 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: what a model has to carry so it correlates, per BPMS The page described the API and sent the reader to three adapter wikis for the model side, so whoever took the migration promise literally moved a model from Camunda 7 to Camunda 8 and found that the correlation needs a different modelling step. One table now says it in one place: what a correlation id asks of the model per adapter, what it asks without one (nothing, everywhere), and what the adapter puts into the deployed model itself. Underneath it, what the call verifies while your transaction is still open, which differs for a reason worth reading: Camunda 7 fails where nothing waits for the message, Camunda 8 checks the deployed model because its cluster buffers a message for the time-to-live, and the Process-Engine-API cannot check at all. An application which learned the Camunda 7 behaviour has to unlearn it before it moves. Choosing-a-BPMS carries a line each and links here. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CvgyhjwTEh834mwbptZZxh
docs: the pages follow the decisions taken since 2026-08-11 Camunda 7 progresses a workflow after the caller's commit, through the outbox, since story 63. Three pages still described the model before it: correlating a message, broadcasting a signal and pushing a changed aggregate all said an embedded BPMS does the work inside the caller's transaction. They now say what every adapter does, with the reason in one sentence - a command which loses a concurrency conflict leaves the caller's transaction rollback-only, so it cannot be repeated there. The ordering paragraph of Workflow-aggregates loses its embedded exception for the same reason: an embedded BPMS is dispatched by the same outbox and promises no order either. A workflow module's configuration file carries defaults again (2026-08-21), so the Spring Boot and Quarkus pages stop promising it higher priority than the application's own files. Workflow-modules-in-Spring-Boot no longer says VanillaBP scans the classpath for workflow services: they are found among the bean definitions since 2026-08-26, which changes what a module nobody scanned looks like at startup. The migration guide's property table said retry-backoff is "not yet in version 2". It is back on the Camunda 8 adapter, PT10S by default and resolvable down to a single task, so the row now points there instead of asking readers to report it. Versions read 2.0 everywhere, without a patch digit and without -SNAPSHOT, and the pages which introduce the BOM say once what that means for a build. Two anchors were dead, workflow-visibility-timeout on the Camunda 8 Configuration page and a section about the aggregate's ID which does not exist on Workflow-aggregates. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CvgyhjwTEh834mwbptZZxh
docs(correlation): whether siblings reach the cluster depends on the adapter VanillaBP hands the activation to the adapter when the entry is dispatched, so an adapter which derives a message id of its own can put it there. Where it does not, three elements of a multi-instance call activity are three operations for VanillaBP and one message for the cluster.
docs(correlation): a correlation planned inside a handler carries its activation Multi-instance siblings of one aggregate no longer share an idempotency key: the element instance the BPMS is running is part of the key of a correlation planned while a task handler runs. The page now separates correlating from inside a handler from correlating outside one, because the remedy differs, and says that the Camunda 8 cluster's own net still does not know about activations.
docs(correlation): what an idempotency key deduplicates, and what a loop has to do The key deduplicates the operations still waiting for their dispatch, so the second round of a loop correlating the same message with the same correlation id reaches the BPMS instead of being swallowed for the retention period. What still collides is two correlations planned in one unit of work, and a multi-instance call activity is where the sameness of the aggregate is not the application's choice - so the page says to vary the correlation id per round and per element, and that VanillaBP warns about every discard. Camunda 8 gets a section of its own: the cluster deduplicates by message id for the message time-to-live, one hour by default, which is the longer of the two nets and shortened by no VanillaBP setting. The outbox sections of both platform pages say what the retention still buys after this, and `Workflow-tasks` says that the same property decides correctness on the inbound side. Story 128. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CvgyhjwTEh834mwbptZZxh
docs: a phase-two failure repeating cannot fix blocks the entry at once
Story 54: the election cache also records what VanillaBP knows Elections are no longer the only thing filling the cache: starting a workflow and every inbound delivery record which BPMS holds it. That record is what lets an operation right after a start succeed on a BPMS whose probe reads an eventually consistent model, and it is the reason a clustered application wants a shared cache.
Story 55: point at what an adapter wiki still carries An adapter wiki is now configuration plus deviations, so the pages delegating BPMS specifics have to name the page which answers them: the wiring conventions and correlation mechanics sit on the adapter's Configuration page, what a BPMS cannot serve on its Deviations page. "What is documented in the adapter's wiki?" listed six kinds of content, four of which the adapters no longer keep. Also says that Camunda 7's table-prefix does not start an engine, where the version-1 migration table offers it as the successor of camunda.bpm.*.
Story 44: document telling the BPMS that the aggregate changed Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JfGxTzh2x1suKFoJJv5aXS
docs: when a workflow ends, and that a signal is not buffered Names what each BPMS can honestly report about the end of a workflow, and adds the property a Camunda 8 test uncovered: a broadcast reaches whoever waits at that moment, nobody else. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
docs: a signal's scope is the workflow module Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
docs: signals are not messages Names what a broadcast reaches, why it needs a transaction, that it cannot be deduplicated and why there is no way to send a signal to a single workflow. 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>
Move BPMS-specific content into the adapter wikis The main wiki now documents only what is identical across all BPMS. Everything specific to Camunda 7, Camunda 8 or the Process-Engine-API moved into the respective adapter wiki. Where such content stood, the pages now carry a list of the available adapters linking directly to the matching page of the adapter's wiki. The new page 'Available BPMS adapters' holds the full list and is linked from Home. A custom footer with the VanillaBP logo and the license notice was added. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Document BPMS migration: election, cache and start consistency New page describing the headline feature end to end: configuring several BPMS side by side, the two routing rules (new workflows start in the first-priority adapter, operations on existing workflows go to the BPMS holding them), the election guarantees (unknown falls through, unreachable never falls back, completed is a no-op, guiding exceptions), the election cache including the optional application-provided bean for cluster-shared caching, and the at-least-once property of workflow starts against remote BPMS. Linked from the concept overview, both platform integration pages, the workflow tasks page and the message correlation page. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Add message-correlation page, document story 23 conventions Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015drvS8i7xLpNkuRNXdvtYM