Document Signal events (#1893)

* docs(signal): document signal start events - Adds a signal event page - Mark the signal start event implemented in the BPMN coverage - Explain signal start events * docs(signal): document broadcast signal RPC Adds documentation of the BroadcastSignal RPC * docs(signal): document signals concept * docs(signal): restructure sidebar * docs(signal): move bpmn file to different location Moving the bpmn file to this folder prevents docusaurus from having to package it. * docs(signal): link from grpc to signal concepts page * docs(signal): add signals use-case example * docs(signal): restructure signals concepts text * docs(signal): add section about variables * docs(signal): add note about unsupported signal events * style(formatting): technical review * docs(signals): process review - Clarified subscription for signal starts events - Clarified variable mappings --------- Co-authored-by: Christina Ausley <[email protected]>
camunda · Apr 6, 2023 · 16ec7ae · 16ec7ae
1 parent e5ad4ec
commit 16ec7ae
Show file tree

Hide file tree

Showing 8 changed files with 145 additions and 3 deletions.
diff --git a/docs/apis-clients/grpc.md b/docs/apis-clients/grpc.md
@@ -92,6 +92,32 @@ Returned if:
 - Timeout less than 1 (ms)
 - maxJobsToActivate is less than 1
 
+### `BroadcastSignal` RPC
+
+Broadcasts a [signal](../components/concepts/signals.md).
+
+#### Input: `BroadcastSignalRequest`
+
+```protobuf
+message BroadcastSignalRequest {
+  // The name of the signal
+  string signalName = 1;
+
+  // the signal variables as a JSON document; to be valid, the root of the document must be an
+  // object, e.g. { "a": "foo" }. [ "foo" ] would not be valid.
+  string variables = 2;
+}
+```
+
+#### Output: `BroadcastSignalResponse`
+
+```protobuf
+message BroadcastSignalResponse {
+  // the unique ID of the signal that was broadcasted.
+  int64 key = 1;
+}
+```
+
 ### `CancelProcessInstance` RPC
 
 Cancels a running process instance.

diff --git a/docs/components/concepts/signals.md b/docs/components/concepts/signals.md
@@ -0,0 +1,23 @@
+---
+id: signals
+title: "Signals"
+description: "Learn about broadcasting signals, which can trigger all matching signal events with a single broadcast."
+---
+
+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
+respond accordingly.
+
+## 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
+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.
+
+## 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.
diff --git a/docs/components/modeler/bpmn/bpmn-coverage.md b/docs/components/modeler/bpmn/bpmn-coverage.md
@@ -399,11 +399,11 @@ import MultipleParallelBoundaryEventNonInterruptingSvg from './assets/bpmn-symbo
     </tr>
     <tr>
         <td>
-            Signal
+            <a href="../signal-events/">Signal</a>
         </td>
         <td>
-            <a href="#">
-                <SignalStartEventSvg />
+            <a href="../signal-events/">
+                <SignalStartEventSvg className="implemented" />
             </a>
         </td>
         <td>

diff --git a/docs/components/modeler/bpmn/events.md b/docs/components/modeler/bpmn/events.md
@@ -13,6 +13,11 @@ Currently supported events:
 - [Escalation events](escalation-events/escalation-events.md)
 - [Terminate events](terminate-events/terminate-events.md)
 - [Link events](link-events/link-events.md)
+- [Signal events](signal-events/signal-events.md)
+
+:::note
+Not all the signal events are supported yet. For a complete overview of supported events, refer to the [BPMN coverage](../bpmn-coverage#events).
+:::
 
 ## Events in general
 

diff --git a/docs/components/modeler/bpmn/signal-events/assets/signal-start-event.png b/docs/components/modeler/bpmn/signal-events/assets/signal-start-event.png
diff --git a/docs/components/modeler/bpmn/signal-events/signal-events.md b/docs/components/modeler/bpmn/signal-events/signal-events.md
@@ -0,0 +1,43 @@
+---
+id: signal-events
+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 start events
+
+![Process with a top-level signal start event](assets/signal-start-event.png)
+
+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.
+
+Broadcasting a signal will iterate 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.
+
+## 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.
+
+For more information about variable scopes, visit the documentation about [variable scopes](../../../concepts/variables#variable-scopes).
+
+## Additional resources
+
+### XML representation
+
+A signal start event with signal definition:
+
+```xml
+<bpmn:startEvent id="startEventId">
+    <bpmn:signalEventDefinition id="signalEventDefinitionId" signalRef="signalId" />
+</bpmn:startEvent>
+
+<bpmn:signal id="signalId" name="signal" />
+```
diff --git a/media-pre-src/docs/components/modeler/bpmn/signal-events/signal-start-event.bpmn b/media-pre-src/docs/components/modeler/bpmn/signal-events/signal-start-event.bpmn
@@ -0,0 +1,43 @@
+<?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:di="http://www.omg.org/spec/DD/20100524/DI" xmlns:modeler="http://camunda.org/schema/modeler/1.0" id="Definitions_1vwix6t" targetNamespace="http://bpmn.io/schema/bpmn" exporter="Camunda Modeler" exporterVersion="5.9.0" modeler:executionPlatform="Camunda Cloud" modeler:executionPlatformVersion="8.1.0">
+  <bpmn:process id="Process_0iypqeg" isExecutable="true">
+    <bpmn:startEvent id="StartEvent_1" name="Signal received">
+      <bpmn:outgoing>Flow_1t5xr6l</bpmn:outgoing>
+      <bpmn:signalEventDefinition id="SignalEventDefinition_1eg2olc" />
+    </bpmn:startEvent>
+    <bpmn:sequenceFlow id="Flow_1t5xr6l" sourceRef="StartEvent_1" targetRef="Activity_1750mu3" />
+    <bpmn:endEvent id="Event_03jvwzp">
+      <bpmn:incoming>Flow_06le21g</bpmn:incoming>
+    </bpmn:endEvent>
+    <bpmn:sequenceFlow id="Flow_06le21g" sourceRef="Activity_1750mu3" targetRef="Event_03jvwzp" />
+    <bpmn:serviceTask id="Activity_1750mu3" name="Perform action">
+      <bpmn:incoming>Flow_1t5xr6l</bpmn:incoming>
+      <bpmn:outgoing>Flow_06le21g</bpmn:outgoing>
+    </bpmn:serviceTask>
+  </bpmn:process>
+  <bpmndi:BPMNDiagram id="BPMNDiagram_1">
+    <bpmndi:BPMNPlane id="BPMNPlane_1" bpmnElement="Process_0iypqeg">
+      <bpmndi:BPMNShape id="Event_08nmn19_di" bpmnElement="StartEvent_1">
+        <dc:Bounds x="179" y="99" width="36" height="36" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="159" y="142" width="76" height="14" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="Event_03jvwzp_di" bpmnElement="Event_03jvwzp">
+        <dc:Bounds x="432" y="99" width="36" height="36" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="Activity_1ekk65q_di" bpmnElement="Activity_1750mu3">
+        <dc:Bounds x="270" y="77" width="100" height="80" />
+        <bpmndi:BPMNLabel />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNEdge id="Flow_1t5xr6l_di" bpmnElement="Flow_1t5xr6l">
+        <di:waypoint x="215" y="117" />
+        <di:waypoint x="270" y="117" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="Flow_06le21g_di" bpmnElement="Flow_06le21g">
+        <di:waypoint x="370" y="117" />
+        <di:waypoint x="432" y="117" />
+      </bpmndi:BPMNEdge>
+    </bpmndi:BPMNPlane>
+  </bpmndi:BPMNDiagram>
+</bpmn:definitions>
diff --git a/sidebars.js b/sidebars.js
@@ -70,6 +70,7 @@ module.exports = {
         "components/concepts/job-workers",
         "components/concepts/process-instance-creation",
         "components/concepts/messages",
+        "components/concepts/signals",
         "components/concepts/incidents",
         "components/concepts/variables",
         "components/concepts/expressions",
@@ -204,6 +205,7 @@ module.exports = {
                 "components/modeler/bpmn/events",
                 "components/modeler/bpmn/none-events/none-events",
                 "components/modeler/bpmn/message-events/message-events",
+                "components/modeler/bpmn/signal-events/signal-events",
                 "components/modeler/bpmn/timer-events/timer-events",
                 "components/modeler/bpmn/error-events/error-events",
                 "components/modeler/bpmn/escalation-events/escalation-events",