docs(bpmn): explain binding types for call activities, business rule …

…tasks, and user tasks (#4132)

docs/components/best-practices/modeling/choosing-the-resource-binding-type.md

@@ -0,0 +1,33 @@
+---
+title: Choosing the resource binding type
+tags:
+  - BPMN
+description: "Choose the resource binding type and understand the differences between 'latest' and 'deployment' binding for linked resources."
+---
+
+Camunda 8 offers version binding for linked processes, decisions, or forms. This allows you to deploy new versions without disrupting live processes, and prevents production outages.
+
+You can choose the binding type for the linked target resource for the following BPMN process elements:
+
+- [Call activities](/docs/components/modeler/bpmn/call-activities/call-activities.md#defining-the-called-process)
+- [Business rule tasks](/docs/components/modeler/bpmn/business-rule-tasks/business-rule-tasks.md#defining-a-called-decision) (if the DMN decision implementation is used)
+- [User tasks](/docs/components/modeler/bpmn/user-tasks/user-tasks.md#user-task-forms) (if a Camunda Form is linked)
+
+The binding type determines the version of the target resource used at runtime.
+
+For example, for a call activity this would be the version of the called process to be instantiated.
+
+## Supported binding types
+
+Camunda 8 supports the following binding types:
+
+| Type         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `latest`     | <p>Resolves to the **latest deployed version** of the target resource at the moment the process element is activated.</p><p><ul><li><p>This can lead to unexpected behavior if you deploy a new version of the target resource without ensuring backwards compatibility with every deployed process that depends on it.</p></li><li><p>Therefore, using `latest` might not be suited for production environments that require stability and a predictable behavior.</p></li></ul></p>                                                                                                                                                                                                                                                                                                                                                                           |
+| `deployment` | <p>Resolves to the specific version of the target resource that was **deployed together** with the currently running version of the process in the **same deployment**.</p><p><ul><li><p>This option ensures predictable behavior by tying the two versions together, and allows you to deploy future versions of the target resource without disrupting ongoing process instances.</p></li><li><p>This option is ideal for self-contained projects without external or shared dependencies.</p></li><li><p>To use the `deployment` binding option, create and deploy a [process application in Web Modeler](/docs/components/modeler/web-modeler/process-applications.md#deploy-and-run-a-process-application), or deploy multiple resources together via the [Zeebe API](/docs/apis-tools/zeebe-api/gateway-service.md#deployresource-rpc).</p></li></ul></p> |
+
+:::note
+
+If the binding type is not explicitly specified in your BPMN diagram, `latest` is used as the default.
+
+:::

docs/components/modeler/bpmn/business-rule-tasks/business-rule-tasks.md

@@ -42,6 +42,19 @@ e.g. `= "shipping_box_size_" + countryCode`). The expression is evaluated on act
 an incident at the business rule task is resolved) after input mappings have been applied. The expression must result in
 a `string`.
 
+The `bindingType` attribute determines which version of the called decision is evaluated:
+
+- `latest`: the latest deployed version at the moment the business rule task is activated.
+- `deployment`: the version that was deployed together with the currently running version of the process.
+
+To learn more about choosing binding types, see [Choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md).
+
+:::note
+
+If the `bindingType` attribute is not specified, `latest` is used as the default.
+
+:::
+
 A business rule task must define the process variable name of the decision result as
 `resultVariable`. The result of the decision is stored in this variable. The `resultVariable`
 is defined as a static value.
@@ -92,12 +105,12 @@ to transform the variables passed to the job worker, or to customize how the var
 
 ### XML representation
 
-A business rule task with a called decision:
+A business rule task with a called decision that uses `deployment` binding:
 
 ```xml
 <bpmn:businessRuleTask id="determine-box-size" name="Determine shipping box size">
   <bpmn:extensionElements>
-    <zeebe:calledDecision decisionId="shipping_box_size" resultVariable="boxSize" />
+    <zeebe:calledDecision decisionId="shipping_box_size" resultVariable="boxSize" bindingType="deployment" />
   </bpmn:extensionElements>
 </bpmn:businessRuleTask>
 ```

docs/components/modeler/bpmn/call-activities/call-activities.md

@@ -16,10 +16,21 @@ When the created process instance is completed, the call activity is left and th
 
 A call activity must define the BPMN process id of the called process as `processId`.
 
-The new instance of the defined process is created by its **latest version** at the point when the call activity is activated.
-
 Usually, the `processId` is defined as a [static value](/components/concepts/expressions.md#expressions-vs-static-values) (e.g. `shipping-process`), but it can also be defined as [expression](/components/concepts/expressions.md) (e.g. `= "shipping-" + tenantId`). The expression is evaluated on activating the call activity and must result in a `string`.
 
+The `bindingType` attribute determines which version of the called process is instantiated:
+
+- `latest`: the latest deployed version at the moment the call activity is activated.
+- `deployment`: the version that was deployed together with the currently running version of the calling process.
+
+To learn more about choosing binding types, see [Choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md).
+
+:::note
+
+If the `bindingType` attribute is not specified, `latest` is used as the default.
+
+:::
+
 ## Boundary events
 
 ![call-activity-boundary-event](assets/call-activities-boundary-events.png)
@@ -50,12 +61,12 @@ By disabling this attribute, variables existing at higher scopes are no longer c
 
 ### XML representation
 
-A call activity with static process id and propagation of all child variables turned on:
+A call activity with static process id, propagation of all child variables turned on, and `deployment` binding:
 
 ```xml
 <bpmn:callActivity id="Call_Activity" name="Call Process A">
   <bpmn:extensionElements>
-    <zeebe:calledElement processId="child-process-a" propagateAllChildVariables="true" />
+    <zeebe:calledElement processId="child-process-a" propagateAllChildVariables="true" bindingType="deployment" />
   </bpmn:extensionElements>
 </bpmn:callActivity>
 ```

docs/components/modeler/bpmn/user-tasks/user-tasks.md

@@ -106,7 +106,19 @@ Depending on your use case, two different types of form references can be used:
    Forms linked this way can be deployed together with the referencing process models.
    To link a user task to a Camunda Form, you have to specify the ID of the Camunda Form as the `formId` attribute
    of the task's `zeebe:formDefinition` extension element (see the [XML representation](#camunda-form-linked)).
-   Form ID references always refer to the latest deployed version of the Camunda Form.
+
+   The `bindingType` attribute determines which version of the linked form is used:
+
+   - `latest`: the latest deployed version at the moment the user task is activated.
+   - `deployment`: the version that was deployed together with the currently running version of the process.
+
+   To learn more about choosing binding types, see [Choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md).
+
+   :::note
+
+   If the `bindingType` attribute is not specified, `latest` is used as the default.
+
+   :::
 
    You can read more about Camunda Forms in the [Camunda Forms guide](/guides/utilizing-forms.md) or the [Camunda Forms reference](/components/modeler/forms/camunda-forms-reference.md)
    to explore all configuration options for form elements.
@@ -176,12 +188,12 @@ Zeebe user task-specific features are not available to those user tasks.
 
 #### Camunda Form
 
-A user task with a linked Camunda Form, an assignment definition, and a task schedule:
+A user task with a linked Camunda Form (that uses `deployment` binding), an assignment definition, and a task schedule:
 
 ```xml
 <bpmn:userTask id="configure" name="Configure">
   <bpmn:extensionElements>
-    <zeebe:formDefinition formId="configure-control-process" />
+    <zeebe:formDefinition formId="configure-control-process" bindingType="deployment" />
     <zeebe:assignmentDefinition assignee="= default_controller" candidateGroups="controllers, auditors" />
     <zeebe:taskSchedule dueDate="= task_finished_deadline" followUpDate="= now() + duration(&#34;P12D&#34;)" />
     <zeebe:userTask />

docs/guides/migrating-from-camunda-7/adjusting-bpmn-models.md

@@ -108,14 +108,18 @@ The following attributes/elements can be migrated:
   - `camunda:candidateUsers` to `zeebe:assignmentDefinition candidateUsers`
   - `camunda:formKey` to `zeebe:formDefinition formKey`, but Camunda 8 requires you to embed the form definition itself into the root element of your BPMN XML models, see [the user task documentation](/components/modeler/bpmn/user-tasks/user-tasks.md#user-task-forms).
   - `camunda:formRef` to `zeebe:formDefinition formId`
+  - `camunda:formRefBinding` to `zeebe:formDefinition bindingType`
+    :::note
+    Camunda 8 only supports the `deployment` and `latest` binding types for user task forms.
+    :::
 
 The following attributes/elements **cannot** yet be migrated:
 
 - Form handling:
   - `camunda:formHandlerClass`
   - `camunda:formData`
   - `camunda:formProperty`
-  - `camunda:formRefBinding` and `camunda:formRefVersion` (Camunda 8 always uses `latest` binding)
+  - `camunda:formRefVersion`
 - `camunda:taskListener`
 - `camunda:dueDate`
 - `camunda:followUpDate`
@@ -131,10 +135,14 @@ The following attributes/elements can be migrated:
 
 - `camunda:decisionRef` to `zeebe:calledDecision decisionId`
 - `camunda:resultVariable` to `zeebe:calledDecision resultVariable`
+- `camunda:decisionRefBinding` to `zeebe:calledDecision bindingType`
+  :::note
+  Camunda 8 only supports the `deployment` and `latest` binding types for business rule tasks.
+  :::
 
 The following attributes are **not** yet supported:
 
-- `camunda:decisionRefBinding`, `camunda:decisionRefVersion`, and `camunda:decisionRefVersionTag`(always use the latest version)
+- `camunda:decisionRefVersion` and `camunda:decisionRefVersionTag`
 - `camunda:mapDecisionResult` (no mapping happens)
 - `camunda:decisionRefTenantId`
 
@@ -146,15 +154,18 @@ A business rule task can also _behave like a service task_ to allow integration
 
 Call activities are generally supported in Zeebe. The following attributes/elements can be migrated:
 
-- `camunda:calledElement` will be converted into `zeebe:calledElement`
+- `camunda:calledElement` to `zeebe:calledElement processId`
+- `camunda:calledElementBinding` to `zeebe:calledElement bindingType`
+  :::note
+  Camunda 8 only supports the `deployment` and `latest` binding types for call activities.
+  :::
 - Data mapping
   - `camunda:in` to `zeebe:input`
   - `camunda:out` to `zeebe:output`
 
 The following attributes/elements **cannot** be migrated:
 
-- `camunda:calledElementBinding`: Currently Zeebe always assumes 'late' binding.
-- `camunda:calledElementVersionTag`: Zeebe does not know a version tag.
+- `camunda:calledElementVersion` and `camunda:calledElementVersionTag`
 - `camunda:variableMappingClass`: You cannot execute code to do variable mapping in Zeebe.
 - `camunda:variableMappingDelegateExpression`: You cannot execute code to do variable mapping in Zeebe.
 

optimize_sidebars.js

@@ -1367,6 +1367,10 @@ module.exports = {
               "Choosing the DMN hit policy",
               "components/best-practices/modeling/choosing-the-dmn-hit-policy/"
             ),
+            docsLink(
+              "Choosing the resource binding type",
+              "components/best-practices/modeling/choosing-the-resource-binding-type/"
+            ),
           ],
         },
 

sidebars.js

@@ -648,6 +648,7 @@ module.exports = {
             "components/best-practices/modeling/modeling-with-situation-patterns",
             "components/best-practices/modeling/building-flexibility-into-bpmn-models",
             "components/best-practices/modeling/choosing-the-dmn-hit-policy",
+            "components/best-practices/modeling/choosing-the-resource-binding-type",
           ],
           Operations: [
             "components/best-practices/operations/versioning-process-definitions",