What is the standard way to version bpmn model?


We do keep all the bpmn models in version control so to some extend they are versioned. But are their any practices on how to version the bpmn models like :

  • Do we keep the version number in the file name?
  • Do we keep the version number in the ProcessId ?
  • No versioning in the name or processid needed ?
  • How to version them then ?


(Note: Not sure how this applies to Cloud, as I mostly do Platform, but …)

The Runtime engine itself actually keeps track of version numbers for you. Every time you deploy a new version of the model to the engine, it increments the version number of the BPMN model. In Platform, if you’re using the Enterprise Version, you can then ‘migrate’ processes from one version to another.

The problem with versioning them by changing the file name is that they would then get deployed as new, different models and there would be no ability to do any migrations.

It would seem to me that as long as you’re using version control on the source, version numbers in the file name are not needed. I’ve honestly never thought about using version numbers in the processID though.

Hope that helps!

Building on what @davidgs said: Zeebe assigns a version number internally, but that is only semantic within the system.

The process id, if you version it, will require a change in your code that starts instances of that process. So you could do that, but it then becomes a cross-cutting concern.

One way to do it is like this:

  1. Deploy the process model to Zeebe.
  2. Get the version number that Zeebe returns.
  3. Add the version number to the XML of the model in a comment.
  4. Commit this to git.
  5. Tag the commit with the process id and version.

The relationship between your version controlled asset and the Zeebe version displayed in Operate and used to start instances of that specific version is only created at deployment time - as Zeebe assigns the next sequential version number to the process model when it is deployed.

To capture this relationship in your system of record requires getting the version number at deployment time, and storing it with the corresponding version commit.

Another way to do it, if you wanted to automate this, is to deploy from a specific git branch or tag pattern. Then in the deployment code, grab the version commit hash that is being deployed, and the version returned from the DeployProcess command, and write that to your system of record.