From 8d1058143fa5a54cfad937adb298aff377d5509a Mon Sep 17 00:00:00 2001 From: Jan Friedenstab <8794084+jfriedenstab@users.noreply.github.com> Date: Fri, 9 Aug 2024 18:40:48 +0200 Subject: [PATCH] docs(bpmn): explain binding types for call activities, business rule tasks, and user tasks (#4132) --- .../choosing-the-resource-binding-type.md | 33 +++++++++++++++++++ .../business-rule-tasks.md | 17 ++++++++-- .../bpmn/call-activities/call-activities.md | 19 ++++++++--- .../modeler/bpmn/user-tasks/user-tasks.md | 18 ++++++++-- .../adjusting-bpmn-models.md | 21 +++++++++--- optimize_sidebars.js | 4 +++ sidebars.js | 1 + 7 files changed, 99 insertions(+), 14 deletions(-) create mode 100644 docs/components/best-practices/modeling/choosing-the-resource-binding-type.md diff --git a/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md b/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md new file mode 100644 index 0000000000..cce41816b8 --- /dev/null +++ b/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` |

Resolves to the **latest deployed version** of the target resource at the moment the process element is activated.

| +| `deployment` |

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**.

| + +:::note + +If the binding type is not explicitly specified in your BPMN diagram, `latest` is used as the default. + +::: diff --git a/docs/components/modeler/bpmn/business-rule-tasks/business-rule-tasks.md b/docs/components/modeler/bpmn/business-rule-tasks/business-rule-tasks.md index e593128e0f..ae2dd3409e 100644 --- a/docs/components/modeler/bpmn/business-rule-tasks/business-rule-tasks.md +++ b/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 - + ``` diff --git a/docs/components/modeler/bpmn/call-activities/call-activities.md b/docs/components/modeler/bpmn/call-activities/call-activities.md index e3c522b341..d592b3086f 100644 --- a/docs/components/modeler/bpmn/call-activities/call-activities.md +++ b/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 - + ``` diff --git a/docs/components/modeler/bpmn/user-tasks/user-tasks.md b/docs/components/modeler/bpmn/user-tasks/user-tasks.md index 8501d81ed1..0d36555459 100644 --- a/docs/components/modeler/bpmn/user-tasks/user-tasks.md +++ b/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 - + diff --git a/docs/guides/migrating-from-camunda-7/adjusting-bpmn-models.md b/docs/guides/migrating-from-camunda-7/adjusting-bpmn-models.md index ecbb0e25ca..dbf4fad9c4 100644 --- a/docs/guides/migrating-from-camunda-7/adjusting-bpmn-models.md +++ b/docs/guides/migrating-from-camunda-7/adjusting-bpmn-models.md @@ -108,6 +108,10 @@ 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: @@ -115,7 +119,7 @@ The following attributes/elements **cannot** yet be migrated: - `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. diff --git a/optimize_sidebars.js b/optimize_sidebars.js index 37d8adea25..dee025895d 100644 --- a/optimize_sidebars.js +++ b/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/" + ), ], }, diff --git a/sidebars.js b/sidebars.js index 7b29eb8b62..9921cce87b 100644 --- a/sidebars.js +++ b/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",