I can read how to use an ad-hoc subprocess

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, allowing more flexibility while executing inner elements."
+---
+
+The ad-hoc marker (represented by a **~** tilde character) is only available
+for [embedded subprocesses](../embedded-subprocesses/embedded-subprocesses.md), and are therefore called **ad-hoc subprocesses**.
+Compared to regular subprocesses, ad-hoc subprocesses allow more flexibility for executing 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 remains 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
+<bpmn:adHocSubProcess id="ad-hoc-subprocess" name="Ad-hoc subprocess">
+  <bpmn:extensionElements>
+    <zeebe:adHoc activeElementsCollection="=activeElements" />
+  </bpmn:extensionElements>
+  ... more contained elements ...
+</bpmn:adHocSubProcess>
+```

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'
 
 <div className="bpmn-symbol-container">
     <a href="../multi-instance/">
@@ -136,6 +137,9 @@ import CompensationSvg from './assets/bpmn-symbols/compensation.svg'
     <a href="../compensation-handler/">
         <CompensationSvg className="implemented" />
     </a>
+    <a href="../ad-hoc/">
+        <AdHocSvg className="implemented" />
+    </a>
 </div>
 
 ## Data

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)

media-pre-src/docs/components/modeler/bpmn/ad-hoc/ad-hoc-subprocess-activate.bpmn

@@ -0,0 +1,135 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" xmlns:di="http://www.omg.org/spec/DD/20100524/DI" xmlns:modeler="http://camunda.org/schema/modeler/1.0" id="Definitions_1r7woa3" targetNamespace="http://bpmn.io/schema/bpmn" exporter="Camunda Modeler" exporterVersion="5.29.0" modeler:executionPlatform="Camunda Cloud" modeler:executionPlatformVersion="8.6.0">
+  <bpmn:process id="ad-hoc-subprocess-demo" isExecutable="true">
+    <bpmn:startEvent id="StartEvent_1">
+      <bpmn:outgoing>Flow_0ofj339</bpmn:outgoing>
+    </bpmn:startEvent>
+    <bpmn:sequenceFlow id="Flow_0ofj339" sourceRef="StartEvent_1" targetRef="Activity_1jadqka" />
+    <bpmn:userTask id="Activity_1jadqka" name="Decide next actions">
+      <bpmn:extensionElements>
+        <zeebe:userTask />
+      </bpmn:extensionElements>
+      <bpmn:incoming>Flow_0ofj339</bpmn:incoming>
+      <bpmn:outgoing>Flow_0n50uei</bpmn:outgoing>
+      <bpmn:dataOutputAssociation id="DataOutputAssociation_0ygd3gi">
+        <bpmn:targetRef>DataObjectReference_1fwsvm3</bpmn:targetRef>
+      </bpmn:dataOutputAssociation>
+    </bpmn:userTask>
+    <bpmn:adHocSubProcess id="Activity_0h1xev6" name="Ad-hoc subprocess">
+      <bpmn:extensionElements />
+      <bpmn:incoming>Flow_0n50uei</bpmn:incoming>
+      <bpmn:outgoing>Flow_0m5piby</bpmn:outgoing>
+      <bpmn:property id="Property_0acrrah" name="__targetRef_placeholder" />
+      <bpmn:dataInputAssociation id="DataInputAssociation_1sbvbx6">
+        <bpmn:sourceRef>DataObjectReference_1fwsvm3</bpmn:sourceRef>
+        <bpmn:targetRef>Property_0acrrah</bpmn:targetRef>
+      </bpmn:dataInputAssociation>
+      <bpmn:serviceTask id="task_a" name="task_a">
+        <bpmn:extensionElements>
+          <zeebe:taskDefinition type="task_a" />
+        </bpmn:extensionElements>
+      </bpmn:serviceTask>
+      <bpmn:serviceTask id="task_b" name="task_b">
+        <bpmn:extensionElements>
+          <zeebe:taskDefinition type="task_b" />
+        </bpmn:extensionElements>
+      </bpmn:serviceTask>
+      <bpmn:serviceTask id="task_c" name="task_c">
+        <bpmn:extensionElements>
+          <zeebe:taskDefinition type="task_c" />
+        </bpmn:extensionElements>
+        <bpmn:outgoing>Flow_07gdlen</bpmn:outgoing>
+      </bpmn:serviceTask>
+      <bpmn:sequenceFlow id="Flow_07gdlen" sourceRef="task_c" targetRef="task_d" />
+      <bpmn:serviceTask id="task_d" name="task_d">
+        <bpmn:extensionElements>
+          <zeebe:taskDefinition type="task_d" />
+        </bpmn:extensionElements>
+        <bpmn:incoming>Flow_07gdlen</bpmn:incoming>
+      </bpmn:serviceTask>
+    </bpmn:adHocSubProcess>
+    <bpmn:sequenceFlow id="Flow_0n50uei" sourceRef="Activity_1jadqka" targetRef="Activity_0h1xev6" />
+    <bpmn:endEvent id="Event_0gs60dx">
+      <bpmn:incoming>Flow_0m5piby</bpmn:incoming>
+    </bpmn:endEvent>
+    <bpmn:sequenceFlow id="Flow_0m5piby" sourceRef="Activity_0h1xev6" targetRef="Event_0gs60dx" />
+    <bpmn:dataObjectReference id="DataObjectReference_1fwsvm3" name="activeElements:  [&#34;task_a&#34;,&#34;task_c&#34;]" dataObjectRef="DataObject_0ddpl3z" />
+    <bpmn:dataObject id="DataObject_0ddpl3z" />
+    <bpmn:textAnnotation id="TextAnnotation_1ami9k6">
+      <bpmn:text>activeElementsCollection: = activeElements</bpmn:text>
+    </bpmn:textAnnotation>
+    <bpmn:association id="Association_19hzeo2" associationDirection="None" sourceRef="Activity_0h1xev6" targetRef="TextAnnotation_1ami9k6" />
+  </bpmn:process>
+  <bpmndi:BPMNDiagram id="BPMNDiagram_1">
+    <bpmndi:BPMNPlane id="BPMNPlane_1" bpmnElement="ad-hoc-subprocess-demo">
+      <bpmndi:BPMNShape id="StartEvent_1_di" bpmnElement="StartEvent_1">
+        <dc:Bounds x="182" y="162" width="36" height="36" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="Activity_0wclalc_di" bpmnElement="Activity_1jadqka">
+        <dc:Bounds x="270" y="140" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="DataObjectReference_1fwsvm3_di" bpmnElement="DataObjectReference_1fwsvm3">
+        <dc:Bounds x="300" y="345" width="36" height="50" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="275" y="402" width="89" height="27" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="Activity_0kz19j1_di" bpmnElement="Activity_0h1xev6" isExpanded="true">
+        <dc:Bounds x="420" y="60" width="320" height="270" />
+        <bpmndi:BPMNLabel />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="Activity_1o2ugjf_di" bpmnElement="task_a">
+        <dc:Bounds x="450" y="100" width="100" height="80" />
+        <bpmndi:BPMNLabel />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_1tj764q" bpmnElement="task_b">
+        <dc:Bounds x="600" y="100" width="100" height="80" />
+        <bpmndi:BPMNLabel />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_1lv5cv3" bpmnElement="task_c">
+        <dc:Bounds x="450" y="210" width="100" height="80" />
+        <bpmndi:BPMNLabel />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="Activity_1hwuyjy_di" bpmnElement="task_d">
+        <dc:Bounds x="600" y="210" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNEdge id="Flow_07gdlen_di" bpmnElement="Flow_07gdlen">
+        <di:waypoint x="550" y="250" />
+        <di:waypoint x="600" y="250" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNShape id="Event_0gs60dx_di" bpmnElement="Event_0gs60dx">
+        <dc:Bounds x="792" y="162" width="36" height="36" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNEdge id="Association_19hzeo2_di" bpmnElement="Association_19hzeo2">
+        <di:waypoint x="610" y="330" />
+        <di:waypoint x="610" y="371" />
+        <di:waypoint x="650" y="371" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="Flow_0ofj339_di" bpmnElement="Flow_0ofj339">
+        <di:waypoint x="218" y="180" />
+        <di:waypoint x="270" y="180" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="Flow_0n50uei_di" bpmnElement="Flow_0n50uei">
+        <di:waypoint x="370" y="180" />
+        <di:waypoint x="420" y="180" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="Flow_0m5piby_di" bpmnElement="Flow_0m5piby">
+        <di:waypoint x="740" y="180" />
+        <di:waypoint x="792" y="180" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="DataOutputAssociation_0ygd3gi_di" bpmnElement="DataOutputAssociation_0ygd3gi">
+        <di:waypoint x="320" y="220" />
+        <di:waypoint x="320" y="345" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="DataInputAssociation_1sbvbx6_di" bpmnElement="DataInputAssociation_1sbvbx6">
+        <di:waypoint x="336" y="370" />
+        <di:waypoint x="580" y="370" />
+        <di:waypoint x="580" y="330" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNShape id="TextAnnotation_1ami9k6_di" bpmnElement="TextAnnotation_1ami9k6">
+        <dc:Bounds x="650" y="350" width="160" height="41" />
+        <bpmndi:BPMNLabel />
+      </bpmndi:BPMNShape>
+    </bpmndi:BPMNPlane>
+  </bpmndi:BPMNDiagram>
+</bpmn:definitions>

media-pre-src/docs/components/modeler/bpmn/ad-hoc/ad-hoc-subprocess-demo.bpmn

@@ -0,0 +1,99 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" xmlns:di="http://www.omg.org/spec/DD/20100524/DI" xmlns:modeler="http://camunda.org/schema/modeler/1.0" id="Definitions_1r7woa3" targetNamespace="http://bpmn.io/schema/bpmn" exporter="Camunda Modeler" exporterVersion="5.29.0" modeler:executionPlatform="Camunda Cloud" modeler:executionPlatformVersion="8.6.0">
+  <bpmn:process id="ad-hoc-subprocess-demo" isExecutable="true">
+    <bpmn:startEvent id="StartEvent_1">
+      <bpmn:outgoing>Flow_0ofj339</bpmn:outgoing>
+    </bpmn:startEvent>
+    <bpmn:sequenceFlow id="Flow_0ofj339" sourceRef="StartEvent_1" targetRef="Activity_1jadqka" />
+    <bpmn:userTask id="Activity_1jadqka" name="Decide next actions">
+      <bpmn:extensionElements>
+        <zeebe:userTask />
+      </bpmn:extensionElements>
+      <bpmn:incoming>Flow_0ofj339</bpmn:incoming>
+      <bpmn:outgoing>Flow_0n50uei</bpmn:outgoing>
+    </bpmn:userTask>
+    <bpmn:adHocSubProcess id="Activity_0h1xev6" name="Ad-hoc subprocess">
+      <bpmn:extensionElements>
+        <zeebe:adHoc activeElementsCollection="=activeElements" />
+      </bpmn:extensionElements>
+      <bpmn:incoming>Flow_0n50uei</bpmn:incoming>
+      <bpmn:outgoing>Flow_0m5piby</bpmn:outgoing>
+      <bpmn:serviceTask id="task_a" name="task_a">
+        <bpmn:extensionElements>
+          <zeebe:taskDefinition type="task_a" />
+        </bpmn:extensionElements>
+      </bpmn:serviceTask>
+      <bpmn:serviceTask id="task_b" name="task_b">
+        <bpmn:extensionElements>
+          <zeebe:taskDefinition type="task_b" />
+        </bpmn:extensionElements>
+      </bpmn:serviceTask>
+      <bpmn:serviceTask id="task_c" name="task_c">
+        <bpmn:extensionElements>
+          <zeebe:taskDefinition type="task_c" />
+        </bpmn:extensionElements>
+        <bpmn:outgoing>Flow_07gdlen</bpmn:outgoing>
+      </bpmn:serviceTask>
+      <bpmn:sequenceFlow id="Flow_07gdlen" sourceRef="task_c" targetRef="task_d" />
+      <bpmn:serviceTask id="task_d" name="task_d">
+        <bpmn:extensionElements>
+          <zeebe:taskDefinition type="task_d" />
+        </bpmn:extensionElements>
+        <bpmn:incoming>Flow_07gdlen</bpmn:incoming>
+      </bpmn:serviceTask>
+    </bpmn:adHocSubProcess>
+    <bpmn:sequenceFlow id="Flow_0n50uei" sourceRef="Activity_1jadqka" targetRef="Activity_0h1xev6" />
+    <bpmn:endEvent id="Event_0gs60dx">
+      <bpmn:incoming>Flow_0m5piby</bpmn:incoming>
+    </bpmn:endEvent>
+    <bpmn:sequenceFlow id="Flow_0m5piby" sourceRef="Activity_0h1xev6" targetRef="Event_0gs60dx" />
+  </bpmn:process>
+  <bpmndi:BPMNDiagram id="BPMNDiagram_1">
+    <bpmndi:BPMNPlane id="BPMNPlane_1" bpmnElement="ad-hoc-subprocess-demo">
+      <bpmndi:BPMNShape id="StartEvent_1_di" bpmnElement="StartEvent_1">
+        <dc:Bounds x="182" y="162" width="36" height="36" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="Activity_0wclalc_di" bpmnElement="Activity_1jadqka">
+        <dc:Bounds x="270" y="140" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="Activity_0kz19j1_di" bpmnElement="Activity_0h1xev6" isExpanded="true">
+        <dc:Bounds x="420" y="60" width="320" height="270" />
+        <bpmndi:BPMNLabel />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="Activity_1o2ugjf_di" bpmnElement="task_a">
+        <dc:Bounds x="450" y="100" width="100" height="80" />
+        <bpmndi:BPMNLabel />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_1tj764q" bpmnElement="task_b">
+        <dc:Bounds x="600" y="100" width="100" height="80" />
+        <bpmndi:BPMNLabel />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_1lv5cv3" bpmnElement="task_c">
+        <dc:Bounds x="450" y="210" width="100" height="80" />
+        <bpmndi:BPMNLabel />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="Activity_1hwuyjy_di" bpmnElement="task_d">
+        <dc:Bounds x="600" y="210" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNEdge id="Flow_07gdlen_di" bpmnElement="Flow_07gdlen">
+        <di:waypoint x="550" y="250" />
+        <di:waypoint x="600" y="250" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNShape id="Event_0gs60dx_di" bpmnElement="Event_0gs60dx">
+        <dc:Bounds x="792" y="162" width="36" height="36" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNEdge id="Flow_0ofj339_di" bpmnElement="Flow_0ofj339">
+        <di:waypoint x="218" y="180" />
+        <di:waypoint x="270" y="180" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="Flow_0n50uei_di" bpmnElement="Flow_0n50uei">
+        <di:waypoint x="370" y="180" />
+        <di:waypoint x="420" y="180" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="Flow_0m5piby_di" bpmnElement="Flow_0m5piby">
+        <di:waypoint x="740" y="180" />
+        <di:waypoint x="792" y="180" />
+      </bpmndi:BPMNEdge>
+    </bpmndi:BPMNPlane>
+  </bpmndi:BPMNDiagram>
+</bpmn:definitions>

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",
               ],
             },
           ],