Skip to content

Commit

Permalink
docs: document "version tag" binding for linked resources (#4248)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jfriedenstab
jfriedenstab authored Sep 6, 2024
1 parent 73febd3 commit ccca3bd
Show file tree
Hide file tree
Showing 14 changed files with 160 additions and 33 deletions.
31 changes: 31 additions & 0 deletions docs/components/best-practices/modeling/choosing-the-resource-binding-type.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,37 @@ 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).
You can set the version tag for a BPMN process, DMN decision, or Form in the Modeler's properties panel.
</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>
</ul>
<p><strong>Caution:</strong></p>
<ul>
<li>
<p>
If the target resource ID and version tag pair are not deployed, the process instance will have an incident.
To avoid this situation, ensure the version tag defined in the call activity, business rule task, or user task matches the version tag in the dependent resource.
</p>
</li>
<li>
<p>
Be aware that you can deploy a new version of a resource with an already existing version tag.
In this case, the version tag reference will be updated and point to the latest deployed version.
</p>
</li>
</ul>
</td>
</tr>
</tbody>
</table>

Expand Down
27 changes: 24 additions & 3 deletions docs/components/modeler/bpmn/business-rule-tasks/business-rule-tasks.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -105,7 +104,17 @@ 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 does not specify the binding type (`latest` is used implicitly):

```xml
<bpmn:businessRuleTask id="determine-box-size" name="Determine shipping box size">
<bpmn:extensionElements>
<zeebe:calledDecision decisionId="shipping_box_size" resultVariable="boxSize" />
</bpmn:extensionElements>
</bpmn:businessRuleTask>
```

A business rule task with a called decision that uses the `deployment` binding type:

```xml
<bpmn:businessRuleTask id="determine-box-size" name="Determine shipping box size">
Expand All @@ -116,6 +125,18 @@ A business rule task with a called decision that uses `deployment` binding:
</bpmn:businessRuleTask>
```

A business rule task with a called decision that uses the `versionTag` binding type:

```xml
<bpmn:businessRuleTask id="determine-box-size" name="Determine shipping box size">
<bpmn:extensionElements>
<zeebe:calledDecision decisionId="shipping_box_size"
bindingType="versionTag" versionTag="v1.0"
resultVariable="boxSize" />
</bpmn:extensionElements>
</bpmn:businessRuleTask>
```

A business rule task with a job worker implementation and a custom header:

```xml
Expand Down
29 changes: 24 additions & 5 deletions docs/components/modeler/bpmn/call-activities/call-activities.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -61,13 +60,33 @@ 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 no explicit binding type (`latest` is used implicitly):

```xml
<bpmn:callActivity id="Call_Activity" name="Call Process A">
<bpmn:extensionElements>
<zeebe:calledElement processId="child-process-a" propagateAllChildVariables="true" />
</bpmn:extensionElements>
</bpmn:callActivity>
```

A call activity with the `deployment` binding type:

```xml
<bpmn:callActivity id="Call_Activity" name="Call Process A">
<bpmn:extensionElements>
<zeebe:calledElement processId="child-process-a" bindingType="deployment" />
</bpmn:extensionElements>
</bpmn:callActivity>
```

A call activity with the `versionTag` binding type:

```xml
<bpmn:callActivity id="Call_Activity" name="Call Process A">
<bpmn:extensionElements>
<zeebe:calledElement processId="child-process-a" bindingType="deployment"
propagateAllChildVariables="true" />
<zeebe:calledElement processId="child-process-a"
bindingType="versionTag" versionTag="v1.0" />
</bpmn:extensionElements>
</bpmn:callActivity>
```
Expand Down
36 changes: 30 additions & 6 deletions docs/components/modeler/bpmn/user-tasks/user-tasks.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -117,19 +117,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)
Expand Down Expand Up @@ -200,14 +199,39 @@ 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 does not specify the binding type (`latest` is used implicitly) as well as an assignment definition and a task schedule:

```xml
<bpmn:userTask id="configure" name="Configure">
<bpmn:extensionElements>
<zeebe:formDefinition formId="configure-control-process" />
<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>
```

A user task with a linked Camunda Form that uses the `deployment` binding type:

```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:userTask />
</bpmn:extensionElements>
</bpmn:userTask>
```

A user task with a linked Camunda Form that uses the `versionTag` binding type:

```xml
<bpmn:userTask id="configure" name="Configure">
<bpmn:extensionElements>
<zeebe:formDefinition formId="configure-control-process"
bindingType="versionTag" versionTag="v1.0" />
<zeebe:userTask />
</bpmn:extensionElements>
</bpmn:userTask>
Expand Down
13 changes: 9 additions & 4 deletions .../components/modeler/web-modeler/advanced-modeling/business-rule-task-linking.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,13 @@ 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.
---

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).
import PropertiesPanelImg from './img/brt_properties-panel.png'

