Renaming a BPMN process

Renaming a BPMN process is ordinary refactoring in your source tree. But it is the one rename which reaches into your BPMS (business process management system). The old bpmnProcessId stays there. So does every version ever deployed under it, and so do the workflows still running on them. Your software brings only the new name. This page shows how to rename without leaving those workflows behind.

1. What your BPMS keeps
   Why a deployment under a new id changes nothing about the old one.
2. Declaring the old id
   The one annotation which does the whole job.
3. Two ways to end the rename
   Keep the old model for a while, or let it go. What each way costs.
4. What the start says afterwards
   The lines about the old id in your log, and what each of them asks you to do.
5. Versions are counted per process id
   The trap of the rename. Where a version range and outfaded-versions belong because of it.
6. When the old id can go
   How you learn that its last workflow has ended.
7. What a rename does not change
   Starting workflows, scoping, and what VanillaBP will not do for you.

What your BPMS keeps

A BPMS knows a process by its id and counts the versions of that id upwards. So if you deploy a model under a new id, you create a NEW process at version 1. Nothing gets renamed. Everything deployed before is still there under the old id. So is every workflow which was started on it. These workflows keep running and wait for their messages. The BPMS delivers their next task to your application under the old id.

Your source tree does not know the old id any more, and that is the whole problem. Without the declaration below, the deliveries of those workflows arrive for a process which no @WorkflowService answers for. And the startup check for old versions does not look at the old id either, because your application deployed nothing under it.

Declaring the old id

One annotation says that your class answers for both names:

@WorkflowService(
        workflowAggregateClass = OrderApproval.class,
        bpmnProcess = @BpmnProcess(bpmnProcessId = "OrderApproval"),
        secondaryBpmnProcesses = @BpmnProcess(bpmnProcessId = "order_approval"))
public class OrderApprovalService {

  @WorkflowTask
  public void checkCredit(final OrderApproval order) { ... }

}

VanillaBP registers the handler methods of a class under EVERY id the class declares. So a task of a workflow started under order_approval finds the same methods as a task of OrderApproval. The workflow aggregate is the same class, and the ProcessService is the same bean. Your business code never learns that there were two ids.

If the two generations of your model need different handlers, name the versions of the old id:

        secondaryBpmnProcesses = @BpmnProcess(bpmnProcessId = "order_approval", version = "1-3")

version on a declaration is a fallback. It applies to every handler method of the class which names no version itself, and it works per declaration. One class per generation of the model describes this. Read the numbers off your engine. On Camunda 7, look at the process definitions of that id. On Camunda 8, run a process definition search. Or leave the attribute out. Then the methods serve every version the BPMS holds under the old id.

A task which only the OLD model has needs a method of its own. Its version range says so:

  @WorkflowTask(taskDefinition = "assessRiskManually", version = "1-3")
  public void assessRiskManually(final OrderApproval order) { ... }

Such a method matches no task of the model you deploy now. The start does not complain about it, because serving a version the BPMS still holds is its job.

Two ways to end the rename

The declaration is the same either way. The difference is whether the old model stays in your resources while its workflows finish.

Deploy both models until the old workflows have ended. Rename the process in a COPY of the BPMN file and keep the old file next to it. Your workflow module then deploys order_approval and OrderApproval. Both processes are deployed, so everything is wired on every BPMS. The tasks of the old workflows reach your methods exactly as before, and new workflows start under the new id. The only extra thing you carry is a BPMN file which you know you will delete. This way asks nothing of your BPMS and nothing of this page. It also covers the one case which the second way does not cover.

Let the old model go and keep the declaration. Delete the old BPMN file and declare its id, as above. Nothing is deployed under the old id any more. What happens to the workflows still running there depends on what your adapter does with the declaration:

