Bpmn_section (#412)

* how to and spiff sparkles

* how to and spiff spiffsparkles

* rename  data_object_properties.png

* change name images/data_object_prop.png

* downcase png files

---------

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

docs/appendices/bpmn_references.md

@@ -1,28 +0,0 @@
-# Decision Tables
-
-```{tip} 
-:class: note
-🧾 Read more about Data Objects [here](https://medium.com/@danfunk/understanding-bpmns-data-objects-with-spiffworkflow-26e195e23398).
-```
-
-DMN tables are powerful tools for modeling and implementing business rules and decision logic. They allow you to define rules and their associated conditions and actions in a structured manner. By evaluating the conditions in each rule, the DMN engine can determine which rules are triggered based on the provided inputs and execute the corresponding actions. This provides a flexible and configurable approach to decision-making in various scenarios.
-
-A DMN (Decision Model and Notation) table consists of several components that help define the decision logic and structure the decision-making process. The main components of a DMN table are:
-
-## DMN Components
-
-- **Input Variables:** These are the variables that represent the information or data used as input for the decision. Each input variable is typically represented as a column in the table. Multiple columns represent multiple input variables.
-- **Conditions:** Conditions specify the criteria or constraints that need to be evaluated for each input variable. They define the rules or expressions that determine when a particular decision rule should be triggered. Conditions are usually represented in the "When" column of the table.
-- **Actions or Expressions:** Actions or expressions define the operations or calculations that are executed when a specific rule is triggered. They represent the logic associated with the decision outcome and are represented in the same row as the conditions in the table.
-- **Decision Rules:** Decision rules are the individual rows in the DMN table. Each rule represents a specific combination of conditions and actions that define the behavior or logic for a particular scenario. Decision rules combine the input conditions and output actions in a structured manner.
-- **Hit Policy:** The hit policy determines how the decision engine selects or combines the applicable decision rules when multiple rules are triggered. It defines the behavior for resolving conflicts or overlaps between rules. Common hit policies include "First," "Unique," "Priority," "Any," and "Collect."
-
-## Hit Policy
-
-**Unique:** Only one rule can match the given inputs. If multiple rules match, it results in an error or an undefined outcome. This policy ensures that only one result is produced.
-
-**First:** The first rule that matches the inputs is selected, and its corresponding output is returned. Other matching rules are ignored. This policy is useful when you want to prioritize the order of rules.
-
-**Collect:** All rules that match the inputs are selected, and the outputs from those rules are collected and returned as a list or a collection. This policy allows for gathering multiple results.
-
-

docs/bpmn/bpmn.md

@@ -0,0 +1,56 @@
+# How to create a BPMN diagram
+
+When starting to model a business process, it can indeed be a challenging task, especially when multiple departments and users are involved. Here are some helpful tips to guide you through the process and create effective process models: 
+
+**Understand BPMN Symbols:**
+Begin by thoroughly understanding the meaning and usage of each BPMN symbol. This will ensure that you use the symbols correctly to represent the various elements of your business process. Refer to the [Learn Basics](../learn_basics/bpmn_terminology.md) section to learn more about each symbol.
+
+Grouping it together can create a mindmap thats easy to remember.
+
+- Flow Objects
+- Connecting Objects  
+- Swimlanes  
+- Artifacts
+
+**Model Left to Right:** 
+Follow the convention of modeling from left to right. Represent your main process flow, also known as the "Happy Path," at the top in a straight line. Then, depict alternative scenarios and exceptional cases leading to the bottom. This makes the process flow easier to comprehend.
+
+![model_convention](images/model_convention.png) 
+
+**Choose Descriptive Names:** 
+Use clear and human-readable names for activities, events, and gateways in your process. Utilize action verbs to represent activities effectively. Start the task name with an action-oriented verb that indicates what needs to be done in the task. For example, "Approve Request," "Review Documents," "Send Invoice," etc.
+![naming_convention](images/naming_convention.png) 
+
+**Start with High-Level Overview:** 
+Beginning with a high-level overview of the process provides a clear understanding of the overall flow and allows for the identification of major process components before delving into finer details. By breaking the process down into smaller subprocesses or call activities with different levels of detail, the model becomes more manageable and easier to comprehend. This approach enables the use of placeholders where you are unclear of what the process looks like, allowing for flexibility in filling in missing information as it becomes available. It also facilitates the focus on specific sections, preventing feeling overwhelmed by the complexity of the entire process. This systematic approach to process modeling ensures that essential aspects are adequately captured while providing room for further refinement. 
+
+![high_level](images/high_level.png) 
+
+**Include Exception Handling:** 
+Model not only the primary process flow 'Happy Path' but also the exception handling and error recovery paths. This makes the process model more robust and prepares stakeholders for potential challenges.
+
+![out_of_stock](images/out_of_stock.png) 
+
+**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) 
+
+**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.
+
+![version](images/version.png) 
+
+**Make note of Assumptions and possible challenges:** 
+During the modeling process, it is essential to clearly document any assumptions made, especially when you may not have complete knowledge of user behavior or real-life process dynamics. By documenting these assumptions, you provide context and ensure transparency when sharing the model with others. Remember to verify these assumptions during real-life testing to validate their accuracy and adjust the model accordingly.
+
+![version](images/assumptions.png) 
+
+**Example:**
+Initially, we assumed that every customer going to checkout would complete their payment. However, in reality, we observed that customers often abandoned their carts without completing the purchase. To address this issue, we implemented an email reminder to prompt customers to return and complete their purchase. While this approach improved the number of abandoned carts, it didn't completely resolve the problem. Upon further analysis, we recognized that certain customers might never return, leading us to make the decision to automatically close their carts. This action ensures that our inventory accurately reflects the available items and helps maintain inventory accuracy.
+
+**Involve Team members and Stakeholder:** Collaborate with relevant team members and stakeholders, including process owners, subject matter experts, and end-users, throughout the modeling process. Their insights and feedback are valuable in creating a comprehensive and accurate representation of the process.
+
+**Leave no one behind:** 
+Ensure that each case reaches a conclusive outcome. Implement timers to manage actions or decisions within specific time frames, enabling progress through the process despite delays or inactivity. Additionally, utilize intermediate events, such as message events, signal events, or error events, to capture specific occurrences during the process. These events guide the process towards a conclusion and allow for the cancellation of instances from within the process or through external triggers.
+

