docs: document "version tag" binding for call activities, business ru…

…le tasks, and user tasks

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

@@ -63,6 +63,20 @@ 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 custom 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 <code>versionTag</code> binding is ideal for shared ore external dependencies you would like to pin to a specific version.</p></li>
+          <li>
+            <p>Be aware that deploying a new version of a resource with an existing version tag overrides the version tag.
+            That means that always the latest deployed resource version with a given version tag will be used in case of <code>versionTag</code> binding.</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/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`