events and signals (#508)

* events and signals

* update signal_relationships.png issue

* tweaking

---------

Co-authored-by: burnettk <burnettk@users.noreply.github.com>

docs/Building_Diagrams/events.md

@@ -0,0 +1,192 @@
+# Events
+
+Events are specific occurrences that dictate the flow or outcome of processes. They are visually represented by circles. Based on their position and function, events are categorized as: Start Events, Intermediate Events, or End Events.
+
+ ![start_message_event](images/events_categories.png) 
+
+Start Events initialize a process and have no incoming flows.
+Intermediate Events represent something happening during the process and can have both incoming and outgoing flows.
+End Events signify the conclusion of a process and don't have outgoing flows.
+
+**Event Types:**
+
+- Message Events
+- Timer Events
+- Conditional Events
+- Signal Events
+- Error Events
+- Escalation Events
+- Compensation Events
+- Link Events
+- Terminate Events
+
+We will delve into the various event types, exploring their categorizations and applications. It's vital to note that not every type of event is suitable for all variations; there are specific rules and guidelines governing their use. As highlighted in the table, there are distinct limitations. For instance, while you cannot initiate a primary process with an escalation event, it's entirely permissible to kickstart a subprocess with such an event. To adhere to BPMN standards, it's crucial to consult and follow the provided guide. Always ensure that your processes and diagrams conform to these accepted norms.
+
+![events_table](images/events_table.png) 
+
+## Start Event
+
+![start_event_t](images/start_event_t.png) 
+
+Start events signify the beginning of a specific process and can consist of catch, timer, or conditional events. They do not possess any incoming sequence flows.
+
+**Reasons to Use a Start Event:**
+
+- Whenever you want to initiate a new process or sub-process.
+- To indicate the cause or reason why a particular process starts. This could be anything from a message from another process to a specific time condition.
+
+## Intermediate Event
+
+![intermediate_event](images/intermediate_event.png)
+
+An Intermediate Event takes place between the beginning and the conclusion of a process. They can either wait for a specific occurrence (such as receiving a message), initiate an occurrence (like dispatching a message), or pause until a condition is fulfilled or a designated time elapses.
+
+**Reasons to Use an Intermediate Event:**
+
+- To represent events that happen between the start and end of a process.
+- To indicate waiting for something to happen before the process can move forward. For instance, waiting for approval in an order processing system.
+- When the process itself needs to send out a signal or a message to another process.
+- To depict delays or time conditions, like "Wait for 5 days after sending an invoice.
+- For boundary events, which are attached to activities to indicate potential interruptions or additional conditions directly linked to that activity
+
+## End Event
+
+![intermediate_throw_message_event](images/end_event.png)
+
+End events signify the end of a particular process. Once this event is reached, the process stops, and no further activities within this process will be executed.
+
+**Reasons to Use an End Event:**
+
+- To signify the conclusion of a process or sub-process.
+- To denote an outcome or result of a process. For example, an end event might signal that an order has been approved or rejected.
+- When a particular process or activity needs to be terminated prematurely.
+
+## Interrupting Events vs Non-Interrupting Events
+
+Interrupting Events halt the current process or activity they're associated with and divert the flow based on the event.
+Non-Interrupting Events allow the current process or activity to continue its execution, and the event initiates a parallel flow without disruption.
+
+### Interrupting Events
+
+![interrupting_group](images/interrupting_group.png)
+
+ When an interrupting event is triggered, it interrupts the flow of the process or activity it's attached to. Once triggered, the current activity or process is halted, and the process flow directed by the interrupting event is taken up. 
+
+**Reasons to Use an Interrupting Event:**
+
+- In the case of an error, where the current activity cannot proceed further and an exception flow needs to be initiated.
+- When an alternative flow should immediately replace the main flow, like when a timer goes off, indicating a timeout.
+
+![interrupting_example](images/interrupting_example.png)
+
+**Example:**
+Think of a scenario where a manager is given a specific duration to assess a request. If the manager fails to complete evaluation within this timeframe, an interrupting timer will activate, ceasing the ongoing process and initiating a different one. The original task is no longer accessible; instead, the situation has shifted. The provided example demonstrates the same function, but one is with an interrupting start event, while the other is with an interrupting boundary event.
+
+### Non-Interrupting Events
+
+![non-interrupting_group](images/non-interrupting_group.png)
+
+When a Non-Interrupting event is triggered, it does not halt or disrupt the main activity it's attached to. Instead, the process or activity continues its execution in parallel with the event's associated flow.
+
+**Reasons to Use a Non-Interrupting Event:**
+
+- To initiate parallel activities without disturbing the primary flow, like sending periodic reminders while still waiting for a main task to complete.
+- When you want to monitor situations without interrupting the main flow, such as watching for specific signals or messages.
+
+![interrupting_example](images/non-interrupting_example.png)
+
+**Example:**
+Consider the previous example, but instead of terminating the initial review task when the time elapses, a Non-Interrupting Event is triggered, creating another thread. A reminder is sent to the manager about the outstanding review without disturbing the primary review process. The original task proceeds uninterrupted. This scenario exemplifies the use of a Non-Interrupting Event, where the primary process and reminder notification operate in parallel. Both actions stay active throughout their execution.
+
+### Throw vs. Catch Events
+
+Throw Events actively generate or send messages, signals, or events.
+Catch Events passively wait or listen for messages, signals, or events to be received.
+
+## Throw Event
+
+![throw_events](images/throw_events.png)
+
+Throw events are used to "send" or "throw" a particular type of event. In BPMN, when we talk about a throw event, we're generally discussing an activity or a situation where a specific signal, message, or error is being generated or sent out. It is the trigger, initiating an action.
+
+
+```{admonition} Note
+⚠ Boundary Events are always catch events and cannot act as throw events. They wait for signals to guide them towards an alternative route, whether it's interrupting or non-interrupting.
+```
+
+**Reasons to Use a Throw Event:**
+
+- To send a message to another process.
+- To signal an error in a particular part of the process.
+- To indicate the raising or sending of a specific event or signal to other parts of the process or even to other processes.
+
+![throw_example](images/throw_example.png)
+
+**Example:**
+Imagine a situation where, as soon as the manufacturing of an item begins, a signal is sent to trigger a notification to another department or a customer. This signal conveys that the production task has either commenced or concluded. The throw event is immediate, causing no interruptions or delays in the main process. It's crucial to recognize that there are numerous approaches to catching or receiving this notification signal. 
+
+## Catch Event
+
+![catch_events](images/catch_events.png)
+
+Catch events are used to "receive" or "catch" a particular type of event. In BPMN, when we refer to a catch event, we're talking about a point in the process where it's waiting for or listening to a specific event from another process or activity. It is the listener, awaiting a trigger.
+
+```{admonition} Note
+⚠ End Events are always throw events and cannot act as catch events. They serve as triggers to initiate subsequent processes or actions.
+```
+
+**Reasons to Use a Catch Event:**
+
+- To wait for a message from another process.
+- To catch or handle an error.
+- To wait for a specific signal or event to be triggered before proceeding.
+
+![catch_example](images/catch_example.png)
+
+**Example:**
+The reception of an event can take place in various ways. Drawing from the previous example, the event can be caught at the inception of a sub-process within the same primary process. Alternatively, it could be captured at the start of an entirely distinct process. Moreover, it can also be seized by a boundary event of another task, provided that this task is active when the event is thrown, allowing it to be intercepted by its corresponding boundary event. It can also be caught in the middle of a process (refer to the last example in Non-Boundary Events section).
+
+## Boundary vs. Non-Boundary Events
+
+Boundary and Non-Boundary Events are pivotal in determining how certain events and activities are placed, handled and how they interact with other elements in a process.
+
+### Boundary Event
+
+![boundary_event](images/boundary_event.png)
+
+Boundary events are attached to specific activities in a BPMN diagram, representing something that could happen while the activity is being executed. If the boundary event gets triggered, it can interrupt or not interrupt the attached activity, depending on its type.
+
+**Reasons to Use a Boundary Event:**
+
+- To handle exceptions or specific situations that might occur during the execution of an activity.
+- To capture intermediate events that can interrupt (or sometimes not interrupt) the main flow of an activity.
+- To depict certain conditions under which the process should take an alternative path.
+
+![boundary_example](images/boundary_example.png)
+
+**Example:**
+In our initial scenario where a manager needs to approve or review a submission, employing a timer as a start event impacts the entire workflow. This implies that if this timer is triggered, a different process will kick off, regardless of where the main process currently stands. On the other hand, when we utilize boundary events, we can confine the timer's influence to a specific task, subprocess, or call-activity. This approach grants us greater precision over the timer's scope, as it only applies to the particular task or subprocess it's linked to, and the timer only initiates when the first task within its designated scope begins. Note that a boundary event can be interrupting or non-interrupting. 
+
+## Non-Boundary Event
+
+![non-boundary_event](images/non-boundary_event.png)
+
+Non-boundary Events stand alone in the BPMN process flow. They aren't attached to any activity, and they represent something that happens between activities. Unlike boundary events that are attached to tasks or sub-processes.
+
+**Reasons to Use a Non-Boundary Event:**
+
+- To depict events that occur independently of specific activities, such as timers or messages that are awaited.
+- To showcase events that affect the current flow but aren't tied to a particular task or activity.
+
+![non-boundary_event_example](images/non-boundary_event_example.png)
+
+**Example:**
+
+Consider a manufacturing scenario. If we want to initiate a separate process before starting the manufacturing task, we deploy a intermediate signal event. This event's role is specifically to trigger a distinct process. Differently from a start event, if a boundary catch event isn't active—meaning there's no active instance waiting at that signal event, the thrown signal won't be caught, and the separate process remains unused. 
+If our goal is to schedule the manufacturing to kick off at a specific time, say 6 pm, or delay it for a short while, we can represent this with a timer. The workflow will pause at this event until the timer's conditions are satisfied.
+Conditions function as gatekeepers. For instance, the process will halt until the 'production_sheet_signed' variable evaluates as true, indicating the production sheet has been signed and manufacturing can commence.
+The concept mirrors that of messages and signals. A message, much like a signal, will only be caught in an intermediate event if there's an instance at the ready in the associated catch event.
+
+```{admonition} Note
+⚠ Remember the key distinction between signals and message events is that while messages adhere to a one-to-one correspondence, signals can potentially relate to multiple recipients in a one-to-many fashion. 
+```

docs/Building_Diagrams/signal_events.md

@@ -0,0 +1,76 @@
+# Signal Event
+
+A Signal Event is a type of event that provides a mechanism for communication across different processes. Unlike messages that are sent from a specific sender to a specific receiver, signals are broadcast to multiple recipients. When a signal is thrown, all active processes that are listening for that signal can catch and react to it. Signals do not have any expectation of a response. Once a signal is sent out, it does not wait for a reply.
+
+ ![signal_relationship](images/signal_relationships.png) 
+
+**Reasons to Use a Signal Event:**
+
+- A signal event is used to broadcast a message to multiple signal catch events.
+- They are ideal for scenarios where a notification is important, but a reply or acknowledgment isn't necessary
+- Incorporating Signal Events in BPMN diagrams provides a versatile way to model complex inter-process interactions.
+- Signal Events can trigger multiple other processes, effectively creating separate threads from a single instance. This allows for parallel processing
+- They can help synchronize multiple processes. For instance, different processes can wait for a common signal to proceed, ensuring they operate in tandem.
+
+ 
+## Start Signal Event
+
+![start_signal_event](images/start_signal_event.png)
+
+A Start Signal Event serves as a starting point for a process or subprocess, triggered specifically by a signal broadcasted from another part of the system or even a different system entirely.
+
+![signal_event_example_2](images/signal_event_example_2.png)
+
+**Example:**
+A Start Signal Event is especially valuable in situations where a parallel process needs to commence while the primary process continues. Consider a production line in a factory where specific components are produced. Some stages of this line must occur in sequence, but others can operate concurrently. This parallel operation is what boosts the efficiency of a production line. In the image above two processes are started, meaning three processes will run in parallel. With signals, one process can initiate another. The power of a signal is its ability to launch multiple processes simultaneously because of its one-to-many relationship. It's important to note that a Start Signal Event is typically activated by an intermediate or end throw signal event
+
+## Intermediate Signal Throw Event
+
+![intermediate_throw_message_event](images/intermediate_throw_signal_event.png)
+
+An Intermediate Signal Throw Event is an event that happens in the middle of a process (not at the start or the end) and sends out a signal. This can be caught by another process or a different part of the same process using a Signal Catch Event.
+
+![intermediate_throw_signal_example_2](images/intermediate_throw_signal_example_2.png) 
+
+**Example:**
+Using an Intermediate Throw Event aligns perfectly with the scenario illustrated earlier. To give another example, think about placing an order. Continuous communication with the customer throughout the order process is crucial. However, there's no need to halt our process of fulfilling the order just to send a notification. A more efficient approach is to run a parallel process specifically for notifications. This way, if there's a hiccup in the communication process, it won't impede the primary order completion. Implementing multiple threads to concurrently execute tasks for an instance, as seen when using intermediate signal events, boosts overall efficiency.
+
+## Intermediate Signal Catch Event
+
+![intermediate_catch_message_event](images/intermediate_catch_signal_event.png)
+
+An Intermediate Signal Catch Event waits for a specific signal to start or continue a process. To "catch" means that this event is actively waiting or listening for that signal to be thrown from another part of the process or even from a different process.
+
+![intermediate_catch_signal_example](images/intermediate_catch_signal_example.png) 
+
+**Example:**
+To better understand the difference between a start event and an intermediate event, let's examine a manufacturing example. Within this scenario, the intermediate catch event is a part of an ongoing process, unlike the start event which initiates a new process as seen in our previous example. Picture two simultaneous processes, each crafting a distinct component. The final assembly, however, is dependent on the completion of the first component. Once the production of the second component is finalized, marked by a throw signal, the intermediate catch event pauses and awaits the readiness of the first component before proceeding further.
+
+```{admonition} Note
+⚠  In this example, it's crucial to highlight an underlying assumption: part two must always precede part one. Should this sequence be reversed, the process would fail. This is because the process necessitates the completion of part two, after which the instance is waiting at the catch event, ready to receive the throw event signaling the conclusion of part one. This scenario highlights the importance of understanding the intricacies of each symbol when designing functional and reliable workflows.
+```
+
+![intermediate_catch_signal_example](images/intermediate_catch_signal_example_2.png)
+
+**Example:**
+Let's delve into an example distinguishing between interrupting and non-interrupting boundary catch events. It's vital to recognize that a task must maintain an active instance for it to capture a throw signal via a related boundary event.
+In the case of the interrupting event, both Task 1 and Task 2 will conclude. This is apt for scenarios where, for instance, an order gets canceled and the following tasks are rendered unnecessary.
+Conversely, for the non-interrupting event (depicted on the right), while Task 2 is interrupted, Task 1 persists in its active state and concurrently, Task 3 gets activated.
+
+## End Signal Event
+
+![end_signal_event](images/end_signal_event.png) 
+
+This type of event signifies the end of a process or path and, at the same time, broadcasts a signal to other processes or process instances.
+
+![end_signal_event_example](images/end_signal_event_example.png) 
+
+**Example:**
+
+In an online shopping system, when a customer's payment is successfully processed, an End Signal Event can be triggered. This signal initiates three distinct processes: (1) the "Send Notification" process alerts the customer of their successful purchase, (2) the "Pack Order" process prompts the warehouse team to prepare the item for dispatch, and (3) the "Schedule Delivery" process alerts logistics to arrange for the item's delivery. In this manner, one event efficiently orchestrates a sequence of actions across multiple departments.
+
+![end_signal_event_example](images/signal_sync_example.png) 
+
+**Example:**
+Signals are instrumental in coordinating workflows among varied processes, making certain that tasks adhere to a specified order. Leveraging intermediate catch and throw events allows one process to temporarily halt until tasks in a different process are finished. This is especially beneficial when certain stages can only commence after the completion of others — imagine the utility of such a system across multiple departments.
+

docs/index.md

@@ -14,7 +14,9 @@ Building_Diagrams/learn_basics.md
 Building_Diagrams/bpmn.md
 Building_Diagrams/Forms.md
 Building_Diagrams/gateways.md
+Building_Diagrams/events.md
 Building_Diagrams/message_events.md
+Building_Diagrams/signal_events.md
 Building_Diagrams/Displaying_Content.md
 Building_Diagrams/Script_Tasks.md
 Building_Diagrams/sub-processes_and_call_activities.md