docs/bpmn/data_objects.md

@@ -1,23 +1,23 @@
 # Data Objects
 
-```{tip} 
-:class: note
-🧾 Read more about Data Objects [here](https://medium.com/@danfunk/understanding-bpmns-data-objects-with-spiffworkflow-26e195e23398).
-```
-
 In BPMN (Business Process Model and Notation), a data object represents the information or data used and produced by activities within a business process. It represents the data elements or artifacts that are relevant to the process and provides a way to model the flow of data through the process.
 They help in clarifying the data flow and dependencies within the process, making it easier to understand how information is utilized and transformed throughout the process execution.
 
-## Data Input Configuration
+**Reasons to use data objects:**
 
-| 💻 Form | ⌨ Field Input  | 
-| --- | --- | 
-|![name_field](images/name_field.png) | **Name:** Update Customer Information  |  
-|![id_field](images/id_field.png) | **ID:** Example - updateCustomerInformation    | 
-|![name_field](images/documentation_field.png) | **Element Documentation:** URL, Raw Data, Plain Text | 
-|![name_field](images/data_object_properties.png) | **Element Documentation:** URL, Raw Data, Plain Text (only applicable for Data Object Reference) | 
+- To represent and manage data within a business process. 
+  
+- When it is required to make a specific reference to data being used.
+  
+- When there are dependencies between tasks or activities based on shared data.
 
-### Data Input
+- When data changes within a process.
+
+- If data needs to be stored or retrieved for use in a process.
+
+## Data Object Types
+
+### Data Object
 
 ![data_input](images/data_input.png) 
 
@@ -41,4 +41,11 @@ A Data Object in BPMN typically represents a specific piece of information or a
 
 A Data Store represents a persistent storage location where data is stored and retrieved during the course of a process. It typically represents a database, file system, or any other storage mechanism. Data Stores are used to depict the long-term storage of data that can be accessed by multiple activities or tasks within the process. They provide a centralized location for data storage and retrieval.
 
