Document signal catch and throw events

docs/components/concepts/signals.md

@@ -6,18 +6,35 @@ description: "Learn about broadcasting signals, which can trigger all matching s
 
 Signals are a similar concept to [messages](messages.md). However, messages are correlated to a specific
 process instance, whereas signals can trigger _all_ the matching signal events with a single broadcast.
-Depending on the type of [signal catch events](../modeler/bpmn/signal-events/signal-events.md) the process instance will
+Depending on the type of [signal catch events](../modeler/bpmn/signal-events/signal-events.md), the process instance will
 respond accordingly.
 
+## Broadcasting signals
+
+You can broadcast signals in two ways:
+
+- Using Zeebe's [`BroadcastSignal` RPC](../../../apis-tools/grpc/#broadcastsignal-rpc)
+- Using a [signal throw event or signal end event](../modeler/bpmn/signal-events/signal-events.md#signal-throw-events)
+
 ## Signal subscriptions
 
-Signals work using subscriptions. When a process encounters a signal catch event it creates a new signal subscription.
-This process instance waits until a signal with a matching name is broadcasted. You can define the signal name in the
+When you broadcast a signal it triggers _all_ signal subscriptions that match the signal name.
+
+When a process instance encounters a signal catch event it creates a new signal subscription. This process instance waits until a signal with a matching name is broadcasted. You can define the signal name in the
 process definition.
-Deploying a process with a signal start event also creates a new signal subscription. In this case the subscription will
-be used to start a new process instance.
+
+Deploying a process with a signal start event also creates a new signal subscription. In this case, the triggered
+subscription starts a new process instance.
 
 ## Signal cardinality
 
 A broadcasted signal iterates over _all_ available subscriptions. As a result, a single broadcast triggers _all_ the
-signal catch events that match the signal name.
+signal catch events that match the signal name, and _all_ [partitions](../zeebe/technical-concepts/partitions.md).
+
+:::caution
+Signals can negatively impact the performance of Camunda 8. Performance is impacted in two ways:
+
+- Signals trigger _all_ available subscriptions that match the signal name, potentially resulting in the continued execution of many processes.
+- Signals are broadcasted to _all_ partitions, resulting in lots of network traffic. This scales linearly with the number of partitions.
+
+:::

docs/components/modeler/bpmn/bpmn-coverage.md

@@ -407,38 +407,38 @@ import MultipleParallelBoundaryEventNonInterruptingSvg from './assets/bpmn-symbo
             </a>
         </td>
         <td>
-            <a href="#">
-                <SignalEventSubprocessSvg />
+            <a href="../signal-events/">
+                <SignalEventSubprocessSvg className="implemented" />
             </a>
         </td>
         <td>
-            <a href="#">
-                <SignalEventSubprocessNonInterruptingSvg />
+            <a href="../signal-events/">
+                <SignalEventSubprocessNonInterruptingSvg className="implemented" />
             </a>
         </td>
         <td>
-            <a href="#">
-                <SignalCatchEventSvg />
+            <a href="../signal-events/">
+                <SignalCatchEventSvg className="implemented" />
             </a>
         </td>
         <td>
-            <a href="#">
-                <SignalBoundaryEventSvg />
+            <a href="../signal-events/">
+                <SignalBoundaryEventSvg className="implemented" />
             </a>
         </td>
         <td>
-            <a href="#">
-                <SignalBoundaryEventNonInterruptingSvg />
+            <a href="../signal-events/">
+                <SignalBoundaryEventNonInterruptingSvg className="implemented" />
             </a>
         </td>
         <td>
-            <a href="#">
-                <SignalThrowEventSvg />
+            <a href="../signal-events/">
+                <SignalThrowEventSvg className="implemented" />
             </a>
         </td>
         <td>
-            <a href="#">
-                <SignalEndEventSvg />
+            <a href="../signal-events/">
+                <SignalEndEventSvg className="implemented" />
             </a>
         </td>
     </tr>

docs/components/modeler/bpmn/event-based-gateways/event-based-gateways.md

@@ -8,7 +8,9 @@ An event-based gateway allows you to make a decision based on events.
 
 ![process](assets/event-based-gateway.png)
 
-An event-based gateway must have at least **two** outgoing sequence flows. Each sequence flow must to be connected to an intermediate catch event of type **timer or message**.
+An event-based gateway must have at least **two** outgoing sequence flows. Each sequence flow must be connected to
+an intermediate catch event of type [timer](../timer-events/timer-events.md),
+[message](../message-events/message-events.md) or [signal](../signal-events/signal-events.md).
 
 When an event-based gateway is entered, the process instance waits at the gateway until one of the events is triggered. When the first event is triggered, the outgoing sequence flow of this event is taken. No other events of the gateway can be triggered afterward.
 
@@ -35,6 +37,10 @@ An event-based gateway with two outgoing sequence flows:
     <bpmn:timeDuration>PT1H</bpmn:timeDuration>
   </bpmn:timerEventDefinition>
 </bpmn:intermediateCatchEvent>
+
+<bpmn:intermediateCatchEvent id="payment-canceled" name="Payment canceled">
+  <bpmn:signalEventDefinition signalRef="signal-payment-canceled" />
+</bpmn:intermediateCatchEvent>
 ```
 
 ### References

docs/components/modeler/bpmn/signal-events/signal-events.md

@@ -4,27 +4,74 @@ title: "Signal events"
 description: "Signal events are events which reference a signal; they are used to wait until a matching signal is received."
 ---
 
-Signal events are events which reference a signal. Broadcasting a signal will trigger all signal events matching the
-name of the broadcasted signal.
+Signal events are events which reference a [signal](../../../concepts/signals.md).
+Broadcasting a signal will trigger _all_ signal events matching the name of the broadcasted signal.
 
-## Signal start events
+![Process with multiple different signal events](assets/signal-events.png)
 
-![Process with a top-level signal start event](assets/signal-start-event.png)
+## Signal start events
 
-Signal start event can be used to start process instances. Deploying processes with a signal start event enables creating
-multiple process instances by performing a single broadcast.
+Signal start events can be used to start process instances. Deploying several processes with a signal start event enables
+creation of multiple process instances by performing a single broadcast.
 
-Broadcasting a signal will iterate over the available subscriptions. If the name of the broadcasted signal matches the
+Broadcasting a signal iterates over the available subscriptions. If the name of the broadcasted signal matches the
 name of the signal start event, the process instance is created.
 
 Signal subscriptions only exist for the latest version of a process definition. Deploying a new version of the same
 process (based on the BPMN process id) will delete the old signal subscription. A new subscription is opened for the
-new deployed process definition.
+new deployed process definition. When the latest version of a process is deleted, the signal subscription is also deleted. If the previous version of the same process (based on the BPMN process id) contains a signal start event, a new subscription
+is opened for it.
+
+## Signal intermediate catch events
+
+When a signal intermediate catch event is entered, a signal subscription is created.
+The process instance stops at this point and waits until it is triggered by a broadcasted signal with the same name.
+
+Broadcasting a signal will iterate over the available subscriptions. If the name of the broadcasted signal matches the
+name of the signal subscription, it triggers the signal subscription.
+
+When the subscription is triggered, the corresponding signal catch event is completed and the process instance continues.
+
+## Signal boundary events
+
+An activity can have one or more signal boundary events.
+Each of the signal events must have a unique signal name.
+
+When the activity is entered, it creates a signal subscription for each boundary signal event.
+If a non-interrupting boundary event is triggered, the activity is not terminated and multiple broadcasted signals can
+trigger the boundary events.
+
+## Signal throw events
+
+A process can contain signal intermediate throw events or signal end events to model the broadcasting of a signal.
+
+When a signal throw events is entered, it broadcasts a signal that can trigger signal subscriptions.
+
+## Signals
+
+In BPMN, a signal event references a `signal`.
+Signals can be referenced by one or more signal events.
+
+A signal must define a `name`. The value is used to determine:
+
+- The name of the signal to broadcast for a signal throw event.
+- The name of the signal to subscribe to for a signal catch event.
+
+Usually, the name of the signal is defined as a [static value](../../../concepts/expressions/#expressions-vs-static-values)
+(e.g. `order canceled`), but it can also be defined as an [expression](../../../concepts/expressions/)
+(e.g. `= "order " + awaitingAction`). If the expression belongs to a signal start event of the process, it is evaluated
+on deploying the process. Otherwise, it is evaluated on activating the signal event. The evaluation must result in a
+`string`.
 
 ## Variable mappings
 
-When broadcasting a signal you can pass along variables. By default, all signal variables are merged into the process
-instance. This behavior can be customized by defining an output mapping at the signal catch event.
+When broadcasting a signal you can pass along variables.
+
+By default, all signal variables are merged into the process instance.
+This behavior can be customized by defining an output mapping at the signal catch event.
+
+When a signal throw event broadcasts a signal, all local variables are passed along.
+You can use input mappings to define these local variables.
 
 For more information about variable scopes, visit the documentation about [variable scopes](../../../concepts/variables#variable-scopes).
 
@@ -35,9 +82,39 @@ For more information about variable scopes, visit the documentation about [varia
 A signal start event with signal definition:
 
 ```xml
-<bpmn:startEvent id="startEventId">
+<bpmn:startEvent id="startEventId" name="Order placed">
     <bpmn:signalEventDefinition id="signalEventDefinitionId" signalRef="signalId" />
 </bpmn:startEvent>
 
-<bpmn:signal id="signalId" name="signal" />
+<bpmn:signal id="signalId" name="order placed" />
+```
+
+A signal boundary event with signal definition:
+
+```xml
+<bpmn:boundaryEvent id="order-canceled" name="Order canceled" attachedToRef="ActivityId">
+  <bpmn:signalEventDefinition id="signalId" />
+</bpmn:boundaryEvent>
+
+<bpmn:signal id="signalId" name="order canceled" />
+```
+
+A signal intermediate catch event with signal definition:
+
+```xml
+<bpmn:intermediateThrowEvent id="money-collected" name="Money collected">
+    <bpmn:signalEventDefinition id="signalEventDefinitionId" signalRef="signalId" />
+</bpmn:intermediateThrowEvent>
+
+<bpmn:signal id="signalId" name="money collected" />
+```
+
+A signal end event with signal definition:
+
+```xml
+<bpmn:endEvent id="parcel_shipped" name="Parcel shipped">
+  <bpmn:signalEventDefinition id="signalEventDefinitionId" signalRef="signalId" />
+</bpmn:endEvent>
+
+<bpmn:signal id="signalId" name="parcel shipped" />
 ```