You can use either 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

1. Select a business rule task from the canvas and a link icon will appear at the bottom right.
1. Select a business rule task from the canvas. A link icon appears at the bottom right.
2. Click the link icon and choose any decision from the same project.
3. Click **Link** to complete the linking process. In the properties panel, the value **DMN decision** is chosen for the **Implementation** property, and the Decision ID of the decision you chose to link is automatically copied to the **Called decision** section.

Expand All @@ -22,9 +24,12 @@ For business rule tasks that are already linked, clicking on the link icon opens

## Using the properties panel

You may also enter the Decision ID directly in the **Called decision** section in the properties panel after selecting **DMN decision** for the **Implementation**.
You can also enter the Decision ID directly in the **Called decision** section in the properties panel after selecting **DMN decision** for the **Implementation**.

- **Binding**: You can also select a different Binding for the called decision. See [Choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md).
- **Version tag**: If you select **version tag** for the Binding, you must enter the actual version tag to use.

![overlay](img/brt_properties-panel.png)
<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.
Expand Down
11 changes: 8 additions & 3 deletions docs/components/modeler/web-modeler/advanced-modeling/call-activity-linking.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,13 @@ 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

1. Select a call activity task from the canvas and a link button will appear at the bottom right.
1. Select a call activity task from the canvas. A link button appears at the bottom right.
2. Click on the button and choose any diagram from the same project.
3. Click the **Link** button to complete the linking process. The process ID of the diagram you chose to link is automatically copied to the **Called element** section in the properties panel.

Expand All @@ -20,9 +22,12 @@ For call activities that are already linked, clicking on the link button opens a

## Using the properties panel

You may also enter the process ID directly in the **Called element** section in the properties panel.
You can also enter the process ID directly in the **Called element** section in the properties panel.

- **Binding**: You can also select a different Binding for the called decision. See [Choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md).
- **Version tag**: If you select **version tag** for the Binding, you must enter the actual version tag to use.

![overlay](img/properties-panel.png)
<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.
Expand Down
16 changes: 11 additions & 5 deletions docs/components/modeler/web-modeler/advanced-modeling/form-linking.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -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 the type and entering the form ID directly, produces 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.
- **Binding**: You can also select a different Binding for the linked form. See [Choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md).
- **Version tag**: If you select **version tag** for the Binding, you must enter the actual version tag to use.

<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 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
Expand Down
Binary file modified docs/components/modeler/web-modeler/advanced-modeling/img/brt_properties-panel.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/components/modeler/web-modeler/advanced-modeling/img/properties-panel.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/components/modeler/web-modeler/advanced-modeling/img/utl_properties-panel.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions docs/components/modeler/web-modeler/run-or-publish-your-process.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ To deploy, click **Deploy** in the upper right corner of the modeling screen:

- Make sure your process is free of errors, otherwise it can't be deployed. Use the [problems panel to detect and fix errors](./fix-problems-in-your-diagram.md).
- Make sure all dependent files are deployed first, such as DMN diagrams, forms, or called processes. You can use the [link tool](./advanced-modeling/call-activity-linking.md) to drill-down into linked resources and deploy them.
If you are using [`versionTag` binding](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md) for a linked resource, make sure it is deployed with the correct version tag.
:::tip
Consider using a [process application](process-applications.md) that allows you to deploy a process and all dependent files together in a single bundle.
:::
Expand Down
Loading

0 comments on commit ccca3bd

Please sign in to comment.