Script task and sub process call activity example

docs/Building_Diagrams/Script_Tasks.md

@@ -6,6 +6,40 @@ In SpiffArena, the scripting language used for writing scripts is Python, a wide
 
 Python offers a rich array of libraries, frameworks, and tools that facilitate script development, making it a popular choice for implementing custom logic and automation.
 
+## **Script Task Properties**
+  ```{image} ./images/Script_task_update.png
+:alt: Script Task
+:width: 300px
+:align: right
+```
+1. **General**
+   - **Name**: Allows users to name the Script Task. The name should reflect the task's purpose for easy identification.
+   - **ID**: Automatically generated unique identifier for the Script Task within the workflow. This ID can be used for referencing in code or debugging.
+
+2. **Documentation**
+   - **Element Documentation**: A free-text field to add notes or explanations about the purpose and function of this task. This is helpful for maintaining clear documentation within the workflow for team collaboration or future updates.
+
+3. **Script**
+   - **Script Field**: A text area for entering the code to be executed. This script should be written in Python, adhering to the rules and libraries supported by SpiffWorkflow.
+     - Example: 
+       ```python
+       result = context.get('input_variable', 0) * 2
+       context['output_variable'] = result
+       ```
+     - In the example above:
+       - **context.get** retrieves a process variable.
+       - **context['output_variable']** saves the result back to the workflow.
+   - **Launch Editor**: A button to open a more robust code editor for longer or more complex scripts. This improves readability and enables developers to write, format, and debug scripts more effectively.
+
+4. **Instructions**
+   - **Instructions Field**: Use this section to define task-specific guidance or additional notes visible during task execution.
+     - Example: *"Ensure the input variable `amount` is defined before running this task."*
+   - Markdown-supported formatting enables rich-text documentation.
+
+5. **Input/Output Management Section**
+   - **Inputs**: Define the process variables required for the script task to execute. For example, a variable `amount` could be an input for calculations.
+   - **Outputs**: Specify the variables the task will produce. These variables can be accessed in subsequent tasks in the workflow.
+
 Let's explore an example of a Script Task in our basics section:
 
 1. **Start Event and User Task - "Form"**

docs/Building_Diagrams/sub-processes_and_call_activities.md

@@ -3,14 +3,61 @@
 Sub-processes and call activities are both useful for simplifying and organizing complex workflows within larger processes.
 They serve distinct purposes and are used in different scenarios.
 
-**Reasons to use Sub-Processes or Call Activities:**
+## **Reasons to use Sub-Processes or Call Activities:**
 
 - Consolidate tasks that either have common features or collaboratively form a distinct functionality.
 For example, a Notification Gateway, which includes script tasks and a service task, works together to construct and send a notification, such as 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 the contained tasks.
 
+## Sub-Processes
+
+**When to use a Sub-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 need 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.
+
+### **Example Use Case: Restaurant Ordering System**
+A restaurant management workflow where customers place an order online, and the system processes their selections step by step. To streamline the workflow, the food selection process is encapsulated in a Subprocess.
+
+![Sub process](images/sub_process.png)
+
+**Step 1**: **Enter Name** 
+- A User Task that collects the customer's name using a web form.
+
+**Step 2**: **Select Food** 
+- A Subprocess that encapsulates the food selection process.
+
+**Step 3**: **Display Bill Value** 
+- A Script Task that calculates the total bill based on the selected items.
+
+**Step 4**: **Handle Payment** 
+- A Call Activity that integrates an external payment handling process.
+
+**Step 5**: **Order Confirmation** - A User Task that displays the confirmation message to the user.
+
+#### **Subprocess: Select Food**
+![Sub process](images/sub_process1.png)
+
+**Goal**: Simplify the food selection process into smaller, more manageable steps.
+
+**Internal Workflow**:
+1. **Start Event**: Initiates the subprocess.
+2. **Appetizer Task**: User selects an appetizer via a form.
+3. **Soup Task**: User selects a soup option.
+4. **Main Course Task**: User chooses a main course.
+5. **Dessert Task**: User selects a dessert.
+6. **End Event**: Marks the completion of the subprocess. 
+7. **Input Variables**:
+  - No specific inputs required in this example as tasks dynamically retrieve options from context or form
+8. **Output Variables**:
+  - `selected_items`: A dictionary containing the user’s food selections (e.g., `{"Appetizer": "Spring Rolls", "Soup": "Tomato Soup", ...}`).
+
+
 ## Call Process
 
 ![active_call_process](images/active_call_process.png)
@@ -32,12 +79,42 @@ Using a Call Process can help to eliminate redundancy and ensure consistent exec
 - **Access Control:** If a specific segment of a process should not be available to every user, converting it into a call process helps establish access control.
 More information about this can be found in the [Admin and Permission](../DevOps_installation_integration/admin_and_permissions.md) section.
 
-## Sub-Processes
 
-**When to use a Sub-Process:**
+### **Example Use Case: Payment Handling**
+A restaurant management workflow handles customer orders, calculates the bill, and processes payments. To maintain modularity and reusability, the payment processing logic is encapsulated in a separate workflow and invoked using a Call Activity.
 
-- **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 Process](images/Call_Activity1.png)
 
-- **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.
+**Step 1**: **Enter Name** - A User Task that collects the customer's name.
 
-- **Conditions or events need 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.
+**Step 2**: **Select Food** - A Subprocess to handle food selection.
+
+**Step 3**: **Display Bill Value** - A Script Task to calculate the total bill.
+
+**Step 4**: **Handle Payment** - A Call Process that navigates to a payment-handling process.
+
+**Step 5**: **Order Confirmation** - A User Task that displays order confirmation.
+
+#### **Call Activity: Handle Payment**:
+A restaurant management workflow handles customer orders, calculates the bill, and processes payments. To maintain modularity and reusability, the payment processing logic is encapsulated in a separate workflow and invoked using a Call Activity.
+
+![Call Process](images/Call_Activity.png)
+
+**Goal**: Abstract the logic of handling different payment methods into a reusable process.
+
+**Internal Workflow of Called Process**:
+1. **Start Event**: Initiates the payment process.
+2. **Select Payment Method**:
+   - A User Task where the customer selects a payment method (e.g., "Pay on Delivery" or "Pay Online").
+3. **Decision Gateway**:
+   - Routes the workflow based on the selected payment method:
+     - **Pay on Delivery**:
+       - A Manual Task to confirm payment upon delivery.
+     - **Pay Online**:
+       - A User Task where the customer enters their card information.
+4. **End Event**:
+   - Completes the payment process and returns to the main workflow.
+
+In the example of "Handle Payment," the main workflow remains focused on order management while delegating payment logic to a reusable process, improving both clarity and efficiency.
+
+Therefore, the Call Process is a critical tool for creating modular, reusable, and scalable workflows in SpiffWorkflow.