# Frequently Asked Questions
## Support and Administration

### **1. Running SpiffWorkflow in PyCharm**
**Q:** Is there a setup where I can run it within PyCharm?  
**A:** Yes, you can run SpiffWorkflow within PyCharm. For detailed settings, refer to the provided screenshot of flask server details. 

![Flask](images/Flask.png)

### **2. Adding Python Libraries to SpiffWorkflow**
**Q:** Is there documentation available for adding python libraries to SpiffWorkflow? For example, if I want to run a process to send emails, I would need `smtplib`.  
**A:** The default answer for something like sending emails would be to use a service task. We have an SMTP connector designed for this purpose. If you're using Spiff Arena, a connector proxy can provide a nice integration into the UI. Here are some helpful links:
- [SMTP Connector](https://github.com/sartography/connector-smtp)
- [Spiff-Connector Demo](https://github.com/sartography/connector-proxy-demo)
- [BPMN,DMN samples for SpiffWorkflow](https://github.com/sartography/sample-process-models/tree/jon/misc/jonjon/smtp)

### **3. Tutorials on Using SpiffWorkflow**
**Q:** Are there any tutorials available on how to use SpiffWorkflow?  
**A:** Yes, here are some references:
- [SpiffExample CLI](https://github.com/sartography/spiff-example-cli)
- [SpiffArena Documentation](https://spiff-arena.readthedocs.io/)
- [SpiffWorkflow Documentation](https://spiffworkflow.readthedocs.io/en/stable/index.html)
- [Getting Started with SpiffWorkflow](https://www.spiffworkflow.org/posts/articles/get_started/)

### **4. Understanding Task Data in Custom Connectors**
**Q:** What kind of data can I expect from `task_data`?  
**A:** The `task_data` param contains data comprised of variables/values from prior tasks. For instance, if you have a script task before your service task that set `x=1`, then in the `task_data` param, you should see `{"x": 1}`.

### **5. Understanding and Using Custom Connectors**
**Q:** What are custom connectors and how do I use them?  
**A:** Custom connectors in SpiffWorkflow allow for integration with external systems or services. They enable the workflow to interact with other platforms, fetch data, or trigger actions. To use them, you'll typically define the connector's behavior, specify its inputs and outputs, and then use it within your BPMN process as a service task.

### **6. Using Data Object Reference and Data Store Reference**
**Q:** What are some good references for "Data Object Reference" and "Data Store Reference" in SpiffWorkFlow?  
**A:** Here are some references to help you understand and implement "Data Object Reference" and "Data Store Reference" in SpiffWorkflow:
- [Understanding BPMN's Data Objects with SpiffWorkflow](https://medium.com/@danfunk/understanding-bpmns-data-objects-with-spiffworkflow-26e195e23398)
- [Data Encapsulation with SpiffWorkflow Video](https://youtu.be/0_PgaaI3WIg)

### **7. Resetting a Workflow**
**Q:** Is there a way of "resetting" a workflow without reloading the BPMN and DMN files?  
**A:** Yes, you can reset a workflow using the following code:
```python
start = workflow.get_tasks_from_spec_name('Start')[0]
workflow.reset_from_task_id(start.id)
```

### **8. Integrating SpiffWorkflow with other Python code**
**Q:** How do you integrate your workflow with another python code?  
**A:** Integrating SpiffWorkflow with other Python code is straightforward. You have two primary methods:
1. **Script Tasks**: These allow you to execute Python code directly within your workflow. This method is suitable for simpler integrations where the code logic is not too complex.
2. **Service Tasks**: For more complex integrations, you can write services that can be called via service tasks within your workflow. This method provides more flexibility and is ideal for scenarios where you need to interface with external systems or perform more intricate operations.

### **9. Using Call Activity for preconfigured modular subprocesses**
**Q:** I need my users to generate many BPMN workflows by dropping preconfigured subprocesses into their workflows. Is this possible?  
**A:** Yes, you can use a "Call Activity" in SpiffArena to reference other processes in your diagram. SpiffArena provides a way to search for other processes in the system that can be used as Call Activities. This means you can create modular workflows by designing subprocesses (like ‘send to accounts’) and then incorporating them into multiple main workflows as needed. This modular approach not only streamlines the design process but also ensures consistency across different workflows.

### **10. Integrating SpiffWorkflow with External Role Management**
**Q:** How do I make external application user roles affect permissions on a task?  
**A:** You can manage the roles externally in an OpenID system and access the user and group information in the Lanes of your BPMN diagram.

### **11. Understanding Workflow Data vs Task Data**
**Q:** What is the difference between the `workflow.data` and `task.data`?  
**A:** Task data is stored on each task, and each task has its own copy. Workflow data is stored on the workflow. If you use BPMN DataObjects, that data is stored in workflow data.

### **12. Understanding Secrets and Authentications in SpiffArena**
**Q:** What are 'Secrets' and 'Authentications' used for in SpiffArena?  
**A:** Secrets are used for communicating with external services when you use service tasks and connectors. Authentications are used when you need to OAuth into an external service. Check out more information [here](https://spiff-arena.readthedocs.io/en/latest/DevOps_installation_integration/Secrets.html).

### **13. Determining the Lane of a Task in a Workflow**
**Q:** In the pre/post script of a task in a workflow, how do I determine what lane the current task is in?  
**A:** You can access the task and use `task.task_spec.lane` to get the lane as a string. This allows you to programmatically determine which lane a task belongs to during its execution.

### **14. Understanding Script Attributes Context**
**Q:** I'm trying to understand the details of `script_attributes_context`. Where can I find more information?  
**A:** The `ScriptAttributesContext` class is defined [here](https://github.com/sartography/spiff-arena/blob/deploy-mod-prod/spiffworkflow-backend/src/spiffworkflow_backend/models/script_attributes_context.py#L9).

### **15. Using Message Start Event to Kick Off a Process**
**Q:** How do I use a message start event to kick off a process?  
**A:** This [script](https://github.com/sartography/spiff-arena/blob/main/spiffworkflow-backend/bin/run_message_start_event_with_api#L39) is an example of using a message start event to kick off a process.


### **16. Making REST API Calls in SpiffArena**
**Q:** How do I make REST API calls in SpiffArena?  
**A:** You can use Service Tasks driven by a Connector Proxy. Check out the [Connector Proxy Demo](https://github.com/sartography/connector-proxy-demo) for more details.

### **17. Assigning User Tasks in SpiffWorkflow**
**Q:** How does one use camunda:assignee="test" in a userTask with Spiff?  
**A:** In SpiffWorkflow, user task assignments can be managed using Lanes in your BPMN diagram. Each Lane can designate which individual or group can execute the tasks within that Lane. If you're looking to interface permissions based on external application user roles, you can manage roles externally and pass the user and group information to assign them to the Lanes.

### **18. Mimicking an Inclusive Gateway in SpiffWorkflow**
**Q:** How can we mimic an inclusive gateway since SpiffWorkflow doesn't support it?  
**A:** You can work around the absence of an inclusive gateway in SpiffWorkflow by using a Parallel Gateway. Within each path following the Parallel Gateway, you can place an Exclusive Gateway to check for the conditions that are or are not required. This approach is effective if the flows can eventually be merged back together.

![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?

**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**
**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: 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: 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**
**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.
Previously, the backend could deadlock when it received a high number of concurrent requests, exhausting the available worker processes.

Since it uses built-in openid, each request would need to communicate with the backend itself.
This issue has been resolved in the newer versions. To potentially fix this, you can update your setup by running the following commands in the directory where you downloaded the `docker-compose.yml` file:

```
docker compose pull
docker compose down
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** 
**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: 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.
ServiceTasks in Spiff Arena utilize a concept called Connector Proxy, an externally hosted system that adheres to a specific protocol.
For tasks like checking if an API is functioning correctly, you can set up a Connector Proxy to handle the request.
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** 
**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: 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: 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**
**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: 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: Creating New Users in SpiffWorkflow**
**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: 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.

### **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.