bpmncode versions separately three things that evolve at different paces:
| What | How it is declared | Reference |
|---|---|---|
| Process | @Process(version = n), one class per version |
ProcessDefinitionRef("ORDER", 2) |
| Business rule | @BusinessRule(version = n), one type or method per version |
BusinessRuleRef, as text R-PER-001@2 |
| Message between processes | @MessageVersion(n), one record per version |
MessageVersionRef, as text EV-PERSON-REGISTERED@2 |
Messages have their own guide: Messages between processes.
Each version is a @Process class with the same id and a different version. The versions coexist in the same
application:
@Process(id = "PER-REGISTRATION", name = "Person registration", version = 1)
public class PersonRegistration { … } // requires age 16 (R-PER-001@1)
@Process(id = "PER-REGISTRATION", name = "Person registration", version = 2)
public class PersonRegistrationV2 { … } // requires age 18 and a document (R-PER-001@2, R-PER-003)- Whoever starts chooses the version.
journal.startProcessInstance(ProcessDefinitionRef.of("PER-REGISTRATION", 2), …). Naturally, each version has its own start contract (the parameter of the@StartEventmethod) and each version of the application's API starts one version of the process. - The instance stays bound to its version. Conformance is always checked against the definition it started with, so running v1 instances finish as v1 even when v2 already exists.
- Node ids may repeat across versions of the same process (and usually do), but not across different processes.
@ProcessPart(processRef, version)states which version a helper class contributes to. If the process has several versions, the version is mandatory.- Current version: the highest.
ProcessDefinitionRegistry.processDefinition("PER-REGISTRATION")andDefinitions.process(id)return it;Definitions.versions(id)returns all of them, from oldest to current, andisCurrent(ref)tells whether a version is the current one. - Diagrams: the one of the current version has the process id (
PER-REGISTRATION) and each earlier version its own (PER-REGISTRATION-v1). Each diagram draws a single version of each process. In BPMN, the version is exported aspac:version.
| Change | New version? |
|---|---|
| Refactoring without changing the flow or the rules | no |
Changing texts (name, documentation) |
no |
| Adding, removing or reordering nodes or flows | yes: running instances must follow the flow they started with |
| Applying another version of a rule | yes, if instances must be able to tell which rule was applied to them |
| Changing the start contract in an incompatible way | yes, and the previous version coexists while someone uses it |
To retire a version, stop starting it and delete its @Process class when no active instances of it remain
(ProcessInstanceHistory.instances(ProcessDefinitionRef.of("PER-REGISTRATION", 1)) filtering the
ProcessInstanceSummary.Active ones).
If it is retired too early, the active instances of that version cannot advance: their next step throws
ProcessConformanceException (Process instance <id> runs PER-REGISTRATION v1, which is no longer deployed: keep the @Process class of every version that still has active instances). The history and the views still list them:
completed ones, as always; active ones, with an empty nextFlowNodeIds(). To find out before the first step, the
library checks at startup whether there are active instances of versions that are no longer deployed. It only queries
the versions with active instances (ProcessInstanceStore#activeVersions()), not the instances. What to do if there
are any is a decision of the application, with pac.process.store.undeployed-versions:
| Value | What it does |
|---|---|
warn (default) |
logs a warning with the affected versions and starts |
fail |
does not start |
ignore |
does not check (e.g. if the application monitors it on its own) |
Active process instances belong to versions that are no longer deployed: [PER-REGISTRATION v1]. They cannot continue until the @Process class of each version is deployed again (set pac.process.store.undeployed-versions=fail to stop the start-up instead)
With fail, startup fails with an IllegalStateException with the same message, ending in
(pac.process.store.undeployed-versions=fail). If the store cannot be queried at startup, with warn only the warning
Could not check whether active process instances belong to deployed versions: … is logged and the application
starts; with fail, it does not start.
To recover those instances, deploy the @Process class of their version again.
A rule evolves independently of the processes using it, so it has its own version. Each version is a different type
or method with @BusinessRule, and earlier ones are not touched:
public final class MinimumAgeRule {
public static final String ID = "R-PER-001";
public static final String REFERENCE_V1 = ID + BusinessRuleRef.SEPARATOR + 1; // "R-PER-001@1"
public static final String REFERENCE_V2 = ID + BusinessRuleRef.SEPARATOR + 2; // "R-PER-001@2"
@BusinessRule(id = ID, version = 1, name = "Minimum age of 16")
public static Optional<Violation> check(BirthDate birthDate, LocalDate referenceDate) { … }
@BusinessRule(id = ID, version = 2, name = "Minimum age of 18")
public static Optional<Violation> checkAdult(BirthDate birthDate, LocalDate referenceDate) { … }
}- Referencing:
businessRuleRefs = MinimumAgeRule.REFERENCE_V2. Without a version ("R-PER-001") it is only valid if the rule has one; with several, the application does not start (AMBIGUOUS_REFERENCE). A non-existent version isUNKNOWN_BUSINESS_RULE_REF, and a repeated one,DUPLICATE_ID. - Recording: store the versioned reference in the node outcome
(
FlowNodeOutcome.of("RULES_VIOLATED", "R-PER-001@2")), so the history always tells which version was applied to each case. - Querying:
Definitions.businessRule(ref)andbusinessRuleVersions(id); traceability lists the versions each node applies.
| Change | What to do |
|---|---|
| The threshold or the logic changes | new version |
| The meaning changes | new rule, with another id |
| Refactoring without behaviour change | same version |