API for starting a process has some terminology confusion

Camunda 7 Topics Discussion & Questions
1

I would like to start a process using the API [1]. But I am confused about the terminology used in the Javadoc [1] regarding

startProcessInstanceByKey(String processDefinitionKey)

As far as I know a process definition has a processDefnitionName and a processDefnitionKey whereby the processDefnitionKey equals to the processDefinitinId. I can see from the cockpit deployments view that the column processDefnitionKey has the value of the processDefinitinId. But the API also has a method for starting a processes by Id [2]. So what is the processDefinitionKey when the Id is the Id and the Key is the Id also?

[1] https://docs.camunda.org/javadoc/camunda-bpm-platform/7.5/org/camunda/bpm/engine/RuntimeService.html#createProcessInstanceByKey(java.lang.String)
[2] https://docs.camunda.org/javadoc/camunda-bpm-platform/7.5/org/camunda/bpm/engine/RuntimeService.html#startProcessInstanceById(java.lang.String)

2

Hi,

The main difference here is when you redeploy a process. The process key is the unique name you give the process, however it is not unique across multiple deployments (eg versions) of the same process app.

When you deploy a process app, behind the scenes the engine allocates a unique Id to the process definition. Thus with multiple deployments with slight changes to the process definition, you will have one process definition key which maps to many process definition Ids.

Thus, when you start a process instance, conceptually the engine will always start an instance based on process definition Id. Hence if you start a process and you give the API the process definition Id, the engine just starts a process instance from that definition. If you start a process instance and you give the API the process definition key, then by default, the engine will look up the most recent deployment associated with the process definition and thus translate the process definition key to the process definition Id associated with the most recent deployment and start a process instance based on that process definition Id.

A good information model to keep in mind, reading one to many, left to right;

Process Definition Key: (On deployment ->) Process Definition Id: (On start process ->) Process Instance Id

Another way to think about it is, starting by process key will typically start the latest version. Start by process Id will start a particular version. This can be useful in 24*7 environments where I may want to pre-deploy a new version but not cutover immediately, eg large clusters…

Regards

Rob

3

The model to keep in mind is great, thanks!

When I understand this correctly the process definition Id does not get specified by the modeler but it gets derived from the process definition key and the version of the process definition during deployment (runtime).

It results in two additional questions:

  1. Why is the input-textfield within the modeler labeled with “Id” instead of “Key” ?
  2. How to build the argument processDefinitionId for a specific version of a process when using the method startProcessInstanceById()? Assuming that the process definition key is “myProcessKey” and there are two versions deployed. How to start a process from version 1? Does the argument have to include the version in some way i.e. “myProcessKey:1”?
1 Like
4

1 agree…

2 have a look at the rest Api documentation under the process definition section… There is an Api where given a key, can return definition ids based on criteria…

5

Hi @Mathias_S , @Webcyberrob,

  1. The modeler uses id as description because it is really the id attribute of the process in the xml, which is then called processDefinitionKey inside the process engine. It cannot be used inside the process engine as id, because it isn’t unique enough to identify a single process definition. Therefore the process engine generates a unique id for itself and uses that one.
  2. You can use a Process Definition Query (processEngine.getRepositoryService().createProcessDefinitionQuery()) and specify various criterias to get the process definition(s) you want. See here in the documentation for an detailed explanation.

Cheers,
Christian

1 Like
6

Alright, Thanks!

Now I got the relation between process key and Id. The meaning of the “process Id” depends on the context. So, in the context of the BPMN XML the Id “identifies” the process from a non-technical point of view which does not take versioning into account. That is why the engine uses the terminology processDefnitionKey for the id attribute of the BPMN XML. And in the context of the process engine the processDefinitinId is an artificial key combined out of the key, the version and a generated id.