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