Situation

In heterogenous camunda clusters not all of the deployed process engines might contain the same process applications; some process engines may be unable to execute certain process definitions because e. g. delegate code is not shared in the database.

Problem

Each process engine in a camunda cluster queries the database for available jobs and tries to acquire and execute them; in heterogenous clusters the process instances themselves are stored in the database and therefore available to all process engines. However, delegate code contained in process applications will not generally be available to all process engines and in this case you will need to prevent process engines from acquiring jobs which they cannot execute.

Solution

The parameter “deployment-aware” can be set to true in the camunda process engine configuration; this instructs the engine to only execute jobs for process instances it knows about.

• if deployment-aware=false, a process engine may acquire any available job
• if deployment-aware=true, a process engine acquires only jobs from a deployment which is registered with the process engine (it need not be created by the process engine, but can also be recognized als “already existing”).

a more detailed definition of “registered” is given here: https://forum.camunda.org/t/deployment-aware-job-executor/7572

How registration happens:
Whenever a deployment is made via API
Whenever a process application is (re-)deployed, it registers all deployments it makes and resumes
Manual registration via ManagementService#registerDeploymentForJobExecutor
Registrations are not persisted
Please note: outdated deployments from a previous version of a process application are also not considered registered.

Scenarios

Let’s think about a few scenarios:

1. Homogenous cluster

All process engines share a common set of process applications which of course share the same deployments. For job execution, the setting of deployment-aware does not matter since all engines recognize the same deployments and take their jobs from them.

You might want to set deployment-aware=false so the process engines will pick up jobs from out-of-date deployments and (probably) still be able to execute them, assuming that the delegates are still present and usable.

2. Heterogenous cluster

 not all process engines run the same set of process applications; you need to set deployment-aware=true for all of them since they can not execute each others delegates. multiple process engines running the same process application(s) will still execute the same jobs because they will recognize the deployments.

3. REST

You deploy process definitions outside of a process engine, for example via REST API. In this case you need to set deployment-aware=false, otherwise your process engine(s) will never pick up jobs from these deployments.

Mixed scenarios where some process engines know all process applications while some know only a subset may be feasible, but were not explored further.

Process Design

When designing a process for a deployment-aware setup, you need to be aware of which process engines might start processes and complete user tasks; that same process engine will also try to execute subsequent service tasks. In many cases, you will have transaction boundaries at the end of the user task and at the process start event anyway; this will create a job which will then be acquired by a suitable process engine.

Further findings

If one process engine is set to deployment-aware=false, picks up an unsuitable job and fails: the job might be acquired by the “right” process application on retry.

No difference was observed in behaviour between embedded process engines and shared process engine in wildfly

The camunda docker images that were used are deployment-aware by default

If you want to separate different process applications cleanly, different IDs for the BPMN processes are sufficient; identical delegate names seem to be no problem.

Fun fact: as long as delegates with matching names are present, we can even execute jobs from foreign process.

Photo by Clark Tibbs on Unsplash