diff --git a/docs/components/modeler/bpmn/ad-hoc/ad-hoc.md b/docs/components/modeler/bpmn/ad-hoc/ad-hoc.md new file mode 100644 index 0000000000..67883eccc3 --- /dev/null +++ b/docs/components/modeler/bpmn/ad-hoc/ad-hoc.md @@ -0,0 +1,75 @@ +--- +id: ad-hoc +title: "Ad-hoc" +description: "The ad-hoc marker is only available for embedded subprocesses, so called ad-hoc subprocesses." +--- + +The ad-hoc marker (**~** a tilde character) is only available +for [embedded subprocesses](../embedded-subprocesses/embedded-subprocesses.md), so called **ad-hoc subprocesses**. +Compared to regular subprocesses, it allows more flexibility for executing the inner elements. + +![A demo process with an ad-hoc subprocess. Some elements inside the subprocess are active.](assets/ad-hoc-subprocess.png) + +The inner elements of an ad-hoc subprocess are not connected to a start or end event. Each element can be executed +multiple times, in any order, or skipped. + +If elements depend on each other, the elements can be connected by a sequence flow to build a structured sequence +within the ad-hoc subprocess. + +When a process instance reaches an ad-hoc subprocess, it [activates the inner elements](#activate-an-element) and waits +for their completion. After the last element is completed, the process instance completes the ad-hoc subprocess and +takes the outgoing sequence flows. + +### Constraints + +An ad-hoc subprocess has the following constraints: + +- Must have at least one activity +- Must not have start events or end events +- Any intermediate catch event must have an outgoing sequence flow + +## Activate an element + +An ad-hoc subprocess can define an expression `activeElementsCollection` that should return a +[list](../../feel/language-guide/feel-data-types.md#list) of strings. Each string in the list should match to an id of +an inner element of the ad-hoc subprocess. Usually, the expression accesses a process instance variable that was +created before and holds the list of element ids. + +![A process with an ad-hoc subprocess that shows how a variable is used to active the inner elements.](assets/ad-hoc-subprocess-activation.png) + +When a process instance reaches an ad-hoc subprocess, it evaluates the expression `activeElementsCollection` and +activates all elements whose element ids are in the list. + +If the list is empty or the expression is not defined, no element is activated and the ad-hoc subprocess stays active. + +If the expression doesn't evaluate to a list of strings, or the list contains other values than inner element ids, the +process instance creates an incident. + +:::note +Currently, it is not possible to activate elements dynamically after the ad-hoc subprocess is activated, only on +entering the subprocess. +::: + +## Variable mappings + +An ad-hoc subprocess can define input and output +[variable mappings](../../../concepts/variables.md#inputoutput-variable-mappings). + +Input variable mappings are applied on activating the ad-hoc subprocess and before evaluating the expression +`activeElementsCollection`. They can be used to create local variables for the ad-hoc subprocess. + +Output variable mappings are applied on completing the ad-hoc subprocess. They can be used to propagate local variables +from the ad-hoc subprocess into the process instance. By default, no local variables are propagated. + +## Additional resources + +### XML representation + +```xml + + + + + ... more contained elements ... + +``` diff --git a/docs/components/modeler/bpmn/ad-hoc/assets/ad-hoc-subprocess-activation.png b/docs/components/modeler/bpmn/ad-hoc/assets/ad-hoc-subprocess-activation.png new file mode 100644 index 0000000000..104d5e30d1 Binary files /dev/null and b/docs/components/modeler/bpmn/ad-hoc/assets/ad-hoc-subprocess-activation.png differ diff --git a/docs/components/modeler/bpmn/ad-hoc/assets/ad-hoc-subprocess.png b/docs/components/modeler/bpmn/ad-hoc/assets/ad-hoc-subprocess.png new file mode 100644 index 0000000000..ec266ccc75 Binary files /dev/null and b/docs/components/modeler/bpmn/ad-hoc/assets/ad-hoc-subprocess.png differ diff --git a/docs/components/modeler/bpmn/assets/bpmn-symbols/ad-hoc.svg b/docs/components/modeler/bpmn/assets/bpmn-symbols/ad-hoc.svg new file mode 100644 index 0000000000..e29215cfd1 --- /dev/null +++ b/docs/components/modeler/bpmn/assets/bpmn-symbols/ad-hoc.svg @@ -0,0 +1,14 @@ + + + + + Ad-Hoc + + \ No newline at end of file diff --git a/docs/components/modeler/bpmn/bpmn-coverage.md b/docs/components/modeler/bpmn/bpmn-coverage.md index c96e34cd92..183794373c 100644 --- a/docs/components/modeler/bpmn/bpmn-coverage.md +++ b/docs/components/modeler/bpmn/bpmn-coverage.md @@ -122,6 +122,7 @@ import MultiInstanceParallelSvg from './assets/bpmn-symbols/multi-instance-paral import MultiInstanceSequentialSvg from './assets/bpmn-symbols/multi-instance-sequential.svg' import LoopSvg from './assets/bpmn-symbols/loop.svg' import CompensationSvg from './assets/bpmn-symbols/compensation.svg' +import AdHocSvg from './assets/bpmn-symbols/ad-hoc.svg'
@@ -136,6 +137,9 @@ import CompensationSvg from './assets/bpmn-symbols/compensation.svg' + + +
## Data diff --git a/docs/components/modeler/bpmn/markers.md b/docs/components/modeler/bpmn/markers.md index 2a08cc4d77..816532b2ee 100644 --- a/docs/components/modeler/bpmn/markers.md +++ b/docs/components/modeler/bpmn/markers.md @@ -14,3 +14,4 @@ Currently supported markers: - [Multi-instance](multi-instance/multi-instance.md) - [Compensation](compensation-handler/compensation-handler.md) +- [Ad-hoc](ad-hoc/ad-hoc.md) diff --git a/sidebars.js b/sidebars.js index 486e440a9d..982d6130b1 100644 --- a/sidebars.js +++ b/sidebars.js @@ -289,6 +289,7 @@ module.exports = { "components/modeler/bpmn/markers", "components/modeler/bpmn/multi-instance/multi-instance", "components/modeler/bpmn/compensation-handler/compensation-handler", + "components/modeler/bpmn/ad-hoc/ad-hoc", ], }, ],