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:

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 startProcessInstanceById:

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>

or

<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 startProcessInstanceByKey).
• 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).

Version Tag

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" ..

The 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")
    .latest()
    .singleResult();

processEngine.getRuntimeService().startProcessInstanceById(pd.getId());

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.