Condition, escalation, timer events (#681)

* Condition, escalation,timer events

* tweaks

* rename

* ventilate prose

---------

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

docs/Building_Diagrams/conditional_events.md

@@ -0,0 +1,87 @@
+# Conditional Event
+
+A Conditional Event is a type of event that activates based on the evaluation of a condition, typically expressed as a Boolean expression (true or false).
+Conditional Events depend on the state or value of process variables that are part of the process context.
+They continuously evaluate the given condition and act when the condition is met.
+
+```{admonition} Note
+⚠  The variable(s) evaluated in the condition should typically be initialized with a default value, often set to false. This ensures it doesn't trigger prematurely. Thus, it remains evaluated as false until the specified condition turns true. Importantly, this variable needs to be accessible within the process context.
+```
+
+**Reasons to Use a Conditional Event:**
+
+- A Conditional Event is ideal for processes where decision-making is based on data or state changes.
+- They allow processes to adapt and respond dynamically to changing conditions within the system.
+
+## Start Conditional Event
+
+![start_signal_event](images/start_conditional_event.png)![start_signal_event](images/non_interrupting_conditional_start_event.png)
+
+A Start Conditional Event marks the beginning of a process or a sub-process, triggered when a specific condition is fulfilled, or in other terms, when the condition evaluates to true.
+
+
+**Example:**
+
+![conditional_start_example](images/conditional_start_example_1.png)
+
+**Conditional Start Event (interrupting):**
+In the first scenario, as a transaction is being processed, funds are withdrawn from a ledger. If this withdrawal results in a negative ledger balance, a certain condition is triggered, stopping the entire process. This is crucial because we can't proceed with a payment if there aren't sufficient funds.
+
+**Conditional Start Event (non-interrupting):**
+In the subsequent scenario, as an online order is placed by a customer, our inventory count gets adjusted. Should this count descend beneath a set threshold, an alert is activated, signaling the warehouse to replenish stocks. Our goal is to maintain an uninterrupted shopping experience for the customer, yet it's important to inform relevant staff when our inventory nears depletion.
+
+## Intermediate Conditional Event
+
+![intermediate_conditional_event](images/intermediate_conditional_event.png) ![intermediate_conditional_event](images/non_interrupting_intermediate_conditional_event.png)
+
+An Intermediate Conditional Event serves as a gate or checkpoint within the flow of a process.
+The process flow will proceed once the attached condition evaluates to true.
+Additionally, a Boundary Event can be associated with specific tasks or sub-processes, acting as an interrupter based on certain conditions.
+This ensures that certain actions are taken or the process is redirected when particular circumstances arise.
+
+**Example:**
+
+![conditional_intermediate_example_1](images/conditional_intermediate_example_1.png)
+
+**Conditional Intermediate Catch Event:**
+Once an order is packed and ready for shipping, it doesn't necessarily imply immediate delivery. The delivery process hinges on the availability of a driver. If no driver is available at the moment, we must patiently await notification of one becoming available.
+
+In a bakery, pastries are made in bulk.
+However, they can only be put in the oven when it reaches the necessary temperature.
+While one might consider using a timer to gauge readiness (and it's not entirely wrong to do so), a timer only measures the elapsed time since activation.
+It can't determine the actual temperature inside the oven.
+Given that our pastries need a specific temperature for baking, only when this condition is met can we proceed to place them in the oven.
+
+**Example:**
+
+![conditional_intermediate_example_2](images/conditional_intermediate_example_2.png)
+
+**Conditional Boundary Event (interrupting):** 
+Boundary events allows us to redirect our processes based on shifts in certain conditions. It's wise to consider such a strategy since it's unrealistic to expect every process to proceed without hiccups. Therefore, planning for alternative pathways becomes essential.
+
+Imagine a user in the midst of completing a form suddenly opting to cancel the process.
+Or consider a scenario where a user is finalizing an order, only to find that due to a changed condition, the desired product is no longer available.
+In such cases, the interrupting event ensures we don't proceed on the originally planned course because the order will not be fulfilled.
+Instead, we shift and use the alternative route to inform the user that the intended process can't progress further, we order more stock or we place the user on a list to be notified when product becomes available again.
+
+**Conditional Boundary Event (non-interrupting):** 
+It's also beneficial in scenarios where there's no need to disrupt the initial workflow, like when receiving a change request. The task still requires completion, but there's an additional remark or modification we must be mindful of.
+
+**Best Modeling Practices:**
+
+![conditional_intermediate_example_3](images/conditional_intermediate_example_3.png)
+
+When utilizing a condition to loop back to a previous stage, it's crucial to highlight that the condition should be reset to evaluate as false once again.
+If not adjusted, the condition might activate immediately when the instance revisits the task, potentially causing an infinite loop.
+Always revert the condition to its default state to ensure appropriate behavior.
+
+## Conditional Event Configuration
+
+| 💻 Form | ⌨ Field Input | 📝 Description |
+| --- | --- | --- |
+| ![name_field](images/name_field.png) | **Name:** Request Assistance | A descriptive name given to the element, providing a human-readable label or title. |
+| ![id_field](images/id_field.png) | **ID:** Example - request_assistance | An identifier used to uniquely identify the element within the BPMN model. |
+| ![configure_conditional_event](images/configure_conditional_event.png) | **Conditional Expression:** request_assistance == true | Set the expression that needs to be evaluated to take action. |
+
+```{admonition} Note
+⚠  When configuring the conditional expression, ensure there's such a variable in your process context.

docs/Building_Diagrams/escalation_events.md

@@ -0,0 +1,91 @@
+# Escalation Event
+
+An Escalation Event in BPMN symbolizes a situation where an issue or condition within a process requires attention at a higher level or different domain.
+This event acts as a mechanism to raise awareness or invoke intervention.
+
+```{admonition} Note
+⚠  Escalation Events are similar to signals; however, they differ in their application. An escalation represents a one-to-one relationship, whereas a signal event embodies a one-to-many relationship.
+```
+
+**Reasons to Use an Escalation Event:**
+
+- Communicate to a subprocess or an upper (parent) process
+- Provide a structured way to handle exceptions, ensuring processes remain fluid despite interruptions
+
+## Start Escalation Event
+
+![start_escalation_event](images/start_escalation_event.png)![non_interrupting_start_escalation_event](images/non_interrupting_start_escalation_event.png)
+
+A Start Escalation Event indicates the beginning of a sub-process, triggered explicitly by an escalation from another process or activity.
+
+```{admonition} Note
+⚠  Escalation Events are typically used in scenarios where standard process flow is disrupted, and involvement from other actors becomes essential for resolution. They are mostly used to communicate from a subprocess to an upper process.
+```
+
+**Example:**
+
+![start_escalation_example](images/start_escalation_example_1.png)
+
+**Escalation Start Event (interrupting):** 
+In a production environment, if a machine malfunctions frequently, or requires calibration, the issue might be escalated to a specialized technical team. This team then initiates a comprehensive diagnostic process to identify and fix the root cause.
+
+**Escalation Start Event (non-interrupting):** 
+After a customer's order is processed, a non-interrupting escalation event is triggered. This event sends a notification to the customer that their order is being prepared for shipment. The key feature of this event is that it is non-interrupting, which means the notification to the customer does not halt the process of moving the order to the shipping phase. It allows for parallel processing to allow the process to continue seamlessly to the next step.
+
+## Intermediate Escalation Event
+
+![intermediate_escalation_event](images/intermediate_escalation_throw_event.png) ![intermediate_escalation_event](images/intermediate_escalation_catch_event.png) ![intermediate_escalation_event](images/non_interrupting_intermediate_escalation_event.png)
+
+An Intermediate Escalation Event serves as a mechanism within a process flow to raise an escalation.
+This could be due to an exception, a delay, or any condition that requires intervention.
+As a Boundary Event, it can also be associated with specific tasks or sub-processes, highlighting the need for escalation if certain criteria are met.
+
+**Example:**
+
+![escalation_intermediate_example_2](images/escalation_example_2.png)
+
+In the same BPMN scenario, escalations can be managed at a higher level in the process hierarchy through a boundary escalation event.
+This method involves placing the escalation event on the border of the parent process activity.
+
+**Escalation Boundary Event (interrupting):** 
+When the machine manufacturing a part requires calibration, it can be escalated to a parent process where a process is followed to notify or handle the alternate path by catching the throw event (Escalation End Event) from its child process.
+
+**Escalation Boundary Event (non-interrupting):** 
+The same can be done for our order processing scenario. A non-interrupting escalation event is caught by the parent process, alerting the customer that their order is ready for shipment. This boundary event operates in tandem with the core process, updating the customer in real-time while maintaining uninterrupted progression to shipping. This parallel processing ensures that there are two active instances within the workflow hierarchy, with one instance continuing the child process and the other managing customer communication on the parent level.
+
+```{admonition} Note
+⚠  A call process is generally employed for processes that can be repeated across different scenarios or use cases.
+```
+
+**Example:**
+
+![escalation_intermediate_example_2](images/escalation_example_3.png)
+
+**Escalation Boundary Event (interrupting):** 
+In the given scenario, utilizing a subprocess can lead to the desired outcome similarly. A gateway is used to assess whether a machine needs calibration. With only one potential result from this evaluation—calibration being necessary—the escalation event is captured at the boundary of the subprocess. In this case, since there is a single active process instance, the non-interrupting characteristic of the event does not impact the process's flow.
+
+**Escalation Boundary Event (non-interrupting):** 
+In a subsequent setup, a parallel gateway launches two simultaneous paths. While one path proceeds with the shipment as usual, the other leverages parallel processing to update the customer. The update is facilitated through a non-interrupting boundary event within a subprocess, which ensures the shipment process continues uninterrupted.
+
+```{admonition} Note
+⚠  The same end result was achieved by three different usescases for the escalation events. The choice of event type should be based on the particular application and context, as this will inform the most appropriate design decision for your process.
+```
+
+## End Escalation Event
+
+![intermediate_escalation_event](images/end_escalation_event.png) 
+
+In our earlier examples, we demonstrated how to use throw and catch events.
+The End Escalation event functions similarly to the Intermediate Throw Escalation event, with the key distinction being its occurrence at the end of a particular pathway.
+It's important to note that the End Escalation event doesn't always signify the termination of the entire process.
+Particularly in scenarios involving non-interrupting events, the process instance may continue independently even after the escalation event is triggered.
+
+**Example:**
+
+![escalation_intermediate_example_2](images/escalation_example_4.png)
+
+In this scenario, we observe an End Escalation following a Boundary Event.
+This thrown End Escalation can be intercepted by the boundary event of a Call Activity or at the start of a sub-process, as shown in previous examples on this page.
+In another example, we see an End Escalation event being thrown within a sub-process and caught at the sub-process's boundary.
+The application of the last example aligns with the first, where the escalation can be intercepted either on a Call Activity or at the beginning of a sub-process.
+It's crucial to remember that whether a process is created or terminated in these contexts depends on whether non-interrupting or interrupting events are utilized.

docs/Building_Diagrams/timer_events.md

@@ -0,0 +1,113 @@
+# Timer Event
+
+A Timer Event in BPMN is tied to the concept of time.
+It represents a specific moment or duration after which certain actions in a process are initiated or controlled.
+Using Timer Events ensures that processes can be designed to factor in time-based conditions, which are common in real-world scenarios.
+There are 3 specific types.
+
+**Specific Date/Time Trigger:** 
+A Timer Event can be set to activate on an exact date and time. This is like setting an alarm clock. When the clock hits the designated time, the Timer Event is triggered. For instance, a monthly system backup could be initiated using a Timer Event set for the first day of every month at 2:00 AM.
+
+- **2023-12-25T09:00:00Z** - This would set the timer to trigger at 9:00 AM (UTC) on December 25, 2023.
+- **2024-01-01T00:00:00-05:00** - This would set the timer to trigger at midnight (Eastern Time) on January 1, 2024, accounting for the time zone offset.
+
+**Duration-based Trigger:** This isn't a fixed point in time but a period that is often defined in the format of 'PnYnMnDTnHnMnS', (where P indicates the period, T separates date and time elements, and Y, M, D, H, M, S represent years, months, days, hours, minutes, and seconds, respectively). It's analogous to using a stopwatch. Once the task or process starts, the Timer Event begins counting, and after the predefined duration (say, 48 hours), it activates.
+An example scenario might be an e-commerce platform setting a Timer Event to automatically cancel unprocessed orders after 72 hours.
+
+- **PT72H** - Represents a period of 72 hours.
+- **P2D** - Equates to a period of two days.
+- **P3DT12H30M** - Corresponds to a period of three days, twelve hours, and thirty minutes.
+
+**Recurring Trigger:** Advanced uses of Timer Events can involve recurring time patterns, like activating a process every 8 hours for 3 cycles. This pattern-based time definition can manage repetitive tasks without needing individual Timer Events for each occurrence. The R denotes recurrence, followed by the number of recurrences, and PT8H is the duration of 8 hours.
+
+- **R3/PT8H** Every 8 hours for 3 cycles. 
+
+**Reasons to Use a Timer Event:**
+
+- A Timer Event is perfect for processes that have to wait for a specific period or set time before starting or progressing to the next step.
+- They allow processes to adapt and react based on time-sensitive conditions or deadlines.
+
+## Start Timer Event
+
+![start_signal_event](images/start_timer_event.png)![start_timer_example](images/non_interrupting_start_timer.png)
+
+A Start Timer Event marks the beginning of a process or sub-process, but only once a specified period has elapsed or at a predetermined time.
+
+**Example:**
+
+![start_timer_example](images/start_timer_example.png)
+
+**Timer Start Event:** Consider a company that sends out a newsletter on the first of every month. To achieve this, they could set up a 'Start Timer Event' named 'Monthly Newsletter Timer' with a cyclic timer to activate on the first day of each month. 
+
+**Timer Start Event (interrupting):** In a different setting, let's imagine an organization that allows proposal submissions but sets a deadline for a specified date. Here, a 'Start Timer Event' can be used to automatically close the proposal submission form after this date, ensuring no entries are accepted post-deadline. 
+
+**Timer Start Event (non-interrupting):**
+Taking a more customer-centric example, envision an online shopping platform. While a customer browses and adds items to the cart, they might get distracted and forget to check out. To address this, the platform can trigger a 'Non-Interrupting Timer Event' coupled with a subprocess. If the cart remains unattended for an hour, this timer triggers the subprocess, sending an email to the customer reminding them of their abandoned cart. The advantage is that it doesn't disrupt the customer's current session, providing a seamless experience.
+
+## Intermediate Timer Event
+
+![intermediate_timer_event](images/intermediate_timer_event.png) ![non_interrupting_intermediate_timer_event](images/non_interrupting_intermediate_timer_event.png)
+
+An Intermediate Timer Event acts as a pause or delay within the flow of a process.
+The process flow will only continue after the set time has been reached or elapsed.
+Furthermore, as a Boundary Event, it can be linked to specific tasks or sub-processes, potentially interrupting or delaying those tasks based on timing constraints.
+
+**Example:**
+
+![timer_intermediate_example_1](images/start_timer_example_1.png)
+
+**Timer Intermediate Catch Event:** 
+
+The intermediate timer event dictates the timing between stages of a process.
+For example, in the context of baking, once a cake is removed from the oven, it's essential to let it cool properly before decorating.
+This cooling phase ensures that the icing doesn't melt off the hot cake.
+To manage this, an 'Intermediate Timer Event' can be set, signaling a baking process to wait for a standard duration of two hours post-baking before decorating.
+
+Transitioning to a logistics scenario, let's consider a company that processes multiple orders throughout the day.
+They might spend hours collecting items, packaging, and preparing them for shipment.
+However, rather than dispatching each order individually, they follow a batch process strategy, consolidating all orders for a one-time dispatch.
+An 'Intermediate Timer Event' can be configured here to accumulate the day's orders and trigger a batch processing subprocess at a specific time, ensuring efficient and streamlined delivery operations.
+
+**Example:**
+
+![start_timer_example_2](images/start_timer_example_2.png)
+
+**Timer Boundary Event (interrupting):** 
+
+Imagine an online examination system where students have exactly 1 hour to complete the exam.
+A task labeled "Take Exam" will have a timer boundary event attached to it.
+If the exam isn't completed within 60 minutes, the timer boundary event activates, automatically submitting whatever has been completed by the student and ending the exam.
+
+On an e-commerce platform, a product is available at a flash sale price for just 24 hours.
+When customers add this item to their cart, a timer boundary event of 24 hours is set.
+If they don't purchase within this time frame, the timer activates, removing the limited offering.
+
+**Timer Boundary Event (non-interrupting):** 
+
+A company prides itself on responding to customer support queries within 12 hours.
+When a new query is logged, a task named "Respond to Customer" is initiated.
+This task has a timer boundary event set for 12 hours.
+If the customer support team hasn't addressed the query within this time frame, the timer boundary event triggers a notification subprocess to alert the team lead or manager about the overdue response.
+Note that the original task is still active.
+
+**Best Modeling Practices:**
+
+![start_timer_example_3](images/start_timer_example_3.png)
+
+In process automation, ensuring all tasks and processes reach a definitive end is a fundamental aspect of good modeling practice.
+Abandoned or lingering tasks can strain resources and introduce inefficiencies.
+Timer events act as watchdogs, monitoring periods of inactivity and auto-terminating stagnant processes.
+Given the unpredictability of user behavior, integrating timer events is a proactive strategy to ensure no open instances remain.
+
+Looping based on time is also a possible use-case.
+For instance, a system might need to retry a failed task every three minutes until successful.
+Here, the Timer Event ensures that after every 3 minutes, the task is re-attempted.
+Just remember to have a mechanism in place to eventually break out of the loop after a certain number of retries or if another condition is met.
+
+## Timer Event Configuration
+
+| 💻 Form | ⌨ Field Input | 📝 Description |
+| --- | --- | --- |
+| ![name_field](images/name_field.png) | **Name:** Cancel Order | A descriptive name given to the element, providing a human-readable label or title. |
+| ![id_field](images/id_field.png) | **ID:** Example - cancel_order | An identifier used to uniquely identify the element within the BPMN model. |
+| ![timer_field](images/timer_field.png) | **Type:** Duration **Value:** PT48H | Choose the type of trigger you want to set: Specific Date/Time, Duration, or Cycle Trigger. |

docs/index.md

@@ -17,6 +17,9 @@ Building_Diagrams/gateways.md
 Building_Diagrams/events.md
 Building_Diagrams/message_events.md
 Building_Diagrams/signal_events.md
+Building_Diagrams/timer_events.md
+Building_Diagrams/escalation_events.md
+Building_Diagrams/conditional_events.md
 Building_Diagrams/Displaying_Content.md
 Building_Diagrams/Script_Tasks.md
 Building_Diagrams/sub-processes_and_call_activities.md