Documentation on Lanes/Pools and FAQ (#1473)

* Documentation on Lanes/Pools and FAQ

* Updates

* Remove Get_Current_User

docs/Building_Diagrams/pools_and_lanes.md

@@ -70,3 +70,42 @@ Remember that each pool requires Lane configuration, even if it contains just a
 | --- | --- | --- |
 | ![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. |
+
+### Example: Using Lanes and Pools for Petty Cash Request Process
+This example demonstrates the application of Lanes and pools in a BPMN diagram, specifically designed to handle a petty cash request process within an organization. 
+
+The process is structured around different tasks allocated to lane and pools, emphasizing role-based access and task execution.
+
+
+#### BPMN Diagram
+![Lanes and Pools Example](images/lanes_pools_example_1.png)
+
+**Process Flow:**   
+
+1. **Start Event**: The workflow kicks off with a start event signaling the initiation of a petty cash request.
+
+2. **User Task: Petty Cash Request**: This task uses a form to collect petty cash requests, including the requested amount and the reason for the request.
+
+    ![Lanes and Pools Example](images/lanes_pools_example_2.png)
+
+The process transitions from the Requester Lane to the Cashier Lane within the Cashier Pool for approval.
+
+3. **User Task: Approve Petty Cash**: In this task, cashiers review and approve the petty cash request, recording the approver’s name for accountability.
+
+    ![Lanes and Pools Example](images/lanes_pools_example_3.png)
+
+After approval, the workflow returns to the Requester Lane for final confirmation and display of the approval outcome.
+
+4. **Manual Task: Display Output**:
+
+**Display Message**:
+
+```markdown
+Your petty cash request for {{amount}} has been approved by {{approved_by}}
+```
+This message informs the requester of the approval status, including the approved amount and the name of the approver. After manual task, marks the end of the process.
+
+![Lanes and Pools Example](images/lanes_pools_example_4.png)
+
+
+This BPMN diagram effectively uses Lanes and pools to structure a petty cash request process, ensuring that responsibilities are clearly assigned and the workflow is logically organized.

docs/Support/FAQ.md

@@ -375,6 +375,26 @@ can I resolve this?
 
 5. **Custom Code Integration:** If you observe different behaviors between the Spiff CLI environment and your platform, it's important to ensure that the scripting environment and return values are consistently implemented across both. Differences in the scripting environment or the way the `execute` method is defined can lead to varying task states.
 
+**Q**: Can SpiffWorkflow be used to integrate with external systems, such as a CRM?
+
+**Answer:**
+
+Yes, SpiffWorkflow is well-suited for integrating with external systems, including CRM platforms. SpiffWorkflow can interact with these systems through various mechanisms to enhance your workflow capabilities.
+
+**Key Integration Features:**
+
+1. **Service Tasks for External Communication**:
+   - SpiffWorkflow supports the use of Service Tasks to connect to external applications like a CRM. These tasks can perform operations such as showing user dialogs, creating, reading, updating, and deleting (CRUD) objects within the CRM.
+
+2. **Control and Automation**:
+   - You can control your CRM directly from the workflow engine, allowing for dynamic interactions based on workflow conditions. This includes automating data exchange between SpiffWorkflow and the CRM to streamline processes and reduce manual intervention.
+
+3. **API Triggers**:
+   - Workflows in SpiffWorkflow can be triggered from an external CRM via API endpoints. This capability enables you to start workflows in response to specific events or conditions within the CRM, creating a responsive and interconnected system environment.
+
+**Example and Resources**:
+
+For practical implementation, refer to examples and guides available on SpiffWorkflow’s documentation site, such as the [external services integration example](https://spiffdemo.org/process-groups/examples:2-in-depth:2-2-external-services). This resource provides detailed steps on how to set up and utilize Service Tasks for calling external APIs.
 By adjusting the return value of your script task's `execute` method and understanding the underlying mechanics of task state management in SpiffWorkflow, you can effectively control the flow of your workflow processes.
 
 ### **40: Event Design in SpiffWorkflow**
@@ -386,3 +406,67 @@ By adjusting the return value of your script task's `execute` method and underst
    - **External Event Management:** For real external events, SpiffWorkflow allows the creation of an event object and passing it to the `send_event` function. This approach is used for events that need to be handled outside the workflow system.
    - **Event Translation and Messaging:** External systems should translate their events into SpiffWorkflow's format and call `send_events` to trigger the workflow. SpiffWorkflow collects all unhandled events, which the workflow system should periodically check using `get_events`. This process allows for the translation and sending of these events to external systems.
    - **Practical Application:** In real-world applications, tasks like UserTasks can be mapped to ApprovalTasks or FormTasks, and ServiceTasks can be mapped to API calls to external systems. The approach to handling events or messages, such as using RabbitMQ for pub/sub events or direct messaging via email or SMS, depends on the specific requirements and design of the workflow system.
+
+
+### **41: SpiffWorkflow Backend Support**
+
+**Q:** How does the SpiffWorkflow backend support different worker types and modular integrations?
+
+**A:**
+The SpiffWorkflow backend is highly modular, supporting various worker types through well-defined mechanisms:
+- **External APIs and Service Tasks:** We utilize Service Tasks and a Connector Proxy to facilitate connections to external APIs. This setup allows for parameters of service calls to be directly accessible under the Service Task properties in the BPMN diagram, enabling custom task configurations.
+- **Custom Tasks and Workflow Nesting:** SpiffWorkflow allows the nesting of workflows and the creation of custom tasks through service tasks, scripts, and Decision Model and Notation (DMN). 
+
+
+**Q:** Do multiple instances of the SpiffWorkflow backend require a shared filesystem for storing process models?
+
+**A**
+No, multiple instances of the SpiffWorkflow backend do not require a shared filesystem. Each backend instance can write to a local directory, and configurations can be extended to commit process models to a Git repository. This allows each instance to maintain an independent set of models while ensuring access to updated versions through Git synchronization.
+
+**Q:** What steps should I take if I encounter errors related to environment variable settings during backend configuration?
+
+**A**
+If you encounter errors, first verify the current settings of your environment variables. This can often be done by accessing the backend container and running diagnostic commands, such as:
+```bash
+from flask import current_app
+print(current_app.config['SPIFFWORKFLOW_BACKEND_URL_FOR_FRONTEND'])
+```
+If issues persist, consider deploying an updated version of your backend from the main branch, which might include improved error messages that can help diagnose the problem.
+
+### **42: Managing Service Task Connectors**
+
+**Q:** Is it possible to manage service-task connectors via the API instead of including them in the main deployment?
+
+**A:**
+Service-task connectors in SpiffWorkflow are typically included in the deployment of a connector proxy rather than the main backend deployment. This setup allows for more flexibility in managing connectors separately from the core workflow engine. 
+
+For a detailed guide on setting up and managing a connector proxy in just five minutes, refer to the [Connector Proxy Quick Start Guide](https://github.com/sartography/spiff-arena/wiki/Connector-Proxy-in-5-mins).
+
+### **43: Implementing and Troubleshooting Service Tasks in SpiffWorkflow**
+
+**Q:** How can I create a process that retrieves data from a REST endpoint using a service task in SpiffWorkflow?
+
+**A:**
+To retrieve data from a REST endpoint using a service task (`serviceTaskOperator: "http/GetRequest"`), you need to define a connector. When running SpiffWorkflow as a library, service tasks act as placeholders and require a custom script engine or connector proxy to execute the tasks. Ensure your service task is correctly configured with parameters such as URL, headers, and authentication details. The URL must be properly quoted in the configuration to avoid syntax errors.
+
+**Example Configuration:**
+```xml
+<bpmn:serviceTask id="Activity_0wu4fqk" name="get employee">
+  <bpmn:extensionElements>
+    <spiffworkflow:serviceTaskOperator id="http/GetRequest" resultVariable="data">
+      <spiffworkflow:parameters>
+        <spiffworkflow:parameter id="url" type="url" value="'https://example.com/api/employee'" />
+        <spiffworkflow:parameter id="headers" type="any" />
+        <spiffworkflow:parameter id="params" type="any" />
+        <spiffworkflow:parameter id="basic_auth_username" type="str" />
+        <spiffworkflow:parameter id="basic_auth_password" type="str" />
+      </spiffworkflow:parameters>
+    </spiffworkflow:serviceTaskOperator>
+  </bpmn:extensionElements>
+</bpmn:serviceTask>
+```
+
+**Q:** Why do I receive different behaviors when running the same service task in SpiffWorkflow library vs. SpiffArena?
+
+**A:**
+In SpiffWorkflow library, service tasks do not have built-in functionality and are essentially placeholders that require external implementations to function. In contrast, SpiffArena requires connectors to be set up for service tasks to function, which might lead to errors if the connectors or their configurations are incorrect. Errors such as "invalid syntax" typically occur when expressions (like URLs) are not properly formatted.