+## Data Input Configuration
 
+| 💻 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/data_object_prop.png) | **Element Documentation:** inventory_items| Enter an existing data object ID |

docs/bpmn/dmn.md

@@ -0,0 +1,23 @@
+# Decision Tables
+
+DMN tables are powerful tools for modeling and implementing business rules and decision logic. They allow you to define rules and their associated conditions and actions in a structured manner. By evaluating the conditions in each rule, the DMN engine can determine which rules are triggered based on the provided inputs and execute the corresponding actions. This provides a flexible and configurable approach to decision-making in various scenarios.
+
+A DMN (Decision Model and Notation) table consists of several components that help define the decision logic and structure the decision-making process. The main components of a DMN table are:
+
+## DMN Components
+
+- ***Input Variables:**** These are the variables that represent the information or data used as input for the decision. Each input variable is typically represented as a column in the table. Multiple columns represent multiple input variables.
+- ***Conditions:**** Conditions specify the criteria or constraints that need to be evaluated for each input variable. They define the rules or expressions that determine when a particular decision rule should be triggered. Conditions are usually represented in the "When" column of the table.
+- ***Actions or Expressions:**** Actions or expressions define the operations or calculations that are executed when a specific rule is triggered. They represent the logic associated with the decision outcome and are represented in the same row as the conditions in the table.
+- ***Decision Rules:**** Decision rules are the individual rows in the DMN table. Each rule represents a specific combination of conditions and actions that define the behavior or logic for a particular scenario. Decision rules combine the input conditions and output actions in a structured manner.
+- ***Hit Policy:**** The hit policy determines how the decision engine selects or combines the applicable decision rules when multiple rules are triggered. It defines the behavior for resolving conflicts or overlaps between rules. Common hit policies include "First," "Unique," "Priority," "Any," and "Collect."
+
+## Hit Policy
+
+**Unique:** Only one rule can match the given inputs. If multiple rules match, it results in an error or an undefined outcome. This policy ensures that only one result is produced.
+
+**First:** The first rule that matches the inputs is selected, and its corresponding output is returned. Other matching rules are ignored. This policy is useful when you want to prioritize the order of rules.
+
+**Collect:** All rules that match the inputs are selected, and the outputs from those rules are collected and returned as a list or a collection. This policy allows for gathering multiple results.
+
+

docs/bpmn/gateways.md

