add message events, pools and lanes, signals (#448)

* add message events, pools and lanes, signals

* changed PNG to png

* corrected png error

---------

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

docs/Building_Diagrams/Displaying_Content.md

@@ -1,4 +1,5 @@
 # Displaying Content
+
 The SpiffArena platform offers powerful features for displaying 
 content  within your BPMN processes.
 Follow the steps below to effectively display content in your 
@@ -12,6 +13,7 @@ Let's dive in and learn the key aspects of displaying content within
 your workflows.
 
 ## Markdown: Formatting Content
+
 Markdown is a powerful tool for formatting and styling your content in 
 SpiffArena. With Markdown, you can easily add headings, lists, tables, 
 hyperlinks, and more to enhance the readability and visual appeal of 
@@ -41,7 +43,7 @@ workflow of the content display process model and discover various
 ways to present content in different scenarios.
 
 
-### Display Content Process Overview:
+### Display Content Process Overview
 
 ![Image](images/Display_Content.png)
 

docs/Building_Diagrams/bpmn.md

@@ -34,7 +34,7 @@ Model not only the primary process flow 'Happy Path' but also the exception hand
 **Use Lanes for Roles and Responsibilities:** 
 Utilize swimlanes (pools and lanes) to clearly define the roles and responsibilities when there are different departments or individuals involved in the process. This visual representation will help demonstrate the interactions and handoffs between role players, enhancing the understanding of their involvement throughout the process.
 
-![pools](images/pools.png) 
+![lanes](images/lanes_1.png) 
 
 **Embrace Iterative Approach:**
 Creating a perfect model in the first attempt is unlikely. Embrace an iterative approach, and be prepared for continuous improvement. Analyze what went wrong in your initial attempts and refine your model accordingly. Understand that your process model is not static. It will evolve over time, and there will always be room for improvement. Stay open to finding better ways to represent the process as you gain more insights.

docs/Building_Diagrams/gateways.md

@@ -2,98 +2,113 @@
 
 Gateways in BPMN are essential for controlling the flow of a business process. They act as decision points where the process flow can diverge into multiple paths or converge back into a single flow. Gateways are used to evaluate conditions or rules and determine the appropriate path for the process to follow. 
 
+**Reasons to use a Gateway:**
+
+- Enable decision points in the process, where different paths are chosen based on conditions.
+- Facilitate parallel processing, allowing multiple tasks or activities to be performed simultaneously.
+- Merge alternate paths together after parallel activities.
+- Handle complex process logic, accommodating various possible scenarios and outcomes.
+- Enhance process interpretation and comprehension by visually illustrating alternative or parallel paths.
+  
 ## Exclusive Gateway
 
-Exclusive Gateway (XOR): An exclusive gateway represents a decision point where only one outgoing sequence flow can be taken. It is used when the process flow needs to make a mutually exclusive choice between different paths. Each outgoing sequence flow has a condition associated with it, and the flow with a true condition is selected.
+![exclusive_gateway](images/exclusive_gateway.png) 
+
+Exclusive Gateway (XOR): An Exclusive Gateway represents a decision point where only one outgoing sequence flow can be taken. It is used when the process flow needs to make a mutually exclusive choice between different paths. Each outgoing sequence flow has a condition associated with it, and the flow with a true condition is selected.
 
 **Default Flow:**
 
-If the default flow is used, the instance will follow the default path whenever the condition on the other paths is not true. In other words, if none of the conditions for the outgoing sequence flows are met, the default flow provides an alternative route for the process to follow. This ensures that the process can still progress even if none of the explicitly defined conditions are satisfied, providing a fallback option for handling unexpected scenarios.
+Whenever the conditions on the other paths aren't met, the instance will proceed via the Default Flow. In other words, if none of the conditions for the outgoing sequence flows are met, the Default Flow provides an alternative route for the process to follow. This ensures that the process can still progress even if none of the explicitly defined conditions are satisfied, providing a fallback option for handling unexpected scenarios.
 
-
-
-![data_input](images/exclusive_gateway_default.png) 
+![exclusive_gateway_default](images/exclusive_gateway_default.png) 
 
 **Challenges:**
-Avoiding conflicting conditions is straightforward when evaluating only one variable that can have only one value (see image 1 below). However, as conditions become more complex, it becomes crucial to carefully structure logical expressions to ensure that only one condition can be true at a time. This becomes especially important when dealing with multiple variables or scenarios that could potentially lead to conflicting conditions.
+Avoiding conflicting conditions is straightforward when evaluating only one variable that can have only one value (see image 1 below). However, with more complex conditions, it's crucial to carefully structure logical expressions ensuring that only one condition can be true at a time. This becomes especially important when dealing with multiple variables or scenarios that could potentially lead to conflicting conditions.
 
-![data_input](images/exclusive_gateway_examples.png) 
+![exclusive_gateway_examples](images/exclusive_gateway_examples.png) 
 
 For example, consider a scenario where multiple variables are involved in a process, and it's possible for more than one variable to be true in the process context (see image 2 above). To guarantee that only one condition will be true, you can use additional expressions, such as "voucher == false" to specify distinct paths for each condition. This ensures that only one branch of the expression will be true, preventing conflicts and providing a clear direction for the process flow (see image 3 above).
 
-In cases where there can be more options to evaluate later, and all options will follow the same route, consider using a default flow. This can be particularly useful when dealing with scenarios where additional payment gateways might be added in the future, but they will all follow the same processing path. By using a default flow, you won't have to modify the expression whenever new payment gateways are added, only if the underlying logic changes (see image 4 above).
+In cases where there might be more options to evaluate later, and all options will follow the same route, consider using a Default Flow. This can be particularly useful when dealing with scenarios where additional payment gateways might be added in the future, but they will all follow the same processing path. You won't have to modify the expression whenever new payment gateways are added, only if the underlying logic changes (see image 4 above).
 
 **Join:**
-To join or merge an exclusive gateway (see image 1 below) is not mandatory; it depends on the specific scenario. When the process encounters the exclusive merge, only one of the incoming sequence flows will be activated, indicating which path was completed first or satisfied its specific condition.
+To join or merge an Exclusive Gateway (see Image 1) is not mandatory; it depends on the specific scenario. When the process encounters the Exclusive Merge, only one of the incoming sequence flows will be activated, indicating which path was completed first or satisfied its specific condition.
 
-While the exclusive merge is commonly utilized alongside the exclusive gateway, it is also compatible with other gateway types in BPMN. It serves as a valuable mechanism for synchronizing and consolidating multiple parallel paths, ensuring that only one path is followed based on the given conditions.
+While the Exclusive Merge is commonly used alongside the Exclusive Gateway, it is also compatible with other gateway types in BPMN. It serves as a valuable mechanism for synchronizing and consolidating multiple parallel paths, ensuring that only one path is followed based on the given conditions.
 
-![data_output](images/exclusive_merge.png)
+![exclusive_merge](images/exclusive_merge.png)
 
-### Inclusive Gateway
+## Inclusive Gateway
 
-Inclusive Gateway (OR): An inclusive gateway also represents a decision point, but it allows multiple outgoing sequence flows to be taken. It is used when the process flow needs to make an inclusive choice, where multiple paths can be followed simultaneously. Each outgoing sequence flow can have a condition associated with it, but even if multiple conditions evaluate to true, all the flows are taken. 
+![inclusive_gateway](images/inclusive_gateway.png) 
+
+Inclusive Gateway (OR): Represents a decision point, but it allows multiple outgoing sequence flows to be taken. It is used when the process flow needs to make an inclusive choice, where multiple paths can be followed simultaneously. Each outgoing sequence flow can have a condition associated with it, but even if multiple conditions evaluate to true, all the flows are taken. 
 
 ```{admonition} Note
-⚠ Note that default flow is not possible with Inclusive Gateways
+⚠ Note that Default Flow is not possible with Inclusive Gateways.
 ```
 
-![data_output](images/inclusive_gateway_mp.png)
+![inclusive_gateway_mp](images/inclusive_gateway_mp.png)
 
 **Challenges:**
-In an inclusive gateway, at least one path should be true for the process to continue. Unlike an exclusive gateway, where only one path can be taken based on the conditions, the inclusive gateway evaluates all incoming sequence flows and enables all the paths for which the conditions are met.
+At least one path should be true for the process to continue. Unlike an Exclusive Gateway, where only one path can be taken based on the conditions, the Inclusive Gateway evaluates all incoming sequence flows and enables all the paths for which the conditions are met.
 
-![data_output](images/inclusive_gateway_conditions.png)
+![inclusive_gateway_conditions](images/inclusive_gateway_conditions.png)
 
-For example, in a career matching system, individuals can input their skillsets, educational qualifications, and work experience. An inclusive gateway can be employed to assess the compatibility of the individual's skillsets with various job roles. The process may diverge into multiple paths, each representing different job categories. For example, some candidates may possess strong problem-solving skills but lack coding proficiency, making them suitable for specific departments that require problem-solving expertise. On the other hand, other candidates might have a combination of problem-solving and coding skills, making them eligible for multiple departments where these skills are essential, the result is not exclusive to one path.
+For example, in a career matching system, individuals can input their skillsets, educational qualifications, and work experience. An Inclusive Gateway can be employed to assess the compatibility of the individual's skillsets with various job roles. The process may diverge into multiple paths, each representing different job categories. For example, some candidates may possess strong problem-solving skills but lack coding proficiency, making them suitable for specific departments that require problem-solving expertise. On the other hand, other candidates might have a combination of problem-solving and coding skills, making them eligible for multiple departments where these skills are essential, this means the result is not exclusive to one path..
 
 **Join:**
 
-The purpose of an inclusive gateway merge is to bring together and merge multiple parallel paths that were previously split by an inclusive gateway. Unlike an exclusive gateway merge, which selects only one path based on conditions, the inclusive gateway merge evaluates all incoming sequence flows and allows all paths with true conditions to proceed. This means that if multiple paths were activated during the parallel execution, all these paths will converge and merge at the inclusive gateway merge.
+The purpose of an Inclusive Gateway merge is to consolidate multiple parallel paths that were previously split. Unlike an Exclusive Gateway merge, which selects only one path based on conditions, the Inclusive Gateway merge evaluates all incoming sequence flows and allows all paths with true conditions to proceed. This means that if multiple paths were activated during the parallel execution, all these paths will converge.
 
-![data_output](images/inclusive_gateway_merge.png)
+![inclusive_gateway_merge](images/inclusive_gateway_merge.png)
 
-It's important to note that the use of an inclusive gateway and its corresponding merge is not mandatory in a process. They can be used independently, depending on the specific scenario and process requirements. In some cases, only the inclusive gateway might be used to split the flow into multiple paths based on different conditions without necessarily requiring a merge later in the process. Similarly, the inclusive gateway merge can be used without an inclusive gateway to consolidate parallel paths from other types of gateways, or even from different parts of the process.
+It's important to note that the use of an Inclusive Gateway and its corresponding merge is not mandatory in a process. They can be used independently, depending on the specific scenario and process requirements. In some cases, only the Inclusive Gateway might be used to split the flow into multiple paths based on different conditions without necessarily requiring a merge later in the process. Similarly, the Inclusive Gateway merge can be used without an Inclusive Gateway to consolidate parallel paths from other types of gateways, or even from different parts of the process.
 
-### Parallel Gateway
+## Parallel Gateway
 
-Parallel Gateway (AND): A parallel gateway is used to split the process flow into multiple parallel paths, allowing concurrent execution of activities. All outgoing sequence flows from a parallel gateway are taken simultaneously, and the process flow continues along all the paths simultaneously.
+![parallel_gateway](images/parallel_gateway.png)
+
+Parallel Gateway (AND): Is used to split the process flow into multiple parallel paths, allowing concurrent execution of activities. All outgoing sequence flows from a Parallel Gateway are taken simultaneously, and the process flow continues along all the paths simultaneously.
 
 Unlike other gateways, a parallel gateway does not dictate the flow based on conditions. Instead, it ensures that all outgoing paths are followed concurrently, regardless of any conditions that may exist. This means that tasks or activities connected to the outgoing sequence flows will be executed simultaneously and independently from one another.
 
 ```{admonition} Note
-⚠ Note that default flow is not possible with Parallel Gateways
+⚠ Note that Default Flow is not possible with Parallel Gateways
 ```
 
-![data_object_reference](images/parallel_gateways.png)
+![parallel_gateways](images/parallel_gateways.png)
 
 **Challenges:**
-Since a parallel gateway does not dictate the flow based on conditions, it avoids conflicts that may arise from complex decision-making logic. 
+Since a Parallel Gateway does not dictate the flow based on conditions, it avoids conflicts that may arise from complex decision-making logic. 
 
 **Join:**
+Note that the behavior for a parallel join, also known as a Parallel Gateway merge, is to synchronize and consolidate multiple parallel paths into a single flow. When the process flow reaches the parallel join, it evaluates the completion of all incoming sequence flows from the corresponding parallel split. It ensures that all parallel paths have completed their execution before the process continues along the single outgoing sequence flow after the join. 
 
-Note that the behavior for a parallel join, also known as a parallel gateway merge, is to synchronize and consolidate multiple parallel paths into a single flow. When the process flow reaches the parallel join, it evaluates the completion of all incoming sequence flows from the corresponding parallel split. The parallel join ensures that all parallel paths have completed their execution before the process continues along the single outgoing sequence flow after the join. 
+## Event-Based Gateway
 
-### Event-Based Gateway
+![event_based_gateway](images/event_based_gateway.png) 
 
-![data_store](images/event_based_gateway.png) 
-
-Event-Based Gateway: An event-based gateway is used to represent a branching point based on events occurring in the process. It is often associated with intermediate events in the process flow. When an event occurs, the gateway determines the subsequent flow based on event definitions and conditions.
+Event-Based Gateway: An Event-Based Gateway is used to represent a branching point based on events occurring in the process. It is often associated with intermediate events in the process flow. When an event occurs, the gateway determines the subsequent flow based on event definitions and conditions.
 
 ## Gateway Configuration
 
-Unlike most tasks, gateways in BPMN are configured on the outgoing sequence flows rather than in the side panel. Each gateway, except for the parallel gateway, requires one or more conditions to be set on the outgoing sequence flows. These conditions determine the path the process flow should take. It's important to note that incoming sequence flows for gateways do not require conditions to be set.
+Unlike most Tasks in BPMN, the configuration for Gateways is primarily set on the outgoing sequence flows, not in the Side Panel. Every Gateway, with the exception of the Parallel Gateway, requires conditions to be established on these outgoing sequence flows. These conditions dictate the direction of the process flow. It's also crucial to understand that conditions aren't required for incoming sequence flows to Gateways.
 
 **Gateway:**
 
 | 💻 Form | ⌨ Field Input | 📝 Description |
 | --- | --- | --- |
-| ![name_field](images/name_field.png) | **Name:** Update Customer Information | An identifier used to uniquely identify the element within the BPMN model. |
-| ![id_field](images/id_field.png) | **ID:** Example - updateCustomerInformation | A descriptive name given to the element, providing a human-readable label or title. |
-| ![name_field](images/documentation_field.png) | **Element Documentation:** URL, Raw Data, Plain Text | Additional information or documentation related to the element, such as URLs, plain text, or raw data. |
+| ![name_field](images/name_field.png) | **Name:** Update Customer Information | A descriptive name given to the element, providing a human-readable label or title. |
+| ![id_field](images/id_field.png) | **ID:** Example - updateCustomerInformation | An identifier used to uniquely identify the element within the BPMN model. |
+| ![documentation_field](images/documentation_field.png) | **Element Documentation:** URL, Raw Data, Plain Text | Additional information or documentation related to the element, such as URLs, plain text, or raw data. |
 
 **Outgoing Sequence:**
 
+```{admonition} Note
+⚠ All expressions, including expressions written on the outgoing sequence, are written in Python.
+```
+
 | 💻 Form | ⌨ Field Input | 📝 Description |
 | --- | --- | --- |
-| ![name_field](images/conditions.png) | **Condition:** payment_method == "credit_card" | Pyhton expression. Note that multiple conditions can be strung together using AND/OR |
+| ![conditions](images/conditions.png) | **Condition:** payment_method == "credit_card" | Python expression. Note that multiple conditions can be strung together using AND/OR. |

docs/Building_Diagrams/message_events.md

@@ -0,0 +1,123 @@
+# Message Event
+
+A Message Event acts as a channel for the exchange of information between different process participants or external systems. While it might be tempting to associate "message events" with emails, their scope extends beyond digital correspondence. It signifies the transmission of information between various process components, whether within the same process or across different processes.
+
+ ![message_relationship](images/relationship_message.png) 
+
+**Reasons to Use a Message Event:**
+
+- Message Events model scenarios where processes interact with external entities or systems for information exchange.
+- They initiate specific actions by sending or receiving an event within the process flow.
+- Visually, they illustrate communication among various participants or across different pools and lanes.
+- They clarify how data or events are shared, fostering collaboration among different business process components.
+
+ 
+## Start Message Event
+
+![start_message_event](images/start_message_event_1.png) 
+
+A Message Start Event serves as a starting point for a process, activated specifically by a message received from another process or external system.
+
+![message_event_example_4](images/msg_event_example_3.png) 
+
+In the given example, a process can be initiated either by a message from an external system or by capturing a throw event from another process.
+
+```{admonition} Note
+In a subsequent example, it's clarified that message events can span multiple BPMN diagrams and are not confined solely to lanes and pools as illustrated in the initial example.
+```
+
+## Intermediate Message Throw Event
+
+![intermediate_throw_message_event](images/intermediate_throw_msg_event.png)
+
+An Intermediate Throw Event sends a message from within the process to a receiver. When the process execution reaches this event, it triggers a message event that can be captured by a corresponding Message Catch Event in another process or by an external system.
+
+![message_event_example_4](images/msg_event_example_2.png) 
+
+In the example provided, once a quote is finalized, the sales team forwards a formal quotation. Similarly, upon receiving a purchase order from the customer, the sales department generates an order confirmation receipt and sends it to the customer.  
+
+## Intermediate Message Catch Event
+
+![intermediate_catch_message_event](images/intermediate_catch_msg_event.png)
+
+An Intermediate Catch Event is used to wait for and capture a specific message from another source. Once activated upon receiving the designated message, it allows the process flow to continue from that point onward. It's crucial to understand that the process instance remains in a waiting state until triggered by another source or process. This fundamental distinction sets Intermediate Catch Events apart from Intermediate Throw Events, as Catch Events exclusively await external triggers, while Throw Events initiate those triggers.
+
+![message_event_example_5](images/msg_event_example_5.png) 
+
+Alternatively, Message Events can be utilized beyond the confines of pools and lanes. The process outlined in the previous section can be split into two distinct BPMN files without affecting its functionality, as demonstrated in the example above.
+
+```{admonition} Note
+⚠ It should be noted that, in this situation, connectors cannot visually represent the link between the throw and catch events. Further in this document, the topic of correlation is discussed to clarify how these events are interconnected
+```
+
+In the given example, there are two Intermediate Catch Events. One waits for confirmation from the customer, and the other depends on the shipping department's verification of dispatch before producing the invoice. Without feedback from both the customer and the shipping department at this stage, the process instance won't move to the subsequent step.
+
+```{admonition} Note
+⚠ While it is generally true that most Throw Events have corresponding Catch Events, it is not an absolute rule. The need for a Catch Event alongside a Throw Event varies depending on the specific scenario and the requirements of the process. There may be cases where a Throw Event initiates an action without requiring a subsequent Catch Event to capture its effects. The decision to use a Catch Event in conjunction with a Throw Event is determined by the requirements of the particular process.
+```
+
+## End Message Event
+
+![end_message_event](images/end_msg_event.png) 
+
+This type of event signifies the completion of a process and indicates that a message is sent to an external recipient to notify them of the process's conclusion. It serves as the endpoint of the process and sends a message when the process reaches this event.
+
+![message_event_example_4](images/msg_event_example_4.png) 
+
+Please note that the End Event when using pools, signifies the conclusion of the process within that specific pool, but it does not necessarily indicate the end of the entire process. In the provided example, the final step involves sending the customer an invoice. Prior to this, the last step for the shipping department was to send a confirmation. 
+
+```{admonition} Note
+⚠ Start Events mark the initiation point of a process. Intermediate Events occur during the course of the process, throwing, capturing and reacting to specific occurrences or messages from external sources or other processes. On the other hand, End Events denote the conclusion of the process, signifying its termination or reaching a final state.
+```
+
+## Correlation
+
+A singular Throw Message Event corresponds exclusively to a single active Catch Message Event. This correlation is one-to-one, unlike Signal Events that could be sent to multiple active Signal Catch Events. It is important to configure the correlation of the Catch and Throw Events.
+
+
+## Message Event Configuration
+
+3 seperate configurations needs to be completed. 
+
+- Collaboration
+- Throw Message Event
+- Catch Message Event
+  
+
+**Default configuration:**
+
+| 💻 Form | ⌨ Field Input | 📝 Description |
+| ------------------------------------------------------------- | --- | --- |
+| ![name_field](images/name_field.png) | **Name:** Place Order | A descriptive name given to the element, providing a human-readable label or title. |
+| ![id_field](images/id_field.png) | **ID:** Example - send_invoice | An identifier used to uniquely identify the element within the BPMN model.|
+| ![documentation_field](images/documentation_field.png) | **Element Documentation:** URL, Raw Data, Plain Text | Additional information or documentation related to the element, such as URLs, plain text, or raw data. |
+
+**Collaboration:**
+
+![collaboration](images/collaboration_msg.png) 
+
+The identical configuration must be applied to every BPMN diagram if messages extend across multiple diagrams.
+
+| 💻 Form | ⌨ Field Input | 📝 Description |
+| --- | --- | --- |
+| ![correlation_keys](images/correlation_keys_1.png) | **Correlation Keys:** order | A correlation key is a unique identifier or attribute used to establish a connection or relationship between message events (it can be likened to the shared subject between them). It is possible to have multiple correlation keys for a process.
+| ![correlation_properties](images/correlation_properties_1.png) | **Correlation Properties:** invoice_number | The correlation property is what differentiates each key instance from another, and it's the defining attribute that sets them apart. For instance, if "order" is selected as the correlation key, a property like "invoice_number" could be used to distinguish each order instance from another. Keep in mind that this variable should be incorporated within the context of the process instance.|
+| ![collaboration_messages](images/collaboration_messages_1.png) | **Messages:** order_approval, order_dispatch etc. | Messages are established for each message pair (Throw and Catch Message Events). This setup will be utilized to configure the events, linking the associated occurrences together. |
+
+**Throw Message Event:**
+
+| 💻 Form | ⌨ Field Input | 📝 Description |
+| --- | --- | --- |
+| ![conditions](images/message_1.png) | **Message:** order_approval | This input isn't an open-text field; instead, it provides a dropdown list populated by the Messages configured in the preceding Collaboration section.|
+| ![conditions](images/payload_msg.png) | **Payload:** order_amount | The Payload can include a variable, holding unique information specific to the instance, or in this scenario, the order. |
+| ![conditions](images/event_correlation_msg.png) | **Correlation:** invoice_number | Select the correlation that can identify the distinct property distinguishing one process instance from another. |
+
+**Catch Message Event:**
+
+The connected catch event is configured in precisely the same manner as the throw event
+
+| 💻 Form | ⌨ Field Input | 📝 Description |
+| --- | --- | --- |
+| ![conditions](images/message_1.png) | **Message:** order_approval | This input isn't an open-text field; instead, it consists of a dropdown list populated by the Messages configured in the preceding Collaboration section.|
+| ![conditions](images/payload_msg.png) | **Variable Name:** order_amount | The Variable Name can include a variable, holding unique information specific to the instance, or in this scenario, the order. |
+| ![conditions](images/event_correlation_msg.png) | **Correlation:** invoice_number | Select the correlation that can identify the distinct property distinguishing one process instance from another. |

docs/Building_Diagrams/pools_and_lanes.md

@@ -0,0 +1,66 @@
+# Pools and Lanes
+
+A Pool represents a participant and can be seen as a self-contained process. This participant can be an internal entity (e.g., a department within a company) or an external entity (e.g., a customer or another company). Lanes are helpful in highlighting which specific role or department is responsible for certain activities or tasks in a process. A process can have one or more Pools, each with one or more Lanes.
+
+**Reasons to Use Pools and Lanes:**
+
+- They visually represent distinct participants in a process, such as various departments, organizations, or systems.
+- Helps depict interactions between separate business entities, like a buyer-seller dynamic.
+- Provide a clear overview of communication between different participants.
+- Categorizing tasks or activities based on specific roles.
+- Bring structure and organization to complex diagrams that involve multiple roles, departments, or stakeholders.
+
+ 
+## Pools
+
+A Pool can be configured as an "Empty Pool" (collapsed) or an "Expanded Pool". You can choose the desired configuration 🔧 from the element's options after dragging it onto your diagram.
+
+![pools_and_lanes](images/pools_and_lanes_1.png) 
+
+Empty Pools are used to represent role players in cases where a specific process is neither known nor required, but the interaction points remain valuable. They serve to illustrate the engagement of certain entities without detailing their internal processes, for example, we dont know a customers specific process but it matters when we interact with them to complete our process.
+
+Conversely, Expanded Pools are employed when the processes are known and hold relevance within the diagram's context. 
+
+## Lanes
+
+Lanes group activities within a single Pool, usually signifying different roles or departments. 
+
+![lanes](images/lanes_1.png)
+
+Lanes are incorporated into Pools when the roles they represent belong to the same entity. However, if a process doesn't logically fit within the same Pool, like those for different organizations or businesses, it's more appropriate to represent it as a separate Pool rather than another Lane.
+
+![lanes](images/separate_pools_1.png)
+
+## Configuration
+
+![participant_configuration](images/participant_configuration_1.png)
+
+**Collapsed (Empty) Pool configuration:**
+
+Configuring an "Empty Pool" (collapsed) representing an external entity such as a customer.
+
+| 💻 Form | ⌨ Field Input | 📝 Description |
+| --- | --- | --- |
+| ![participant_sales](images/participant_customer_1.png) | **Participant Name:** Sales, **Participant ID:** sales, | A clear and descriptive name serves as a human-readable label or title the participant. Additionally, a unique ID is essential to distinguish the participant from other participants. |
+| ![data_object_pools](images/data_object_pools_1.png) | **Data Objects:** order_details | Create or Refernce a Data Object to store information for sharing between entities. |
+
+**Expanded Pool configuration:**
+
+Setting up an "Expanded Pool" requires referencing the process, in contrast to the setup of an empty pool.
+
+| 💻 Form | ⌨ Field Input | 📝 Description |
+| --- | --- | --- |
+| ![participant_sales](images/participant_sales_1.png) | **Participant Name:** Sales, **Participant ID:** sales,  **Process ID:** process_order, **Process Name:** Process Order | A clear and descriptive name serves as a human-readable label or title for both the participant and the process. Additionally, a unique ID is essential to distinguish both the participant and the process from others. |
+| ![data_object_pools](images/data_object_pools_1.png) | **Data Objects:** order_details | Create or Refernce a Data Object to store information for sharing between entities. |
+
+**Collapsed Pool configuration:**
+
+![lanes](images/lane_configuration_1.png)
+
+Remember that each pool requires Lane configuration, even if it contains just a single Lane.
+![lanes](images/pool_settings_1.png)
+
+| 💻 Form | ⌨ Field Input | 📝 Description |
+| --- | --- | --- |
+| ![participant_sales](images/participant_lane_1.png) | **Name:** Manager | A concise and descriptive label that accurately represents the owner and role of the Lane. |
+| ![data_object_pools](images/data_object_pools_1.png) | **ID:** lane_manager | A distinct ID to differentiate each Lane, especially when there are multiple.|

docs/Building_Diagrams/sub-processes_and_call_activities.md

@@ -2,17 +2,17 @@
 
 Sub-processes and call activities are both useful for simplifying and organizing complex workflows within larger processes. They have distinct purposes and are used in different scenarios.
 
-**Reasons to use a Sub-Process or Call Activity:**
+**Reasons to use Sub-Processes or Call Activities:**
 
-- Consolidating tasks with common features or forming a distinct functionality, such as a Notification Gateway that constructs and sends notifications like emails.
-
-- Grouping tasks where a boundary event can efficiently be applied to the entire group, avoiding the need to assign conditions or timers individually to each task.
+- Consolidate tasks that have either common features or collaboratively form a distinct functionality. For instance, a Notification Gateway, which includes script tasks and a service task, works together to construct and send a notification like an email.
+  
+- Group tasks where a Boundary Event can be efficiently applied to the entire group. For instance, instead of individually assigning a condition or timer to each task, all tasks can be included within a sub-process or call activity, where the condition or timer inherently applies to all contained tasks.
 
 ## Call Process
 
 ![active_call_process](images/active_call_process.png)
 
-A call process encapsulates part of a workflow and can be reused across multiple processes. It functions as a stand-alone process that can be called into action by other processes. Using a call process eliminates redundancy and ensures consistent execution of process steps.
+A Call Process is similar to a Sub-Process in that it encapsulates part of a workflow, but it is designed to be reused across multiple different processes. It's essentially a stand-alone process that can be "called" into action as required by other processes. Using a Call Process can help to eliminate redundancy and ensure consistent execution of the process steps.
 
 **When to use a Call Process:**
 
@@ -28,14 +28,10 @@ A call process encapsulates part of a workflow and can be reused across multiple
 
 ## Sub-Processes
 
-![active_subtask](images/active_subprocess.png)
-
-Sub-processes are typically used within a single process and are not reusable across multiple processes like call activities. When the conditions for reusability are not necessary, a sub-process is usually the preferred option.
-
 **When to use a Sub-Process:**
 
-- **Consolidating Similar Functionalities:** When a group of tasks are closely related and work well together, but do not need to be used or replicated elsewhere in other processes.
-
-- **Not Requiring a Call Activity:** When tasks do not meet the conditions required for a call activity, a sub-process can achieve the same goal.
-
-- **Applying Conditions or Events:** When specific conditions or events, such as a timer event, need to be applied to a set of tasks that do not collectively form a reusable workflow that can be called as a separate process.
+- **Consolidate similar functionalities:** When you have a group of tasks that are closely related and work well together, but don't need to be used or replicated elsewhere in other processes. 
+  
+- **Call Activity is not required:** When these tasks don't meet the conditions needed for a call activity a sub-process can achieve the same goal.
+  
+- **Conditions or events needs to be applied:** When specific conditions or events, such as a timer event, need to be applied to a set of tasks, but these tasks do not collectively form a reusable workflow that can be called as a separate process. 

docs/Support/suspend_resume_terminate.md

@@ -2,7 +2,7 @@
 
 | ⚙ How do I get there \| Menu Hierarchy |
 | -------------------------------------- |
-| Follow steps to [find a process instance](../spiffsparkles/find_a_process_instance.md)  |
+| Follow steps to find a process instance |
 
 
 ## Suspend a Process
@@ -11,7 +11,7 @@ By suspending a process instance, you temporarily halt its execution, allowing y
 
 > **Step 1: Find the Active Process Instance**
 
-- In order to locate the active process instance, have a look at these pages to [find an instance](../spiffsparkles/find_a_process_instance.md) to suspend.
+- In order to locate the active process instance, have a look at these pages to find an instance to suspend.
 
 ```{admonition} Note
 

docs/index.md

@@ -13,13 +13,15 @@ Getting_Started/quick_start.md
 Building_Diagrams/Using_SpiffArena.md
 Building_Diagrams/learn_basics.md
 Building_Diagrams/bpmn.md
-Building_Diagrams/Displaying_Content.md
 Building_Diagrams/Forms.md
 Building_Diagrams/gateways.md
+Building_Diagrams/message_events.md
+Building_Diagrams/Displaying_Content.md
 Building_Diagrams/Script_Tasks.md
 Building_Diagrams/sub-processes_and_call_activities.md
 Building_Diagrams/data_objects.md
 Building_Diagrams/dmn.md
+Building_Diagrams/pools_and_lanes.md
 ```
 
 ```{toctree}
@@ -37,20 +39,12 @@ DevOps_installation_integration/permission_url.md
 DevOps_installation_integration/configure_connector_proxy.md
 DevOps_installation_integration/deploy_aws_lambda.md
 ```
+
 ```{toctree}
 :maxdepth: 1
 :caption: Support
 Support/suspend_resume_terminate.md
 ```
-```{toctree}
-:maxdepth: 1
-:caption: SpiffSparkles
-spiffsparkles/find_a_process_instance.md
-spiffsparkles/navigate_to_an_active_process_instance.md
-spiffsparkles/complete_task_on_behalf_of_another_user.md
-spiffsparkles/assign_task_to_a_different_user.md
-spiffsparkles/process_instance.md
-```
 
 ```{toctree}
 :maxdepth: 1

docs/spiffsparkles/assign_task_to_a_different_user.md

@@ -1,84 +0,0 @@
-# Assign Task to a Different User
-
-| ⚙ How do I get there \| Menu Hierarchy |
-| -------------------------------------- |
-| Follow steps to [find a Process Instance](../spiffsparkles/find_a_process_instance.md)|
-
-A task is typically allocated to a specific user, who is then tasked with its completion. However, there could be various scenarios where the user might not be able to complete the task within the set timeframe. In such instances, the task can be **reassigned to a different user**. This facilitates a seamless continuation of the process from where the initial user left off, enabling them to proceed with the next task when they're prepared.
-
-## Change Lane Owner
-
-> **Step 1: Find 'Process Instance'**
-
-- The process instance will be assigned to another user and the task can be found by seraching for the Id in the ['Find By Id'](../spiffsparkles/find_a_process_instance.md) tab.
-
-![assigned_to_me](images/assigned_to_me.png)
-
-> **Step 2: Navigate to the Active Process Id**
-
-Follow steps to [navigate to the Active Process Instance.](../spiffsparkles/navigate_to_an_active_process_instance.md)
-
-
-```{admonition} Note
-⚠ The task needs to be active for you to be able to amend it. Completed process instances can not be resumed at a previous point.
-```
-
-> **Step 3: Suspend the Process Instance**
-
-Follow steps to [suspend process.](../Support/suspend_resume_terminate)
-
-```{admonition} Note
-⚠ Note: Only Admin users will be able to complete this step.
-```
-
-> **Step 4: Find Previous Active Task**
-
-- Identify the particular task within the workflow. It's generally located before the currently active task and prior to the lane where the task gets assigned to the lane owner.
-
-- Click on this task to trigger a popup menu,
-- Select the option "View process instance at the time when this task was active."
-![previous_active_state](images/previous_active_state.png)
-
-The activity is now highlighted in yellow. This means that this was the view of the activity when it was active. 
-
-> **Step 5: Reset Process**
-
-The activity needs to be reset to its previous active state to enable the changes required by the Admin. 
-
-- Click on the previous active task and select 'Reset Process Here'.
-
-> **Step 6: Edit Task Data**
-
-- Click on the now active activity then click "Edit"
-
-> **Step 7: Change Lane Owner**
-
-> Change the Lane Owner Property from the current owner to new owner.
-
-```Python
-"lane_owners": {
-	"Approver": [
-		"newuser@spiffworkflow.com"
-	]
-}
-```
-
-> **Step 8: Save Instance**
-
-- Click "Save" to apply field changes to the Instance.
-
-> **Step 7: Execute Task**
-
-- Select to "Execute Task". This will execute the user task with applied changes.
-
-> **Step 8: "Resume" process instance.**
-
-- Follow steps to [resume process.](../Support/suspend_resume_terminate)
-
-> **Step 9: Refresh page**
-
-- After a few seconds, refresh the page to ensure that the workflow has progressed to the next activity
-
-| ✅ Success                                                    |
-| ------------------------------------------------------------ | 
-| With the current activity successfully completed and the workflow advanced to the next stage, the remaining steps of the process can now smoothly proceed. | 

docs/spiffsparkles/complete_task_on_behalf_of_another_user.md

@@ -1,57 +0,0 @@
-# Complete Task on Behalf of another User
-
-| ⚙ How do I get there \| Menu Hierarchy |
-| -------------------------------------- |
-| Follow steps to [find a Process Instance](../spiffsparkles/find_a_process_instance.md)|
-
-A task is assigned to a user who is responsible for completing it. However, due to various reasons, the user may find themselves unable to finish the task within the designated time frame. In such situations, the instance can be completed **by you on behalf of the user.** This enables a smooth continuation of the process from the initial user's perspective, allowing them to move on to the next task when they are ready.
-
-## Complete Task assigned to a different user
-
-> **Step 1: Find 'Process Instance'**
-
-- The process instance will be assigned to another user and the task can be found by seraching for the Id in the ['Find By Id'](../spiffsparkles/find_a_process_instance.md) tab.
-
-![assigned_to_me](images/assigned_to_me.png)
-
-> **Step 2: Navigate to the Active Process Id**
-
-Follow steps to [navigate to the Active Process Instance.](../spiffsparkles/navigate_to_an_active_process_instance.md)
-
-
-```{admonition} Note
-⚠ The task needs to be active for you to complete it. Completed process instances can not be edited or modified.
-```
-
-> **Step 3: Suspend the Process Instance**
-
-Follow steps to [suspend process.](../Support/suspend_resume_terminate)
-
-```{admonition} Note
-⚠ Note: Only Admin users will be able to complete this step.
-```
-
-> **Step 4: Edit selected Task**
-
-- Click on the active task, which is highlighted in yellow. 
-- Select "Edit" from the pop-up screen. A window, or code editor, will open up displaying the task data. Here, you can both view and edit the data as needed. For this step in the process, it's important to know which task data variables you need to change. This knowledge is necessary to ensure that the correct data is modified and the process continues as expected.
-
-> **Step 5: Save Instance**
-
-- Click "Save" to apply field changes to the Instance.
-
-> **Step 6: Execute Task**
-
-- Select to "Execute Task". This will execute the user task with applied changes.
-
-> **Step 7: "Resume" process instance.**
-
-- Follow steps to [resume process.](../Support/suspend_resume_terminate)
-
-> **Step 8: Refresh page**
-
-- After a few seconds, refresh the page to ensure that the workflow has progressed to the next activity
-
-| ✅ Success                                                    | 🚫 Error                                                      |
-| ------------------------------------------------------------ | ------------------------------------------------------------ |
-| The system will then display the parent process that contains the active instance searched for. | What if this was not successful. Add section to troubleshoot?

docs/spiffsparkles/find_a_process_instance.md

@@ -1,64 +0,0 @@
-# Find an Instance
-
-| ⚙ How do I get there \| Menu Hierarchy |
-| -------------------------------------- |
-| Process Instances > For me             |
-
-## Assigned to myself
-
-> **Step 1: Go to 'Process Instance' tab****
-
-- To find a process instance assigned to you, you can access the Process Instance tab.
-
-![process_instance_tab](images/process_instance_tab.png) 
-
-> **Step 2: Browse list**
-
-- Look for the option labeled "For me" and select it. This will provide you with a list of User Tasks assigned to you.
-
-```{admonition} Note
-⚠ **Apply a filter if the Instance can not easily be located**.
-```
-
-![assigned_to_me](images/assigned_to_me.png) 
-
-> **Step 3: Select Instance**
-
-- Select the associated entry from list.
-- You will be redirected to the process instance selected. 
-- *Apply a filter if the Instance can not easily be located**.
-
-| ✅ Success                                                    | 🚫 Error                                                      |
-| ------------------------------------------------------------ | ------------------------------------------------------------ |
-| The system will then display the parent process that contains the active instance searched for. | What if this was not successful. Add section to troubleshoot?
-
----
-
-| ⚙ How do I get there \| Menu Hierarchy |
-| -------------------------------------- |
-| Process Instances > By Id             |
-
-## By Id
-
-If a process is not in your designated queue, it may be assigned to someone else. Generally, finding a process instance by its Id is useful to locate and view the progress of any process instance.
-
-> **Step 1: Go to 'Process Instance' tab**
-
-- To find a specific process instance, you can access the Process Instance tab.
-
-![process_instance_tab](images/process_instance_tab.png) 
-
-> **Step 2: Select "Find by Id"**
-
-- Look for the option labeled "Find by Id" and select it. This will provide you with a field where you can enter the Process Instance Id number associated with the instance you are looking for.
-
-![find_by_id](images/find_by_id.png) 
-
-> **Step 3: Select Instance**
-
-- Once you have entered the Id, click on the "Submit" button to initiate the search. 
-
-| ✅ Success                                                    | 🚫 Error                                                      |
-| ------------------------------------------------------------ | ------------------------------------------------------------ |
-| The system will then display the parent process that contains the instance searched for. | What if this was not successful. Add section to troubleshoot? ![cant_find_process_instance](images/cant_find_process_instance.png)|
-

docs/spiffsparkles/navigate_to_an_active_process_instance.md

@@ -1,57 +0,0 @@
-# Navigate to a Process Instance
-
-| ⚙ How do I get there \| Menu Hierarchy |
-| -------------------------------------- |
-| Follow steps to [Find a Process Instance](../spiffsparkles/find_a_process_instance.md) |
-
-If you can't find the desired task or process you wish to view in the parent or primary process, it's likely that you need to access a sub-process or call activity.
-
-## Inside a Sub-Process
-
-> **Step 1: Locate the Current Active Sub-task**
-
-You might be interested in a process instance that you've specifically searched for, or one that is currently assigned to you. However, when you attempt to view the instance, it might be in a waiting state, denoted by a sub-process highlighted in yellow.
-
-> **Step 2: Select the Link**
-
-- Select the blue arrow located at the bottom right of the highlighted activity, which is indicated in yellow.
-
-![active_subtask](images/active_sub_task.png)
-
-```{admonition} Note
-⚠ Note: This method can also be applied to a process instance that has already been completed.
-```
-
-![inactive_subtask](images/inactive_subtask.png) 
-
-| ✅ Success |  
-|  :----:  | 
-| You will be navigated to the corresponding diagram. Continue to repeat the aforementioned steps until the highlighted activity is neither a call activity nor a sub-process. At this point, you'll be at the lowest level of the active process.|
-
-## Inside a Call Activity
-
-> **Step 1: Locate the Current Active Call Process**
-
-You might be interested in a process instance that you've specifically searched for, or one that is currently assigned to you. However, when you try to access the instance, it might be waiting within a 'call activity', identifiable by a Call Activty highlighted in yellow.
-
-> **Step 2: Select the Activity**
-
-- Select the highlighted activity, indicated in yellow.
-
-![active_call_activity](images/active_call_activity.png)
-
-```{admonition} Note
-⚠ Note: This method can also be applied to a process instance that has already been completed.
-
-```
-
-> **Step 3: Confirm Redirect**
-
-- A popup message will appear. Select "View Call Activity Diagram" to navigate to the child process of the current view.
-
-![call_activity_popup](images/call_activity_popup.png) 
-
-| ✅ Success |  
-|  :----:  | 
-| You will be navigated to the corresponding diagram. Continue to repeat the aforementioned steps until the highlighted activity is neither a call activity nor a sub-process. At this point, you'll be at the lowest level of the active process.|
-

docs/spiffsparkles/process_instance.md

@@ -1,48 +0,0 @@
-# What is a Process Instance
-
-A process instance refers to a specific occurrence. Think of a process instance as an individual journey through a predefined set of steps and rules that make up a larger process. For example, let's consider a purchase order process. Each time a purchase order is initiated and goes through the required steps, such as approval, payment, and fulfillment, it represents a distinct process instance and will have a specific id and data specific to the instance. 
-
-Each Process Instance would have started at the starting point and moved on to subsequent steps. The data it collects along its path is unique to that instance. You therefor have to know how to locate a process instance. 
-
-Follow the steps in this page to understand how to locate a process instance:
-
-- [Find a process instance](../spiffsparkles/find_a_process_instance.md)
-
-## ℹ Information associated with an instance
-
-| Field Name | Description |
-|------------|-------------|
-| **Started By** | Specifies the initiator or originator of the process instance. wWould usually be a a username or email. |
-| **Current Diagram** | Specifies the current diagram where the active process instance can be found. |
-| **Started** | The timestamp of when the parent process was started.|
-| **Updated At** | Specifies the current diagram where the active process instance can be found. |
-| **Process model revision** | The timestamp of when the parent process was started.|
-| **Status** | Specifies the current diagram where the active process instance can be found.|
-
----
-
-## ✅ Statuses
-
-The status of a process instance represents its current state or condition, reflecting its progress and execution. The process status is not necessarily bound to a chronological order and can transition between multiple statuses over time.
-
-| Status    | Image     | Description |
-|-----------|-----------------|-------|
-| **User input required** |![Image description](images/user_input_required.png) |  When a process instance reaches a user task or a point in the process where user input is necessary, the status is set to "User input required." This status indicates that the process cannot proceed further until the user provides the required information or completes the assigned task.   |
-| **Terminated**     | ![Image description](images/terminated.png)|Once a process instance is terminated, it moves into a "terminated" state. This means that it won't resume its execution, and all associated tasks, sub-processes, and jobs are also ended.|
-| **Completed**     |     ![Image description](images/completed.png)              | Once a process instance is completed, it moves into a "completed" state. This indicates that all the tasks and activities associated with that process instance have been completed.      |
- | **Suspended**   |![Image description](images/suspended.png)              | During the suspension period, the process instance remains in a state of temporary pause, and the execution is halted. Once the cause of the suspension is resolved, the process instance can be manually updated to reflect a new location or metadata. [A suspened process can be resumed.](../Support/suspend_resume_terminate.md) |
-| **Error**     |                  |  An error indicates that a process instance has encountered an error or exception during its execution. It signifies that there is an issue or problem that needs to be addressed before the process can proceed further.   |
-
----
-
-## 🚫 Errors
-
-When a process instance encounters an error, it is typically unable to continue executing as intended. The error could be caused by various factors, such as:
-
-**Validation Failure:** If the process instance fails to meet certain validation criteria or encounters invalid data, it may result in an error status.
-
-**System or Service Failure:** Errors can occur if there are technical issues with the underlying systems or services that the process relies upon. These could include connectivity problems, server failures, or service unavailability.
-
-**Business Rule Violation:** If a process instance violates a predefined business rule or policy, it may trigger an error status.
-
-**Exception Handling:** Certain exceptional scenarios, such as unexpected conditions or exceptional events, can lead to errors within the process instance.