diff --git a/docs/apis-clients/grpc.md b/docs/apis-clients/grpc.md
index 19a7a6cc55f..8f4a8ec907b 100644
--- 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
new file mode 100644
index 00000000000..47294d1e98f
--- /dev/null
+++ 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
index 946a941204d..1d41ea6d754 100644
--- 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
- Signal
+ Signal
|
-
-
+
+
|
diff --git a/docs/components/modeler/bpmn/events.md b/docs/components/modeler/bpmn/events.md
index a1955b28c05..3fcd69eee2f 100644
--- 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
new file mode 100644
index 00000000000..62ec613f45f
Binary files /dev/null and b/docs/components/modeler/bpmn/signal-events/assets/signal-start-event.png differ
diff --git a/docs/components/modeler/bpmn/signal-events/signal-events.md b/docs/components/modeler/bpmn/signal-events/signal-events.md
new file mode 100644
index 00000000000..dd1f4b32284
--- /dev/null
+++ 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
+
+
+
+
+
+```
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
new file mode 100644
index 00000000000..0cbb2737c9c
--- /dev/null
+++ b/media-pre-src/docs/components/modeler/bpmn/signal-events/signal-start-event.bpmn
@@ -0,0 +1,43 @@
+
+
+
+
+ Flow_1t5xr6l
+
+
+
+
+ Flow_06le21g
+
+
+
+ Flow_1t5xr6l
+ Flow_06le21g
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/sidebars.js b/sidebars.js
index a7d9ba3f2e0..2e6f5782760 100644
--- 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",
|