docs: document "version tag" binding for linked resources

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

@@ -63,6 +63,23 @@ Camunda 8 supports the following binding types:
         </ul>
       </td>
     </tr>
+    <tr>
+      <td><code>versionTag</code></td>
+      <td>
+        <p>Resolves to the specific version of the target resource that is annotated with the given <strong>version tag</strong>.</p>
+        <ul>
+          <li><p>The version tag is a user-provided string (for example <code>1.2.0.Final</code>) that makes it easy to identify a certain version of a resource and track it across multiple deployment stages (e.g. dev, test, prod).</p></li>
+          <li><p>Using the <code>versionTag</code> binding option ensures that the right version of the target resource is always used, regardless of future deployments, by pinning the dependency to a specific version.</p></li>
+          <li><p>The option is ideal for managing external or shared dependencies.</p></li>
+          <li>
+            <p>
+              Be aware that you can deploy a new version of a resource with the same version tag as a previously deployed one.
+              In this case, the version tag reference will be updated and point to the latest deployed version.
+            </p>
+          </li>
+        </ul>
+      </td>
+    </tr>
   </tbody>
 </table>
 

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

@@ -46,13 +46,12 @@ The `bindingType` attribute determines which version of the called decision is e
 
 - `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.
+- `versionTag`: the latest deployed version that is annotated with the version tag specified in the `versionTag` attribute.
 
 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
@@ -105,12 +104,13 @@ 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 that uses `deployment` binding:
+A business rule task with a called decision that uses `versionTag` binding:
 
 ```xml
 <bpmn:businessRuleTask id="determine-box-size" name="Determine shipping box size">
   <bpmn:extensionElements>
-    <zeebe:calledDecision decisionId="shipping_box_size" bindingType="deployment"
+    <zeebe:calledDecision decisionId="shipping_box_size"
+                          bindingType="versionTag" versionTag="v1.0"
                           resultVariable="boxSize" />
   </bpmn:extensionElements>
 </bpmn:businessRuleTask>

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

@@ -22,13 +22,12 @@ The `bindingType` attribute determines which version of the called process is in
 
 - `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.
+- `versionTag`: the latest deployed version that is annotated with the version tag specified in the `versionTag` attribute.
 
 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
@@ -61,12 +60,13 @@ By disabling this attribute, variables existing at higher scopes are no longer c
 
 ### XML representation
 
-A call activity with static process id, propagation of all child variables turned on, and `deployment` binding:
+A call activity with static process id, propagation of all child variables turned on, and `versionTag` binding:
 
 ```xml
 <bpmn:callActivity id="Call_Activity" name="Call Process A">
   <bpmn:extensionElements>
-    <zeebe:calledElement processId="child-process-a" bindingType="deployment"
+    <zeebe:calledElement processId="child-process-a"
+                         bindingType="versionTag" versionTag="v1.0"
                          propagateAllChildVariables="true" />
   </bpmn:extensionElements>
 </bpmn:callActivity>

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

@@ -105,19 +105,18 @@ Depending on your use case, two different types of form references can be used:
 1. **Camunda Forms** provide a flexible way of linking a user task to a Camunda Form via the form ID.
    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)).
+   of the task's `zeebe:formDefinition` extension element (see the [XML representation](#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.
+   - `versionTag`: the latest deployed version that is annotated with the version tag specified in the `versionTag` attribute.
 
    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)
@@ -188,14 +187,17 @@ Zeebe user task-specific features are not available to those user tasks.
 
 #### Camunda Form
 