BPMS	The tasks of the old workflows	The check of the old versions
Camunda 8	served. If a job type carries no process id, the workers of your deployed processes fetch those jobs anyway. Under name-clash-avoidance: use-prefix the adapter opens one worker per task definition you declare for the old id. It reads the models the cluster holds under that id, so a task inside a multi-instance element gets its iteration context. One case is not covered, see below	reported
Camunda 7	served. The engine runs the model a workflow was started with. So the adapter reads the models the engine still holds under the old id and wires their tasks	reported
bpm-crafters Process-Engine-API	not served. The API offers no way to read the models the engine holds. The start warns once per declared id (gap 23 of that adapter's GAPS.md)	not reported

Both adapters tell you during startup what they wired for a declared id. So you read it before the first of those workflows reaches a task, not afterwards.

One case on Camunda 8 is not covered, because a worker there subscribes to a NAME. A @WorkflowTask(id = "Activity_...") method names no task definition at all. So no job type can be built for it, and the start says so. For this case, take the first way and deploy both models for a while. On Camunda 7 the case does not exist. The models are read from the engine, so the elements are there.

Two more things follow the workflows across the rename, on both Camunda adapters. First, a waiting workflow may need a message whose name only the OLD model declares. correlateMessage accepts it. The check reads the models the BPMS holds for the ids your application declares, not the models this version of the application deployed. It refuses a name only after it has read them again in that same call. Second, the BPMS itself may keep starting workflows under the old id. Camunda 7 fires the timer starts of the old model and matches its signal subscriptions as long as the definitions exist. Those starts are still full VanillaBP workflows: @WorkflowStartedByBpms, the tasks and @WorkflowEnded all reach your methods. If you do not want this, take the timer start or the signal start out of a last deployment under the old id.

What the start says afterwards

Every result of the check for old versions now applies to the old id as well. On the first start after the rename you should see the count of what is still out there:

INFO  4 workflow(s) still run on BPMN process 'order_approval' (workflow module 'order-approval'), which
      this application does not deploy any more - adapter 'camunda8' holds 3 version(s) of it: 1, 2, 3.
      They keep being served because a @WorkflowService declares that id (secondaryBpmnProcesses), which
      is how a renamed BPMN process stays served, so this is not a defect. [...] The number falls to zero
      as they end, and it is what tells you when the declaration and the methods serving it can go.

Nothing is wrong there. But watch the number: it tells you when the rename is over. Three other lines are worth acting on:

• A task definition of an old version which NO method of yours serves is a warning. It is an error if workflows still run on that version, and the error says how many. Each of them runs into an incident at its next such task. This check exists to tell you before that happens. Add a method whose version range covers that version, or declare the version obsolete.
• A declared id of which the BPMS holds NO version at all gives one warning. The warning names the ids your module deploys. After a rename this is the good news, see below. But before the last workflow has ended, it means the id is misspelled.
• Your adapter writes one line per declared id about what it wired for it. That is the workers Camunda 8 opened for the job types of the old id, or the versions whose models Camunda 7 read. Or the line says that nothing had to be opened, because the deployed processes reach those jobs anyway. A line which says that something cannot be reached is the one to act on. It names what to change.

Some BPMS cannot be asked about the versions of a process. There, the old id is still served exactly as described above, and only the reports stay silent. What each BPMS can tell is in what this costs, and what a BPMS has to support.

Versions are counted per process id

This is the trap of a rename. order_approval holds versions 1, 2 and 3. OrderApproval starts at 1 again. So version 2 of the old id and version 2 of the new id are different models which only share a number. This has two consequences.

A numeric range belongs to the declaration it stands on. A method's own version applies to every process the method serves, the old id included. So version = "1-3" also covers the versions 1 to 3 of the new id. Where that matters, put the range on the @BpmnProcess declarations. Each of them carries its own range, and the methods inherit it.

outfaded-versions for the old versions belongs under the old id, at the workflow level:

vanillabp:
  workflow-modules:
    order-approval:
      workflows:
        order_approval:               # the OLD id
          adapters:
            camunda8:
              outfaded-versions:
                - "1-3"

If you wrote the same setting at adapter level, it would cover version 1 of the new id as well. That is the version your start has just deployed. So the application would refuse to start, and it would tell you why. Note one more thing. If you configure a workflow key for an id which no BPMN resource of the module carries, you get a warning of its own. That warning names the declared id as one of the two cases where this is intended.

When the old id can go

The rename is over when nothing runs under the old id any more. Two lines of your log tell you. First, the count above disappears. Second, at some point your BPMS forgets the definitions themselves, because an operator deleted them or the history cleanup of the engine did. Then the declared id is reported as one under which the BPMS holds nothing. Now remove the secondary declaration together with the methods you kept for it. The next start is quiet.

You do not have to wait for the workflows if you do not want to serve them any longer. Fade the old versions out as shown above, and VanillaBP stops asking for methods. With outfaded-versions-in-use: FAIL, workflows still running on them make the start fail. So you get a start which refuses to come up instead of a report you might miss.

What a rename does not change

• Starting a workflow. startWorkflow always starts the process of the primary declaration. So new workflows begin under the new id from the first start onwards. The old id serves what is already running and nothing else.
• The scope of your identifiers. Your workflow module reaches the BPMS either with a prefix or with a tenant of its own. That is name-clash avoidance, and it applies to the old id like to every other id. A rename is not a BPMS migration and needs no configuration change.
• What the BPMS holds. VanillaBP deletes no process definition. It does not migrate running workflows to the new id either. Both are decisions with consequences which your operator owns. They are made with the tools of your BPMS.
• Finding a rename by itself. VanillaBP asks your BPMS about the ids your application declares, and about nothing else. Reading every definition a tenant holds would mean reading the processes of other applications. So a rename which you do not declare stays invisible.