How to Manage Model Versions

In the following short tutorial I will explain how you can manage multiple versions of a workflow model and how Imixs-Workflow supports multiple model versions in a productive business application.

The Imixs-Model-Management

The Imixs-Workflow engine supports multiple model versions from the same process model. Each time a running process instance is updated, the Imixs-Workflow engine applies the same model version as the process instance was created with. Therefor the Imixs-Workflow engine compares the internal model version with the model versions provided by the model repository. In case the current model version is no longer supported, the active process instance will be automatically upgraded to the latest version available in the repository. With this feature it is possible to manage different versions of the same workflow process. To distinguish different model versions, you need a versioning concept.

Semantic Versioning

The concept of “Semantic Versioning” from Tom Preston-Werner will be the basis for the versioning method of process models. Applying the semantic versioning, the version number is separated into three digits:

  1. 2. 3 
  |  |  |-- patch level
  |  |-------- minor version 
  |-------------- major version

Major Version

The first digit indicates the major version number. This is in our case the general main release of a model.  The major version number should only be increased if a general redesign of  whole the process model was done.

Minor Version

The minor version number is used for new functions and enhancements in the process flow. For example after adding a new task or a new event, the minor version number should be increased.

Patch Level

The last digit is used for the Patch Level of a model. It indicates bug fixes or changes of naming or wording.

The semantic versioning can be perfectly used for the BPMN model file. This helps you to manage different version within your modellng tool:


We typically prefix the filename with the process name to maintain different workflows in the same directory.  In the example above we have an Invoicing workflow in the version 1.0.0. The model file itself should also be stored in a code repository like Git. This allows you to remove deprecated models from your code base.

The Model Version

Also the Imixs-Workflow Model holds a separate version number. This version number is mandatory and can be maintained in the Workflow Profile of the Imixs-BPMN modeling tool:

We prefix the version number again with the process name followed by a two-digit version number. Applied to the “Semantic Versioning” only the Major and Minor Version number is used here!

The reason for this shorter version number is, that the model repository of a business application should not hold different patch levels of the same model. Remember, the patch level is only used to  indicates bug fixes or changes of naming or wording. Only if the model is extended functional the minor version number is increased or in case of a new process variant the major version number:

Modelversion    File Version            Comment 
invocing-1.0    invocing-1.0.0.bpmn     First draft
                invocing-1.0.1.bpmn     typo
invocing-1.1    invocing-1.1.0.bpmn     additional approval
                invocing-1.1.1.bpmn     change mail message
                invocing-1.1.2.bpmn     change history text
invocing-2.0    invocing-2.0.0.bpmn     new Invoicing process

In this example version 1.0 of the Invoicing process was first patch with a typo and next extended with an additional approval, which leads to Minor version 1.1. In this version again then some text changes were made. And finally a complete new Invoicing process was designed, with leads to the new Major version 2.0.

From the view of the running process instances only 3 different model versions exist. From the view of the code repository the model file exists in 6 different versions.


With the concept of “Semantic Versioning” process models can be easily handled in different versions. Even if you need to patch an already running model, you don’t need to worry about polluting the model repository of your business application if you use only 2 digits for internal model version.

Leave a Reply

Your email address will not be published. Required fields are marked *