@@ -0,0 +1,99 @@
+# Gateways
+
+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. 
+
+## 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.
+
+**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.
+
+
+
+![data_input](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.
+
+![data_input](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).
+
+**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.
+
+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.
+
+![data_output](images/exclusive_merge.png)
+
+### 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. 
+
+```{admonition} Note
+⚠ Note that default flow is not possible with Inclusive Gateways
+```
+
+![data_output](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.
+
+![data_output](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.
+
+**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.
+
+![data_output](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.
+
+### 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.
+
+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
+```
+
+![data_object_reference](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. 
+
+**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
+
+![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.
+
+## 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.
+
+**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. |
+
+**Outgoing Sequence:**
+
+| 💻 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 |

docs/bpmn/sub-processes_and_call_activities.md

@@ -25,7 +25,6 @@ A call process is similar to a sub-process in that it encapsulates part of a wor
 - **Delegation**: When different people or teams need to be responsible for the execution of tasks within a process, a call activity can be useful and can be assigned to the most appropriate person or team.
 
 - **Access Control**: If a specific segment of a process isn't meant to be available to every user, converting it into a call process can aid in establishing access control over that particular process. Additional information about this can be found in the [Admin and Permission](../installation_integration/admin_and_permissions.md) section.
-- 
 
 ## Sub-processes
 
@@ -38,3 +37,5 @@ Sub-processes are generally employed within a single process, whereas a call act
 - **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/index.md

@@ -32,18 +32,24 @@ wish_list/wish_list.md
 
 ```{toctree}
 :maxdepth: 3
-:caption: Spiffworkflow
-spiffworkflow/navigating-spiffworkflow.md
-spiffworkflow/creatingbpmn.md
-spiffworkflow/examples.md
-spiffworkflow/process_instance.md
+:caption: SpiffSparkles
+spiffsparkles/find_a_process_instance.md
+spiffsparkles/navigate_to_an_active_process_instance.md
+spiffsparkles/suspend_resume_terminate.md
+spiffsparkles/complete_task_on_behalf_of_another_user.md
+spiffsparkles/assign_task_to_a_different_user.md
+spiffsparkles/process_instance.md
 ```
 
 ```{toctree}
 :maxdepth: 3
-:caption: In Depth Topics
-in_depth_topics/sub-processes_and_call_activities.md
-in_depth_topics/data_objects.md
+:caption: BPMN
+bpmn/bpmn.md
+bpmn/gateways.md
+bpmn/sub-processes_and_call_activities.md
+bpmn/data_objects.md
+bpmn/dmn.md
+
 
 ```
 
@@ -58,9 +64,8 @@ installation_integration/permission_url.md
 ```{toctree}
 :maxdepth: 3
 :caption: Appendices
-appendices/bpmn_references.md
+appendices/glossary.md
 appendices/articles.md
-glossary/glossary.md
 learn_basics/bpmn_terminology.md
 
 ```

docs/installation_integration/admin_and_permissions.md

@@ -96,10 +96,12 @@ All the required workflows can be downloaded from [Github - set-permissions](htt
 Select to upload all downloaded files to the newly created Process model. 
 ![add_file](images/add_file.png) 
 
-Upload the following files
-permissions.bpmn - _Primary file_
-groups_permissions.dmn
-users_to_groups.dmn
+**Upload the following files:**
+
+- permissions.bpmn - _Primary file_ 
+- groups_permissions.dmn
+- users_to_groups.dmn
+  
 ![upload_file](images/upload_file.png) 
 
 the Process Model view should now include all uploaded files. 
@@ -107,7 +109,7 @@ the Process Model view should now include all uploaded files.
 
 ### Step 4: Understand the Process Models
 
-[Read more about DMN tables and how they work here.](../appendices/bpmn_references.md)
+[Read more about DMN tables and how they work here.](../bpmn/dmn.md)
 
 #### Users to Groups
 
@@ -126,7 +128,7 @@ Based on DMN functionality, leaving the "*" column empty means that all rules ('
 Now that the groups have been identified their permissions can be set by adding the group name under the "permissions_group" column. 
 
 - To determine a user's capabilities within the permissible scope, you can define specific permissions. These permissions can be combined in a sequence if multiple apply to a particular rule. For instance, ["read", "start"] indicates that the user can perform both reading and starting actions. Alternatively, [All] can be employed to grant unrestricted access.
-- The hit policy is set to "Collect" which means that all conditions that are true will be applied. [Read more about DMN tables and hit policies here.](../appendices/bpmn_references.md)
+- The hit policy is set to "Collect" which means that all conditions that are true will be applied. [Read more about DMN tables and hit policies here.](../bpmn/dmn.md)
 - The permission URL can be configured to define the user's access privileges. Our objective is to streamline the process by minimizing the necessity of being familiar with the complete set of permission URLs. In most instances, utilizing BASIC and ELEVATED permissions, as well as PM/PG, should be sufficient. However, it is also feasible to directly incorporate any API URL into the permissions.
   
 In truth what you are doing is writing an expression. In this case it would read that if the variable 'permissions_group' type string is equal to 'permissions' variable of type string then set the 'permission_url' equal to the associated value.

docs/spiffsparkles/assign_task_to_a_different_user.md

@@ -0,0 +1,84 @@
+# 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.](../spiffsparkles/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.](../spiffsparkles/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

@@ -0,0 +1,57 @@
+# 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.](../spiffsparkles/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.](../spiffsparkles/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

@@ -0,0 +1,64 @@
+# 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

@@ -0,0 +1,57 @@
+# 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,14 +1,12 @@
-# Navigating Spiffworkflow
-
-## What is a Process Instance
+# 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 following steps to understand how to locate a process instance:
-% [How to find an Instance assigned to someone else](/how_to/find_an_Instance_assigned_to_someone_else)
-% [How to find an Instance assigned to myself](https://github.com/sartography/spiff-arena/blob/main/docs/how_to/find_an_Instance_assigned_to_myself.md)
+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
 
@@ -30,9 +28,9 @@ The status of a process instance represents its current state or condition, refl
 | 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**     |                  |       |
-| **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: [How to resume a process](https://github.com/sartography/spiff-arena/blob/main/docs/how_to/resume_a_process.md)    |
+| **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.](../spiffsparkles/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.   |
 
 ---

docs/spiffsparkles/suspend_resume_terminate.md

@@ -0,0 +1,87 @@
+# Suspend, Resume and Terminate a Process
+
+| ⚙ How do I get there \| Menu Hierarchy |
+| -------------------------------------- |
+| Follow steps to [find a process instance](../spiffsparkles/find_a_process_instance.md)  |
+
+
+## Suspend a Process
+
+By suspending a process instance, you temporarily halt its execution, allowing you to access and modify the necessary data or configurations associated with that specific instance. This feature is not only useful for making updates but also enables the possibility to redo a previous step with different metadata if needed.
+
+> **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.
+
+```{admonition} Note
+
+⚠ Note that the suspension of a process instance is only applicable to active instances. If an instance is not active, it indicates that the process has already been completed, and therefore, it cannot be suspended.
+
+```
+
+> **Step 2: Locate Suspend Icon**
+
+![suspend](images/suspend.png) 
+
+- Next to the Process Instance Id, look for the icon that resembles the 'Suspend' icon and select it to initiate the suspension of the process instance.
+
+> **Step 3: Select Suspend Button**
+
+Click on the 'Suspend' icon. This action will pause the process instance, granting you the ability to make edits and modifications. When ready the process instance can be resumed. The process instance remains highlighted in yellow.
+
+![suspend](images/active_process_instance.png)
+
+
+| ✅ Success                                                    |  
+|  :----:  | 
+| Confirm that the status has changed from ‘waiting’ to ‘suspended’|
+|![suspended](images/suspended.png)| 
+
+## Resume a Process
+
+Resuming a process is essential for ensuring that the process can continue its execution, recover from interruptions, and proceed with the necessary updates or corrections.
+
+> **Step 1: Locate Resume Icon**
+
+![resume](images/resume.png) 
+
+- Next to the Process Instance Id, look for the icon that resembles the 'Resume' icon and select it to resume the suspended process instance.
+
+> **Step 2: Select Resume Button**
+
+- Click on the 'Resume' button. This action will cause the process instance to go back to its active state allowing the process instance to continue. Depending on where the process instance is in its journey the status might be waiting or some other active status. The process instance remains highlighted in yellow.
+
+![suspend](images/active_process_instance.png)
+
+
+| ✅ Success                                                    | 
+| :----:  |
+| Confirm that the status has changed from ‘suspended’ to an active status.|
+![waiting](images/waiting.png)| 
+
+## Terminate a Process Instance
+
+Terminating efers to ending the execution of a specific occurrence of a process before it reaches its natural completion or final outcome. There are various reasons for terminating a process instance such as the instance is no longer required or in an error state. 
+
+> **Step 1: Locate Terminate Icon**
+
+![terminate](images/terminate.png) 
+
+- Next to the Process Instance Id, look for the icon that resembles the 'Terminate' icon and select it to resume the suspended process instance.
+
+> **Step 2: Select Terminate Button**
+
+- Click on the 'Terminate' button. Note that the process instance will be terminated permanently, and this action cannot be undone. 
+
+> **Step 3: Confirm Terminatation**
+
+- Before proceeding with the termination, it is essential to be absolutely certain about your decision.
+![terminate_warning](images/terminate_warning.png)
+
+- The process status will now be 'Terminated' and the last active task will be highlighted in purple.
+![suspend](images/terminated_process_instance.png)
+
+| ✅ Success                                                    | 
+| :----:  |
+| Confirm that the status has changed from ‘suspended’ to 'terminated'
+![suspend](images/terminated.png) | 

docs/spiffworkflow/creatingbpmn.md

@@ -1,2 +0,0 @@
-# Create a BPMN flow
-

docs/spiffworkflow/examples.md

@@ -1 +0,0 @@
-# Examples

docs/spiffworkflow/navigating-spiffworkflow.md

@@ -1 +0,0 @@
-# Navigating Spiffworkflow