imported patch from old FAQ_3rd_Set branch w/ burnettk (#810)

* imported patch from old FAQ_3rd_Set branch w/ burnettk * updates while reviewing --------- Co-authored-by: jasquat <jasquat@users.noreply.github.com> Co-authored-by: burnettk <burnettk@users.noreply.github.com>
2023-12-20 18:23:38 -05:00 · 2023-12-20 18:23:38 -05:00 · dc0aa584be
parent d2b39b10c6
commit dc0aa584be
1 changed files with 182 additions and 21 deletions
--- a/docs/Support/FAQ.md
+++ b/docs/Support/FAQ.md
@ -94,31 +94,36 @@ workflow.reset_from_task_id(start.id)
 ![Mimicking Inclusive Gateway](images/Mimicking_inclusive_gateway.png)
 ### **19. Designing an Approval Process in SpiffWorkflow**
-**Q:** I am designing an approval process using SpiffWorkflow. Can SpiffWorkflow handle scenarios where a task should complete if more than 2 users approve out of 3 assignees?  
+**Q:** I am designing an approval process using SpiffWorkflow. Can SpiffWorkflow handle scenarios where a task should complete 
 if more than 2 users approve out of 3 assignees?
 **A:** Yes, SpiffWorkflow can handle complex approval processes. The [provided video](https://www.youtube.com/watch?v=EfTbTg3KRqc) link offers insights into managing such scenarios using SpiffWorkflow.
-
+### **20. Process Instances in Spiff Arena After Docker Compose Restart**
-**20: I restarted docker-compose, and my process instances in Spiff Arena aren't persistent. How can I ensure they remain after a restart?**
+**Q:** I restarted docker-compose, and my process instances in Spiff Arena aren't persistent. How can I ensure they remain after a restart?
 **A:** Make sure you're using the updated "getting started" `docker-compose.yml` file that uses sqlite to persist the database between docker compose restarts.
 This will ensure that your process instances remain after a restart.
 If you're still facing issues, refer to the provided documentation on admin and permissions for further guidance.
-**21: Is it possible to download a process model in Spiff Arena and then re-upload it?**
+### **21: Downloading and Re-uploading Process Models in Spiff Arena**
 **Q:** Is it possible to download a process model in Spiff Arena and then re-upload it?
 **A:** Yes, in Spiff Arena, you can download a process model and then re-upload it. However, it's essential to note that all process IDs must be unique across the system. If you're re-uploading a process model, its ID might need to be modified to ensure uniqueness.
-**22: What are the "notification addresses" and "metadata extractions" fields when creating a new process model in Spiff Arena?**
+
 ### **22: Understanding "Notification Addresses" and "Metadata Extractions" in Spiff Arena**
 **Q:** What are the "notification addresses" and "metadata extractions" fields when creating a new process model in Spiff Arena?
 **A:** When creating a new process model in Spiff Arena, the "notification addresses" field is used to specify recipients for notifications related to that process.
 The "metadata extractions" field is used to extract specific metadata from the process.
 Detailed documentation for both fields is available.
 It's worth noting that the functionality of "Notification Addresses" might undergo changes in the future to centralize the logic and avoid splitting configurations.
-
+### **23: Issues with Spiff Arena Frontend Loading**
-**23: Why doesn't the Spiff Arena frontend always load completely?**
+**Q:** Why doesn't the Spiff Arena frontend always load completely?
 **A:** The issue might arise when the frontend cannot communicate with the backend.
 Recent updates have been made to address this specific problem.
@ -136,15 +141,16 @@ docker compose up -d
 By doing this, you'll pull the latest images, shut down the current containers, and then start them up again with the updated configurations.
 This should help in ensuring that the frontend loads completely and communicates effectively with the backend.
-
+### **24: Resolving Docker Compose Issues on M1/M2 Mac in Spiff Arena** 
-**24: I'm using an M1/M2 Mac and facing issues with docker-compose in Spiff Arena. How can I resolve this?**
+**Q:** I'm using an M1/M2 Mac and facing issues with docker-compose in Spiff Arena. How can I resolve this?
 **A:** Ensure that you're using the latest versions of Docker and docker-compose.
 If you encounter messages about platform mismatches, note that these may just be warnings and not errors.
 Update your images and restart the containers as needed.
 Instructions in the getting started guide reference `curl`, but if that is not working for you, `wget` may be an option that is already installed on your system.
-**25: Why can't I import an external module in a script task in Spiff Arena?**
+### **25: Importing External Modules in Script Tasks in Spiff Arena**
 **Q:** Why can't I import an external module in a script task in Spiff Arena?
 **A:** In Spiff Arena, script tasks are designed for lightweight scripting and do not support importing external modules.
 If you need to communicate with external systems, it's recommended to use a ServiceTask instead.
@ -153,36 +159,191 @@ For tasks like checking if an API is functioning correctly, you can set up a Con
 Detailed documentation available [here](https://spiff-arena.readthedocs.io/en/latest/DevOps_installation_integration/configure_connector_proxy.html).
 If you want to bypass security features of the restricted script engine and import modules from your script tasks, you can set the environment variable: `SPIFFWORKFLOW_BACKEND_USE_RESTRICTED_SCRIPT_ENGINE=false`
-
+### **26:  Storage of Properties Data in Spiff Arena** 
-**26: Where is the properties data stored in the properties panel?**
+**Q:** Where is the properties data stored in the properties panel?
 **A:** The properties data is stored directly within the XML of the BPMN diagram. Some of this data is stored in extension elements. 
 For instance, the configuration for a service task can be found [here](https://github.com/sartography/sample-process-models/blob/sample-models-1/misc/jonjon/ham/ham.bpmn#L13) and instructions can be found [here](https://github.com/sartography/sample-process-models/blob/sample-models-1/misc/documentation/user-guide-basics/user-guide-basics.bpmn#L24). If you're considering bypassing the properties panel, it's essential to ensure that the XML output remains consistent with the expected format.
-**27: How do I start a task? What do I need besides BPMN?**
+### **27: Starting a Task in Spiff Arena**
 **Q:** How do I start a task? What do I need besides BPMN?
 **A:** To start a task, you'll need to have a proper BPMN diagram and a configured environment. The docker compose file, as mentioned on the [spiffworkflow.org](https://www.spiffworkflow.org/posts/articles/get_started/) website, provides a containerized environment for both the API and asynchronous processing. For a more robust production deployment, it's recommended to use separate containers for different functionalities.
-**28: Any documentation on how to set up our own openid provider?**
+### **28: Setting Up Own OpenID Provider**
 **Q:** Any documentation on how to set up our own openid provider?
 **A:** If you're using the spiff-arena/spiffworkflow-backend, there's a script named `./keycloak/bin/start_keycloak` that can initiate a container serving as an example OpenID provider. This can be a good starting point if you're looking to set up your own OpenID provider.
-
+### **29: Configuring SMTP Server for Email Notifications in SpiffWorkflow**
-**29: Where can I configure an SMTP server for Spiffworkflow to send email notifications?**
+**Q:** Where can I configure an SMTP server for Spiffworkflow to send email notifications?
 **A:** To configure an SMTP server for email notifications, you can utilize connectors and service tasks within SpiffWorkflow. For instance, connectors can be set up to send notifications to platforms like Slack.
-**30: Is there any way to access the timer event value/expression in my code?**
+### **30: Accessing Timer Event Value/Expression in Code**
 **Q:** Is there any way to access the timer event value/expression in my code?
 **A:** Yes, in SpiffWorkflow, you can access timer event values directly from the backend. There are specific sections in the codebase where timer event values are checked and utilized for various functionalities.
-**31: How can I create new users for my co-workers in SpiffWorkflow?**
+### **31: Creating New Users in SpiffWorkflow**
-**A:** There are multiple methods to manage this, such as using OpenID or the process model. However, for beginners eager to add a user quickly, you can adjust the 'example.yml' configuration file within the app identified as `` 'SPIFFWORKFLOW_BACKEND_PERMISSIONS_FILE_NAME: "example.yml"`` 
+**Q:** How can I create new users for my co-workers in SpiffWorkflow?
 **A:** There are multiple methods to manage this, such as using OpenID or the process model. However, for beginners eager to add a user quickly, you can adjust the 'example.yml' configuration file within the app identified as `` 'SPIFFWORKFLOW_BACKEND_PERMISSIONS_FILE_NAME: "example.yml"`` 
 After making changes, restart the container to update user details. For more information, refer to the [Spiff-Arena documentation](https://spiff-arena.readthedocs.io/en/latest/installation_integration/admin_and_permissions.html). The mentioned file can be found [here](https://github.com/sartography/spiff-arena/tree/main/spiffworkflow-backend/src/spiffworkflow_backend/config/permissions).
-**32: Explain the functionality and purpose of the collaboration flag in spiff-example-cli?**
+### **32: Understanding the Collaboration Flag in Spiff-Example-CLI**
 **Q:** Explain the functionality and purpose of the collaboration flag in spiff-example-cli?
 **A:** The collaboration flag enables the simultaneous loading of multiple top-level processes within a single workflow. This results in the creation of a subworkflow for each process, allowing them to initiate concurrently. 
-A practical application of this might be when two processes need to interact but remain independent of each other.
+A practical application of this might be when two processes need to interact but remain independent of each other.
 ### **33: Custom Tasks and Services in Modeler**
 **Q:** How can I draw custom tasks or services in the modeler that can run in Python SpiffWorkflow when loaded using the BPMN YAML file?
 **A:** To create custom tasks or services in SpiffWorkflow, you have several options:
 1. **Using SpiffArena**: You can author a diagram in SpiffArena, which provides a user-friendly interface for designing your workflow. Once your diagram is complete, save it in the standard BPMN XML format. This diagram can then be executed in the SpiffWorkflow library as per the documentation available [here](https://spiffworkflow.readthedocs.io/en/latest/).
 2. **BPMN IO Extensions**: If you prefer to work outside of SpiffArena, you can use the BPMN IO extensions directly, available at [this GitHub repository](https://github.com/sartography/bpmn-js-spiffworkflow). Similar to SpiffArena, you'll save your custom diagram in BPMN XML format for execution in SpiffWorkflow.
 3. **Service Tasks**: For creating service tasks within your custom BPMN diagrams, refer to the detailed documentation provided by SpiffWorkflow [here](https://spiffworkflow.readthedocs.io/en/latest/bpmn/advanced.html?highlight=service#service-tasks). This documentation will guide you on how to effectively integrate service tasks into your workflow.
 4. **Defining Custom Applications**: If your workflow requires calling custom applications, you can define these within your BPMN diagram. For working outside of SpiffArena, ensure to provide hooks in the diagram editor to list available methods, services, etc. While SpiffArena and its Connector Proxy offer a streamlined approach for this, you have the flexibility to write your own connectors if needed.
 By following these guidelines, you can create custom tasks or services tailored to your specific workflow requirements in SpiffWorkflow.
 ### **34: configure SpiffWorkflow to work with hostname instead of "localhost**
 **Q:** How can I configure SpiffWorkflow to work with my computer's hostname instead of "localhost"?
 **A:** To configure SpiffWorkflow to work with your computer's hostname, follow these steps:
 1. **Modify Docker Compose File**: If you're using the Docker Compose file from the root of SpiffArena, you need to adjust the backend URL used by the frontend. Add a line in the environment section of your Docker Compose file to configure `SPIFFWORKFLOW_FRONTEND_RUNTIME_CONFIG_BACKEND_BASE_URL`. For example:
   ```yaml
   environment:
     APPLICATION_ROOT: "/"
     SPIFFWORKFLOW_FRONTEND_RUNTIME_CONFIG_BACKEND_BASE_URL: "http://itsm.local:8000"
     PORT0: "${SPIFFWORKFLOW_FRONTEND_PORT:-8001}"
   ```
 2. **Using NPM Start**: If you're booting the frontend with `npm start`, set the environment variable like this:
   ```
   REACT_APP_BACKEND_BASE_URL=http://itsm.local:8000
   ```
 3. **Add Extra Hosts in Docker Compose**: To ensure that both the SpiffWorkflow frontend and backend can resolve the hostname (e.g., `itsm.local`), add `extra_hosts` to your Docker Compose file. This step is crucial if your hostname is broadcasted on the network (like with avahi-daemon) and not known to the containers. Here's an example of how to add it:
   ```yaml
   services:
     spiffworkflow-frontend:
       ...
       environment:
         ...
         SPIFFWORKFLOW_FRONTEND_RUNTIME_CONFIG_BACKEND_BASE_URL: "http://${HOSTNAME}:${SPIFF_BACKEND_PORT:-8000}"
       ...
       extra_hosts:
         - "${HOSTNAME}:10.89.0.1"
     spiffworkflow-backend:
       ...
       environment:
         ...
         SPIFFWORKFLOW_BACKEND_URL: "http://${HOSTNAME}:${SPIFF_BACKEND_PORT:-8000}"
         ...
         SPIFFWORKFLOW_BACKEND_OPEN_ID_SERVER_URL: "http://${HOSTNAME}:${SPIFF_BACKEND_PORT:-8000}/openid"
         ...
         SPIFFWORKFLOW_BACKEND_URL_FOR_FRONTEND: "http://${HOSTNAME}:${SPIFFWORKFLOW_FRONTEND_PORT:-8001}"
       ...
       extra_hosts:
         - "${HOSTNAME}:10.89.0.1"
   ```
   In this configuration, `${HOSTNAME}` should be replaced with your actual hostname (e.g., `itsm.local`), and `10.89.0.1` represents the gateway IP address of your network, translating to the Docker host IP address.
 4. **Update `/etc/hosts` Inside Containers**: By adding `extra_hosts`, the `/etc/hosts` file inside each container will contain an entry for your hostname, allowing both containers to access and resolve it.
 By following these steps, you can successfully configure SpiffWorkflow to work with your computer's hostname, ensuring smooth operation outside the "host" computer environment.
 ### **35: Approval process in SpiffWorkflow**
 **Q:** How do I model an approval process in SpiffWorkflow where each task may require a different approver?
 **A:** To model an approval process in SpiffWorkflow with multiple tasks, each requiring a different approver, follow these steps:
 1. **Understand the Approval Process**: First, clearly define the approval process, including the number of tasks and the specific approvers required for each task.
 2. **Use User Tasks for Approval**: In SpiffWorkflow, you can use User Tasks to represent approval tasks. Each User Task can be assigned to a different approver based on your process requirements.
 3. **Define Task Properties**: For each User Task, define properties such as the task name, description, and the approver's role or identifier. This ensures that the right approver is associated with each task.
 4. **Sequence the Tasks**: Arrange the tasks in the order they should be executed. You can use sequence flows in your BPMN model to define the order and conditions under which each task should be initiated.
 5. **Utilize Conditional Flows**: If your approval process has conditional paths (e.g., different paths based on the outcome of an approval), model these using exclusive gateways and conditional sequence flows.
 6. **Review and Test**: Once you have modeled the approval process, review it to ensure it accurately represents the required workflow. Test the process to confirm that each task is assigned to the correct approver and that the workflow behaves as expected.
 7. **Refer to SpiffWorkflow Documentation**: For detailed guidance and examples, refer to the SpiffWorkflow documentation, particularly the section on approval processes. The documentation provides valuable insights and best practices for modeling complex workflows. You can find more information at [SpiffWorkflow Approval Process Deep Dive](https://www.spiffworkflow.org/posts/deep_dives/approval).
 By following these steps and utilizing the features of SpiffWorkflow, you can effectively model an approval process with multiple tasks and approvers, ensuring a smooth and efficient workflow.
 ### **36: Timer Start Event and internal scheduler**
 **Q:** How does the Timer Start Event work in SpiffWorkflow, and is there an internal scheduler to execute workflows at the specified timer value?
 **A:** In SpiffWorkflow, Timer Start Events are managed by an internal scheduler within the backend. This scheduler is 
 responsible for triggering workflows based on the timer values set in the Timer Start Events. To ensure that the scheduler 
 functions correctly, you need to start an instance of the process, which will then schedule the event for the appropriate time 
 based on the timer. 
 Additionally, there are environment variables like `SPIFFWORKFLOW_BACKEND_BACKGROUND_SCHEDULER_NOT_STARTED_POLLING_INTERVAL_IN_SECONDS` that control the polling time for the 
 scheduler. For more details, you can refer to the [SpiffWorkflow Backend Initialization Code](https://github.com/sartography/spiff-arena/blob/main/spiffworkflow-backend/src/spiffworkflow_backend/__init__.py).
 ### **37: Authentication tokens in SpiffWorkflow**
 **Q:** How does authentication work in SpiffWorkflow, particularly regarding the use of authentication tokens?
 **A:**  A common approach for handling authentication involves using bearer tokens in the "Authorization" header of API 
 requests. If you encounter issues like "token invalid" responses, it's recommended to inspect the network traffic using your 
 browser's developer tools. This can help you understand how the token is being passed and whether it's correctly formatted. You 
 can copy any request to the backend as a curl command or inspect the headers to see how the bearer token is being used. 
 If the standard openid flow is not ideal for your use case, Service Account / API Token management can be implemented using a process model.
 ### **38: Configure Spiff Arena to run behind a proxy server**
 **Q:** How can I configure Spiff Arena to run behind a proxy server, such as Traefik, and resolve issues with redirects and OpenID provider authentication?
 **A:** Running Spiff Arena behind a proxy server like Traefik involves several configuration steps to ensure proper communication between the frontend, backend, and the OpenID provider. Here are key points to consider:
 1. **Subdomain Configuration:** When setting up Spiff Arena with Traefik, it's common to create subdomains for different components (e.g., "traefik", "auth", "workflow", "workflow-backend"). However, you might encounter issues like redirect loops or authentication errors if the subdomains are not correctly configured.
 2. **Environment Variable Settings:** The `SPIFFWORKFLOW_BACKEND_URL` environment variable is crucial as it informs the frontend about the backend's URL. If you're experiencing HTTP and HTTPS mismatches, it might be due to misconfiguration in Traefik and Flask communication. To resolve this, you can set the `FORWARDED_ALLOW_IPS='*'` environment variable, which allows the backend to correctly report its URL as HTTPS.
 3. **Compatibility Check:** The `SPIFFWORKFLOW_BACKEND_CHECK_FRONTEND_AND_BACKEND_URL_COMPATIBILITY` environment variable is used to ensure that the frontend and backend URLs are compatible, particularly for cookie sharing. If you encounter issues with this check, you might need to adjust your domain setup to ensure that the frontend and backend are on the same domain or subdomain structure.
 4. **Domain Structure:** A common setup involves having the frontend on `example.com` and the backend on `api.example.com`. This structure allows for seamless cookie sharing and authentication. If you initially set up different subdomains (e.g., `workflow.<domain_name>.com` and `workflow-backend.<domain_name>.com`) and face issues, consider switching to a structure like `api.workflow.<domain_name>.com` for the backend, or consider using path-based routing, where the same host is used for both frontend and backend, but the proxy server routes a specific path prefix (/api, /frontend) to each app as needed.
 5. **Debugging and Testing:** Utilize the new API endpoint `/v1.0/debug/url-info` on the backend to verify how Flask perceives the URL. This can help identify any mismatches or misconfigurations in your setup, specifically if you access the app using https but the correct information from the request does not make it all the way to the flask application, and it therefore thinks it using running on http without SSL.
 6. **Community Support:** If you encounter specific issues or need further assistance, consider reaching out to the community on platforms like GitHub or Discord. Sharing your configuration and experiments in detail can help others provide more targeted advice.
 For more detailed guidance and examples of Spiff Arena deployment configurations, you can refer to resources like the [Terraform Kubernetes Modules](https://github.com/mingfang/terraform-k8s-modules/blob/master/examples/spiffworkflow/README.md).
 Remember, each deployment scenario can be unique, so it's important to tailor these guidelines to your specific setup and
 requirements.
 ### **39: Change in states of script tasks**
 **Q:** Why does my script task in SpiffWorkflow change to the "STARTED" state instead of "COMPLETED" after execution, and how
 can I resolve this?
 **A:** The behavior of a script task transitioning to the "STARTED" state instead of "COMPLETED" can occur due to the way SpiffWorkflow handles potentially long-running tasks. Here's what you need to know:
 1. **STARTED State Purpose:** SpiffWorkflow introduced the "STARTED" state to manage tasks that might take a long time to complete. This state allows these tasks to be processed outside the workflow without delaying the entire workflow's progress.
 2. **Return Values from Run Method:** The state transition of a script task is determined by the return values from the `run` method. This is part of SpiffWorkflow's design to provide flexibility in handling different task scenarios.
 3. **Quick Fix for Completion:** If your script task is simple and should be marked as "COMPLETED" immediately after execution, ensure that the `execute` method in your scripting environment returns `True`. This return value explicitly indicates that the task has completed its execution successfully.
 4. **Documentation Reference:** For more detailed information on how SpiffWorkflow handles task states and hooks, you can refer to the [SpiffWorkflow documentation](https://spiffworkflow.readthedocs.io/en/latest/concepts.html#hooks). This resource provides insights into the internal workings of task state management and how you can customize it for your specific needs.
 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.
 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**
 **Q:** How are internal and external events managed within SpiffWorkflow?
 **A:** **Event Handling in SpiffWorkflow:**
   - **Internal vs. External Events:** The distinction between internal and external events in SpiffWorkflow is primarily for deciding whether an event should be handled within the workflow or passed up to a parent workflow from a subprocess. This is now managed by targeting a particular subworkflow or leaving the target as None for internal handling.
   - **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.