-A user task with a linked Camunda Form (that uses `deployment` binding), an assignment definition, and a task schedule:
+A user task with a linked Camunda Form (that uses `versionTag` binding), an assignment definition, and a task schedule:
 
 ```xml
 <bpmn:userTask id="configure" name="Configure">
   <bpmn:extensionElements>
-    <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:formDefinition formId="configure-control-process"
+                          bindingType="versionTag" versionTag="v1.0" />
+    <zeebe:assignmentDefinition assignee="= default_controller"
+                                candidateGroups="controllers, auditors" />
+    <zeebe:taskSchedule dueDate="= task_finished_deadline"
+                        followUpDate="= now() + duration(&#34;P12D&#34;)" />
     <zeebe:userTask />
   </bpmn:extensionElements>
 </bpmn:userTask>

docs/components/modeler/web-modeler/advanced-modeling/business-rule-task-linking.md

@@ -4,6 +4,8 @@ title: Business rule task linking
 description: Use one of the following approaches to link the DMN decision to be called by a business rule task.
 ---
 
+import PropertiesPanelImg from './img/brt_properties-panel.png'
+
 You can use one of the following approaches to link the DMN decision to be called by a [business rule task](/components/modeler/bpmn/business-rule-tasks/business-rule-tasks.md).
 
 ## Using the link button
@@ -24,7 +26,10 @@ For business rule tasks that are already linked, clicking on the link icon opens
 
 You may also enter the Decision ID directly in the **Called decision** section in the properties panel after selecting **DMN decision** for the **Implementation**.
 
-![overlay](img/brt_properties-panel.png)
+There you can also select a different **Binding** for the called decision (learn more about the different options in [Choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md)).
+If you select **version tag**, you need to enter the actual version tag to be used.
+
+<p><img src={PropertiesPanelImg} alt="called decision section in properties panel" style={{width: 430}} /></p>
 
 :::info
 Deploying a diagram does not automatically deploy linked diagrams. Ensure you deploy linked diagrams separately.

docs/components/modeler/web-modeler/advanced-modeling/call-activity-linking.md

@@ -4,6 +4,8 @@ title: Call activity linking
 description: Use one of the following approaches to link the process to be called by a call activity.
 ---
 
+import PropertiesPanelImg from './img/properties-panel.png'
+
 You can use one of the following approaches to link the process to be called by a [call activity](/components/modeler/bpmn/call-activities/call-activities.md).
 
 ## Using the link button
@@ -22,7 +24,10 @@ For call activities that are already linked, clicking on the link button opens a
 
 You may also enter the process ID directly in the **Called element** section in the properties panel.
 
-![overlay](img/properties-panel.png)
+There you can also select a different **Binding** for the called process (learn more about the different options in [Choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md)).
+If you select **version tag**, you need to enter the actual version tag to be used.
+
+<p><img src={PropertiesPanelImg} alt="called element section in properties panel" style={{width: 430}} /></p>
 
 :::info
 Deploying a diagram does not automatically deploy linked diagrams. Ensure you deploy linked diagrams separately.

docs/components/modeler/web-modeler/advanced-modeling/form-linking.md

@@ -6,6 +6,7 @@ description: Use one of the following approaches to link a form to a user task o
 
 import FormLinkOverlayImg from './img/utl_overlay.png';
 import FormLinkOverlayLinkedImg from './img/utl_linked.png';
+import PropertiesPanelImg from './img/utl_properties-panel.png';
 import IssueLinkedFormSolution01 from './img/linked_issue01.png';
 import IssueLinkedFormSolution02 from './img/linked_issue02.png';
 import IssueLinkedFormSolution03 from './img/linked_issue03.png';
@@ -24,27 +25,32 @@ By linking a Camunda Form to a start event, process instances can be started wit
 3. Click the **Link** button to complete the linking process.
    In the properties panel, the value **Camunda Form (linked)** is chosen for the **Type** property, and the form ID of the form you chose to link is automatically copied to the **Form ID** section.
 
-<img src={FormLinkOverlayImg} style={{width: 400}} alt="Linking a Camunda Form" />
+<p><img src={FormLinkOverlayImg} style={{width: 400}} alt="Linking a Camunda Form" /></p>
 
 For user tasks/start events that are already linked, clicking on the link button opens a dialog which shows a preview of the form the user task is linked to.
 It is possible to navigate to the linked form by clicking on it, or you can use the **Unlink** button to remove the link.
 
-<img src={FormLinkOverlayLinkedImg} style={{width: 400}} alt="Linked Camunda Form preview" />
+<p><img src={FormLinkOverlayLinkedImg} style={{width: 400}} alt="Linked Camunda Form preview" /></p>
 
 ## Using the properties panel
 
 Using the properties panel, you can connect a form to a user task/start event via the **Form** section by choosing between different types.
 
 ### Camunda Form (linked)
 
-Choosing **Camunda Form (linked)** as type and entering form ID directly yields the same result as [using the link button on the modeling canvas](#using-the-link-button).
+Choosing **Camunda Form (linked)** as type and entering the form ID directly yields the same result as [using the link button on the modeling canvas](#using-the-link-button).
 
-Using this type of linking is the recommended approach as it allows you to benefit from the form automatically being deployed along with the diagram.
+You can also select a different **Binding** for the linked form (learn more about the different options in [Choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md)).
+If you select **version tag**, you need to enter the actual version tag to be used.
+
+<p><img src={PropertiesPanelImg} style={{width: 430}} alt="form section in properties panel" /></p>
+
+Using a linked form is the recommended approach as it allows you to benefit from the form automatically being deployed along with the diagram.
 This means when deploying a BPMN diagram, Web Modeler will always deploy the latest version of all linked forms along with the diagram, so you do not have to manually re-link forms or [copy & paste JSON configuration](#camunda-form-embedded) when making changes.
 
 :::danger
 When deploying a diagram, Web Modeler will always deploy the latest version of all linked forms along with the diagram.
-This means that if you reference the same Form ID within multiple BPMN diagrams, all diagrams will always use the latest version of the form regardless of which version was used when the diagram was initially deployed.
+This means that if you reference the same Form ID within multiple BPMN diagrams, all diagrams will always use the latest version of the form regardless of which version was used when the diagram was initially deployed (unless you change the [binding type for a linked form](#camunda-form-linked)).
 :::
 
 :::info

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

@@ -28,6 +28,12 @@ The following attributes/elements **cannot** be migrated:
 - `camunda:jobPriority`: There is no way to prioritize jobs in Zeebe (yet).
 - `camunda:failedJobRetryTimeCycle`: You cannot yet configure the retry time cycle. Alternatively, you can [modify your code](/apis-tools/zeebe-api/gateway-service.md#input-failjobrequest) to use the `retryBackOff` timeout (in ms) for the next retry.
 
+### Processes
+
+The following attribute can be migrated:
+
+- `camunda:versionTag` to `bpmn:extensionElements > zeebe:versionTag value`
+
 ### Service tasks
 
 :::note
@@ -110,7 +116,7 @@ The following attributes/elements can be migrated:
   - `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.
