Model Versioning

After deploying a first version of your App model containing Case, Process, Form and other models, to the Flowable Engines in for example Flowable Work and Engage, definitions are created for each of these models with a version value of 1. At this point versioning is still very easy to understand, but when deploying a new version of the App Model, versioning becomes a very important topic and something that needs to be considered already from a Modeling perspective.

This guide explains how versioning works with the Flowable Engines and which options can be considered while modeling your Case, Process, Form and other models.

Versioning models in Flowable Design

In Flowable Design models are versioned to be able to go back to an earlier version of the model when necessary. It also helps to see which changes are done to a model after a certain date and by whom. When a model is saved, automatically a new version is created and the old version is stored in a historic model table.

The versioning in Flowable Design is fully independent of versioning in the Flowable Engines at runtime. Let's focus on the versioning of definitions in the Flowable Engines now.

Versioning definitions in the Flowable Engines

When a model is deployed to a Flowable Engine a new definition is created and definitions are versioned. Let's focus on the Flowable BPMN Engine as a starting point. When a process model is deployed to the Flowable BPMN engine, basically a BPMN XML file is deployed individually or as part of an App. For each process element found in the BPMN XML file a new process definition entry is created in definition table of the BPMN Engine. The best practice is to use only one process element in a process model and don't use multiple pool elements in a single process model. Following this best practice, a process model results in one process definition.

Each definition is versioned starting with a version number of 1 and each new deployment of a new model results in a new definition entry with a new version number that adds 1 to the latest already existing definition with the same key. So if for example three deployments are done for a process model with a key value of orderProcess there will be 3 definition entries with version values from 1 to 3.

Another look at this basic principle is the following example where 2 deployments are done for the a process model with the same key.

When starting a new instance of a (process) definition, by default, always the latest version of the definition is used to start the new instance. The Flowable API also allows users to start a new instance for a specific definition, but this is only used in rare cases. The basic principle is, when starting a new instance, the latest definition version will be used.

Another important principle is that when deploying a new definition, already existing instances with the same definition key will keep running in the definition which they have been started / created with. So when a process instance is started with definition version 1 of the orderProcess and version 2 is deployed of this definition then the instance keeps running in version 1. For BPMN processes there are additional options to migrate a running instance to another definition version.

More logic is involved when thinking about the case where a process model has a user task with a form referenced to it. Which version of the form definition will be used? Let's discuss this in the next section.

Versioning when referencing other definitions

Now we have discussed the basic concept of versioning for individual models and definitions, let's take a look at the relationship between definitions in a single App deployment. A typical example of an App deployment consists of multiple models that have relationships, like a case model to a sub process model, or a process model user task to a form model etc. In Flowable Design there are several options available to choose how versioning should work for referenced models. In the following example a process task in a CMMN model references a BPMN sub process model.

By default the Same deployment and Fallback to default tenant options are checked. The Same deployment flag is important, because it instructs the Flowable Engines to use the referenced model from the same App deployment by default. This means that when the process model from this example is deployed in the same App deployment as the case model, always the process definition version from this deployment will be used when creating a sub process instance from this case definition version (also when newer versions are available). This also means that if there's a problem with the process model, and a new version is deployed to solve this, this won't solve the problem for already running case instances. The reason for this is that these case instances will still start a new sub process instance from the same "old" App deployment.

For the cases where you would always like to use the latest version of the available model reference the Same deployment flag can be unchecked. This does mean that when a new sub process instance is created a lookup is done for the latest version of the process definition and this will be used to start the new instance. This same pattern is also implemented for other model references like Form models, Decision Tables etc.

The other option available is Fallback to default tenant. This is only applicable for multi-tenant usage of the Flowable Engines. When this flag is checked, a referenced definition will be looked up within the same tenant as the parent instance, like in our example a case instance. When the referenced definition cannot not be found, a lookup will be done to the default tenant. This supports the use case of having a combination of tenant specific and default models that are reused across multiple tenants. This flag is supported for Case, Process and Decision Table references.