Versioning of Process Definitions
Business Processes are by nature long running. The process instances will maybe last for weeks, or months. In the meantime the state of the process instance is stored to the database. But sooner or later you might want to change the process definition even if there are still running instances.
This is supported by the process engine:
- If you redeploy a changed process definition, you get a new version in the database.
- Running process instances will continue to run in the version they were started in.
- New process instances will run in the new version - unless specified explicitly.
- Support for migrating process instances to new a version is supported within certain limits.
You can see different versions in the process definition table and the process instances are linked to this:
If you are using multi-tenancy with tenant identifiers then each tenant has its own process definitions which have versions independent from other tenants. See the multi-tenancy section for details.
Which Version Will be Used
When you start a process instance
- By key: It starts an instance of the latest deployed version of the process definition with the key.
- By id: It starts an instance of the deployed process definition with the database id. By using this you can start a specific version.
The default and recommended usage is to use
startProcessInstanceByKey and always use the latest version:
processEngine.getRuntimeService().startProcessInstanceByKey("invoice"); // will use the latest version (2 in our example)
If you want to specifically start an instance of an old process definition, use a Process Definition Query to find the correct ProcessDefinition id and use
ProcessDefinition pd = processEngine.getRepositoryService().createProcessDefinitionQuery() .processDefinitionKey("invoice") .processDefinitionVersion(1).singleResult(); processEngine.getRuntimeService().startProcessInstanceById(pd.getId());
When you use BPMN CallActivities you can configure which version is used:
<callActivity id="callSubProcess" calledElement="checkCreditProcess" camunda:calledElementBinding="latest|deployment|version" camunda:calledElementVersion="17"> </callActivity>
<callActivity id="callSubProcess" calledElement="checkCreditProcess" camunda:calledElementBinding="versionTag" camunda:calledElementVersionTag="ver-tag-1.0.1"> </callActivity>
The options are
- latest: Use the latest version of the process definition (as with
- deployment: Use the process definition in the version matching the version of the calling process. This works if they are deployed within one deployment - as they are then always versioned together (see Process Application Deployment for more details).
- version: Specify the version hard coded in the XML.
- versionTag: Specify the versionTag hard coded in the XML.
Key vs. ID of a Process Definition
You might have spotted that two different columns exist in the process definition table with different meanings:
Key: The key is the unique identifier of the process definition in the XML, so its value is read from the id attribute in the XML:
<bpmn2:process id="invoice" ...
Id: The id is the database primary key and an artificial key normally combined out of the key, the version and a generated id (note that the ID may be shortened to fit into the database column, so there is no guarantee that the id is built this way).
It is possible to tag a process definition with a version tag attribute. This can be done by adding the camunda:versionTag extension attribute to the process:
<bpmn2:process camunda:versionTag="1.5-patch2" ..
ProcessDefinition will now provide a versionTag field which you can fetch:
ProcessDefinition pd = processEngine.getRepositoryService().createProcessDefinitionQuery() .processDefinitionKey("invoice") .processDefinitionVersion(1).singleResult(); pd.getVersionTag();
or to fetch a list of all deployed process definitions which contain the specified version:
List<ProcessDefinition> pdList = processEngine.getRepositoryService().createProcessDefinitionQuery() .versionTag("1.5-patch2") .list();
You can also use
versionTagLike to query for a range of versions:
List<ProcessDefinition> pdList = processEngine.getRepositoryService().createProcessDefinitionQuery() .versionTagLike("1.5-%") .list();
The following example shows how to start a process instance of the latest process definition for a version tag:
ProcessDefinition pd = processEngine.getRepositoryService().createProcessDefinitionQuery() .processDefinitionKey("invoice") .versionTag("1.5-patch2") .orderByVersion(). .desc() .listPage(0,1); processEngine.getRuntimeService().startProcessInstanceById(pd.getId());
The version tag is only for tagging and will neither influence the
The Process Definition
versionTag are separate properties. When querying with
ProcessDefinitionQuery#latestVersion(), the Process Definition with the largest
version number is located for
a given key. Adding a version tag filter to this query might provide an empty result if the latest Process Definition
doesn’t contain the queried version tag.
Process Instance Migration
By default, when a new process version is deployed, process instances running on previous versions are not affected. Process instance migration can be used to migrate process instances to a new version.