+    Camunda 8 only supports the `latest`, `deployment`, and `versionTag` [binding types](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md) for user task forms.
     :::
 
 The following attributes/elements **cannot** yet be migrated:
@@ -137,12 +143,13 @@ The following attributes/elements can be migrated:
 - `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.
+  Camunda 8 only supports the `latest`, `deployment`, and `versionTag` [binding types](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md) for business rule tasks.
   :::
+- `camunda:decisionRefVersionTag` to `zeebe:calledDecision versionTag`
 
 The following attributes are **not** yet supported:
 
-- `camunda:decisionRefVersion` and `camunda:decisionRefVersionTag`
+- `camunda:decisionRefVersion`
 - `camunda:mapDecisionResult` (no mapping happens)
 - `camunda:decisionRefTenantId`
 
@@ -157,15 +164,16 @@ Call activities are generally supported in Zeebe. The following attributes/eleme
 - `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.
+  Camunda 8 only supports the `latest`, `deployment`, and `versionTag` [binding types](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md) for call activities.
   :::
+- `camunda:calledElementVersionTag` to `zeebe:calledElement versionTag`
 - Data mapping
   - `camunda:in` to `zeebe:input`
   - `camunda:out` to `zeebe:output`
 
 The following attributes/elements **cannot** be migrated:
 
-- `camunda:calledElementVersion` and `camunda:calledElementVersionTag`
+- `camunda:calledElementVersion`: Zeebe does not support the `version` binding type.
 - `camunda:variableMappingClass`: You cannot execute code to do variable mapping in Zeebe.
 - `camunda:variableMappingDelegateExpression`: You cannot execute code to do variable mapping in Zeebe.
 

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

@@ -16,13 +16,20 @@ To evaluate Camunda 7 DMN files in Camunda 8, change the following in the XML:
 Web Modeler will automatically update `modeler:executionPlatform` and `modeler:executionPlatformVersion` to the correct values when you upload a DMN file.
 :::
 
+### General considerations
+
 The following elements/attributes are **not** supported in Camunda 8:
 
-- `Version Tag`
 - `History Time to Live`
 - You cannot select the `Expression Language`, only FEEL is supported
 - The property `Input Variable` is removed. In FEEL, the input value can be accessed by using `?` if needed.
 
 Furthermore, legacy behavior can still be executed but the following should be kept in mind:
 
 - Remove data types `integer` + `long` + `double` in favor of `number` for inputs and outputs (in FEEL, there is only a number type represented as `BigDecimal`).
+
+### Decisions
+
+The following attribute can be migrated:
+
+- `camunda:versionTag` to `extensionElements > zeebe:versionTag value`

docs/guides/utilizing-forms.md

@@ -83,7 +83,7 @@ You can now monitor your instances in [Operate](../components/operate/operate-in
 
 :::info
 Linked Camunda Forms will automatically be deployed along with the diagram.
-As linked forms are always resolved to their latest version, make sure you don't accidentally deploy a diagram.
+As linked forms are resolved to their latest version (unless you change the [binding type](/components/modeler/web-modeler/advanced-modeling/form-linking.md#camunda-form-linked)), make sure you don't accidentally deploy a diagram.
 
 When deploying to a Camunda 8 cluster with a version lower than 8.4, forms linked to user tasks or none start events will be automatically embedded into the user task to guarantee backwards compatibility.
 Read more about the different ways to reference Camunda Forms in the [user task forms reference](/components/modeler/bpmn/user-tasks/user-tasks.md#user-task-forms).