Diataxis docs

docs/.gitignore

@@ -1,3 +1,6 @@
 _build
 .venv
-.vscode
+.vscode
+
+# meh, we could commit these, but they are automatically generated by the build, so we do not need to
+_tags

docs/Building_Diagrams/Builtin_examples.md

@@ -226,3 +226,6 @@ Once the score messages are displayed, a **signal event** is included, providing
 Signal events enable external forces or internal errors to interact with the process, and in this scenario, a button press allows for the interruption of the diagram's normal course.
 
 ![](images/Signal_EM.png)
+
+```{tags} tutorial, building_diagrams
+```

docs/Building_Diagrams/Displaying_Content.md

@@ -79,3 +79,6 @@ The process concludes with an End Event, indicating the end of the workflow.
 The instructions panel of the End Event suggests next steps, such as exploring the diagram in edit mode and completing the "Request a Playground" task.
 
 ![Image](images/end_message.png)
+
+```{tags} how_to_guide, building_diagrams
+```

docs/Building_Diagrams/Script_Tasks.md

@@ -184,3 +184,6 @@ Please see the [implementing files themselves](https://github.com/sartography/sp
 | set_user_properties                    | Sets given user properties on the current user.                                                                                                                |
 | times_executed_by_user                 | Returns the number of times the user has started an instance of the current process model.                                                                     |
 | user_has_started_instance              | Returns a boolean indicating if the user has started an instance of the current process model.                                                                 |
+
+```{tags} tutorial, reference, building_diagrams
+```

docs/Building_Diagrams/bpmn.md

@@ -6,7 +6,7 @@ Here are some helpful tips to guide you through the process and create effective
 **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](../appendices/bpmn_terminology.md) section to learn more about each symbol.
+Refer to the [Learn Basics](../appendices/glossary.md) section to learn more about each symbol.
 
 Grouping them together can create a mind map that's easy to remember.
 
@@ -86,3 +86,6 @@ 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.
+
+```{tags} how_to_guide, building_diagrams
+```

docs/Building_Diagrams/conditional_events.md

@@ -99,3 +99,6 @@ Always revert the condition to its default state to ensure appropriate behavior.
 ```{admonition} Note
 ⚠  When configuring the conditional expression, ensure there's such a variable in your process context.
 ```
+
+```{tags} reference, building_diagrams
+```

docs/Building_Diagrams/custom_process_metadata.md

@@ -39,3 +39,6 @@ This guide will walk you through the steps to create a process model that genera
    - You can also filter process instances based on your custom column using the same column options.
 
 By following these steps, you can create a process model that generates custom metadata and efficiently query that metadata using process instance filtering.
+
+```{tags} how_to_guide, building_diagrams
+```

docs/Building_Diagrams/data.md

@@ -7,3 +7,6 @@ task_data.md
 data_objects.md
 data_stores.md
 ```
+
+```{tags} reference, building_diagrams
+```

docs/Building_Diagrams/data_objects.md

@@ -116,3 +116,6 @@ With these permissions, access to the credit card data is denied to everyone, en
 
 By following these steps, SpiffWorkflow users can securely handle sensitive data within their processes.
 The combination of data objects, categorization, and precise permission settings ensures that sensitive information like credit card numbers is protected and accessible only to those with the necessary authorization.
+
+```{tags} reference, building_diagrams
+```

docs/Building_Diagrams/data_stores.md

@@ -160,3 +160,6 @@ This JSON array contains various Gatorade flavors, each with attributes for `nam
 ⚠  In the data store creation, you will see fields like 'Name' and 'Identifier'. If you are using script tasks that interacts with the data store, reference the `identifier` exactly as it is named in the data store configuration.
 ```
 By integrating a JSON data store within a BPMN process, workflows can dynamically manage and interact with structured data.
+
+```{tags} reference, building_diagrams
+```

docs/Building_Diagrams/dmn.md

@@ -52,4 +52,7 @@ Expression for Range:
 - For values from 7 to 10 inclusive: 7 <= ? <= 10
 - For values from 10 to 12 inclusive: 10 <= ? <= 12
 
-These expressions set up the conditions in a way that the DMN engine can clearly understand and process, ensuring that the workflow behaves as expected based on the input values.
+These expressions set up the conditions in a way that the DMN engine can clearly understand and process, ensuring that the workflow behaves as expected based on the input values.
+
+```{tags} reference, building_diagrams
+```

docs/Building_Diagrams/error_events.md

@@ -186,3 +186,6 @@ This example demonstrates the utility of expanded subprocesses for detailed inte
 
 Error Events in BPMN offer a nuanced approach to managing errors within business processes.
 By defining Error Start, End, and Boundary Events, BPMN provides process designers with the tools necessary to anticipate, signal, and handle errors efficiently.
+
+```{tags} reference, building_diagrams
+```

docs/Building_Diagrams/escalation_events.md

@@ -150,3 +150,6 @@ You may need to set additional properties for the escalation event, such as:
 - **Documentation**: Providing details on when the escalation should be triggered and how it should be handled.
 
 After setting up the escalation event, test the workflow to ensure the escalation is triggered under the right conditions and that the catch event handles it as expected.
+
+```{tags} reference, building_diagrams
+```

docs/Building_Diagrams/events.md

@@ -237,3 +237,7 @@ A message, much like a signal, will only be caught in an intermediate event if t
 ```{admonition} Note
 ⚠ Remember the key distinction between signals and message events is that while messages adhere to a one-to-one correspondence, signals can potentially relate to multiple recipients in a one-to-many fashion.
 ```
+
+```{tags} reference, building_diagrams
+
+```

docs/Building_Diagrams/exclusivegatewayexample.md

@@ -12,43 +12,48 @@ This example demonstrates the use of an Exclusive Gateway to manage conditional
 1. **User Task: Show User Form**
 
 ![User Task](images/exclusivegatewayexample1.png)
+
 - **Purpose**: Captures user data which influences pathway decisions.
 - **Form Configuration**:
-     ```json
-     {
-       "title": "First Name Required",
-       "type": "object",
-       "required": ["firstName"],
-       "properties": {
-         "firstName": {
-           "type": "string",
-           "title": "First name",
-           "default": "Chuck"
-         }
-       }
-     }
-     ```
-   - **Role**: Collects inputs that determine the execution path through the Exclusive Gateway.
+
+  ```json
+  {
+    "title": "First Name Required",
+    "type": "object",
+    "required": ["firstName"],
+    "properties": {
+      "firstName": {
+        "type": "string",
+        "title": "First name",
+        "default": "Chuck"
+      }
+    }
+  }
+  ```
+
+  - **Role**: Collects inputs that determine the execution path through the Exclusive Gateway.
 
 2. **Exclusive Gateway**: Evaluates the `firstName` property from the form to decide the subsequent pathway.
 
-    **Sequence Flows**:
+   **Sequence Flows**:
+
+   **a**. **Others**: Leads to a general greeting for users not named "Chuck."
+
+   ![Sequence Flows](images/exclusivegatewayexample3.png)
 
-    **a**. **Others**: Leads to a general greeting for users not named "Chuck."
+   **For 'Others' Sequence Flow**:
 
-    ![Sequence Flows](images/exclusivegatewayexample3.png)
-
-    **For 'Others' Sequence Flow**:
-    - **Condition Expression**: `firstName != "Chuck"`
-    - Goes to **Manual Task**: "Hello to Others" displays a greeting to non-Chuck users.
+   - **Condition Expression**: `firstName != "Chuck"`
+   - Goes to **Manual Task**: "Hello to Others" displays a greeting to non-Chuck users.
 
-    **b**. **Chuck**: Directs to a personalized greeting for users named "Chuck."
+   **b**. **Chuck**: Directs to a personalized greeting for users named "Chuck."
 
-    ![Sequence Flows](images/exclusivegatewayexample4.png)
-
-    **For 'Chuck' Sequence Flow**:
-    - **Condition Expression**: `firstName == "Chuck"`
-    - Goes to **Manual Task**: "Hi to Chuck" delivers a custom greeting to users named Chuck.
+   ![Sequence Flows](images/exclusivegatewayexample4.png)
+
+   **For 'Chuck' Sequence Flow**:
+
+   - **Condition Expression**: `firstName == "Chuck"`
+   - Goes to **Manual Task**: "Hi to Chuck" delivers a custom greeting to users named Chuck.
 
 3. **Exclusive Gateway Merge**: Merges the paths from manual tasks: "Hello to Others" and "Hi to Chuck," continuing to the next unified step in the process.
 
@@ -63,3 +68,7 @@ After the manual task, marks the completion of the process through the end event
 Therefore, Exclusive Gateways are critical in BPMN for managing decisions within the workflow that require conditional logic based on user input or other process variables.
 
 They ensure that the process flow is correctly directed based on specific conditions, preventing incorrect executions and ensuring that the process adapts dynamically to varying inputs.
+
+```{tags} tutorial, building_diagrams
+
+```

docs/Building_Diagrams/gateways.md

@@ -167,3 +167,5 @@ It's also crucial to understand that conditions aren't required for incoming seq
 | 💻 Form                              | ⌨ Field Input                                 | 📝 Description                                                                        |
 | ------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------- |
 | ![conditions](images/conditions.png) | **Condition:** payment_method == "credit_card" | Python expression. Note that multiple conditions can be strung together using AND/OR. |
+
+**Keywords**: reference, building_diagrams, dev_docs

docs/Building_Diagrams/inclusivegatewayexample.md

@@ -54,3 +54,5 @@ This inclusive gateway setup is ideal for scenarios where multiple actions might
 
 By employing inclusive gateways, the process adapts dynamically to the user's specific needs without requiring separate processes or redundant tasks for different combinations of travel modes.
 
+```{tags} explanation, building_diagrams
+```

docs/Building_Diagrams/learn_basics.md

@@ -88,3 +88,6 @@ These elements can be arranged either horizontally or vertically.
 Not only do swimlanes organize activities into separate categories, but they also reveal delays, inefficiencies, and the individuals responsible for each step in a process.
 
 ![Untitled](images/BPMN_swimlane-500x197.png)
+
+```{tags} reference, building_diagrams
+```

docs/Building_Diagrams/message_events.md

@@ -139,4 +139,7 @@ Check out this example on Message Event.
 :maxdepth: 1
 :caption: Message Event Example
 message_example_event.md
-```
+```
+
+```{tags} how_to_guide, building_diagrams
+```

docs/Building_Diagrams/message_example_event.md

@@ -69,4 +69,7 @@ To ensure that messages are delivered to the correct process instance, correlati
 
 ![Message Example](images/message_example4.png)
 
-By using messages and correlation properties, you can effectively manage communication between multiple BPMN processes. This ensures that the right data reaches the right process at the right time, allowing for dynamic and responsive workflows. 
+By using messages and correlation properties, you can effectively manage communication between multiple BPMN processes. This ensures that the right data reaches the right process at the right time, allowing for dynamic and responsive workflows.
+
+```{tags} how_to_guide, building_diagrams
+```

docs/Building_Diagrams/multiinstance.md

@@ -167,3 +167,6 @@ The task is marked with a loop indicator, and the loop condition ensures the tas
 4. **End Event**: Marks the completion of the process once the loop condition is no longer satisfied.
 
 This example illustrates the use of a standard loop in BPMN to model repetitive actions within a workflow, showcasing how loops can automate iterative tasks based on dynamic conditions.
+
+```{tags} tutorial, building_diagrams
+```

docs/Building_Diagrams/parallelgatewayexample.md

@@ -26,3 +26,6 @@ After the script task, signal the successful completion of the process with the
 **Output**:
 After running the task, it will compute and show the result:
 ![Parallel Gateway Example](images/parallel_gateway_ex2.png)
+
+```{tags} explanation, building_diagrams
+```

docs/Building_Diagrams/pools_and_lanes.md

@@ -207,3 +207,6 @@ For example, a process might involve several departments or roles, each represen
 ```{admonition} Note
 ⚠ Specifying a user group in the `lane_owners` dictionary in a script task does not require it to previously exist in the database.
 ```
+
+```{tags} how_to_guide, building_diagrams
+```

docs/Building_Diagrams/service_tasks.md

@@ -99,3 +99,5 @@ Below is workflow overview:
    - **url**: `'https://api.bamboohr.com/api/gateway.php/{your_company_subdomain}/v1/employees/directory'`
      - Replace `{your_company_subdomain}` with your BambooHR subdomain.
 
+```{tags} how_to_guide, building_diagrams
+```

docs/Building_Diagrams/signal_events.md

@@ -163,3 +163,6 @@ After starting the task, the signal buttons "Eat Cheetos" and "Eat Spam" will ap
 Clicking on any button will lead to the respective manual task.
 
 ![signal_event_example](images/Signal_events_spiff_example3.png)
+
+```{tags} reference, building_diagrams
+```

docs/Building_Diagrams/sub-processes_and_call_activities.md

@@ -118,3 +118,6 @@ A restaurant management workflow handles customer orders, calculates the bill, a
 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. 
+
+```{tags} reference, building_diagrams
+```

docs/Building_Diagrams/task_data.md

@@ -15,3 +15,6 @@ Then, when the data is merged back together at a merging gateway, if multiple br
 Therefore, if you have tasks a, b, and c that run in parallel, it might not be a good idea for both a and b to set the "desired_withdrawal_amount" variable since, depending on how fast a and b run (and other implementation details around the parallel processing), the expected "winner" would not be knowable in advance.
 
 This general branching and merging strategy is applied to all parallel constructs, including inclusive gateways.
+
+```{tags} explanation, building_diagrams
+```

docs/Building_Diagrams/timer_events.md

@@ -129,3 +129,6 @@ Just remember to have a mechanism in place to eventually break out of the loop a
 💡 Note: Timer events, especially those set for short durations, may face delays of 20-30 seconds, varying with the number of active instances.
 Despite significant improvements, our ongoing efforts aim to further reduce these delays.
 ```
+
+```{tags} reference, building_diagrams
+```

docs/Building_Diagrams/user_tasks_and_forms.md

@@ -601,3 +601,5 @@ Open an incognito or private browsing window (not logged into Spiff). Navigate t
 
 The Guest User Task feature improves usability for non-logged-in users by allowing them to complete designated tasks seamlessly. 
 
+```{tags} how_to_guide, building_diagrams
+```

docs/Debugging_Diagrams/bpmn_unit_tests.md

@@ -46,3 +46,6 @@ The test will also fail if the process never completes or if an error occurs.
 Go to a process model and either click “Run Unit Tests” to run all tests for the process model or click on the “play icon” next to a "test_something.json" file.
 Next, you will see either a green check mark or a red x.
 You can click on these colored icons to get more details about the passing or failing test.
+
+```{tags} how_to_guide, debugging_diagrams
+```

docs/Debugging_Diagrams/executable_non_executable.md

@@ -36,3 +36,5 @@ In SpiffWorkflow, a process model can be either **Executable** or **Non-Executab
 | Workflow design phase                 | ❌                      | ✅                         |
 | System integration                    | ✅                      | ❌                         |
 
+```{tags} how_to_guide, debugging_diagrams
+```

docs/Debugging_Diagrams/process_error_handling.md

@@ -9,3 +9,6 @@ You can use this process model to handle the error in whatever way is most benef
 Process models often have ways to communicate with users--using an email connector if you use email, or a Slack connector if you use Slack, etc.--and you can use these same capabilities to inform the appropriate users when an error occurs.
 You can choose to ignore errors that occur in less important models, and you can escalate errors in other models to the CEO.
 Since you are using a process model, you have all the power you need to handle errors in a way that matches your business requirements.
+
+```{tags} explanation, debugging_diagrams
+```

docs/DevOps_installation_integration/Secrets.md

@@ -48,3 +48,6 @@ Secrets are only used in service tasks.
 
 Configuring secrets in SpiffArena provides a secure way to handle sensitive information in your BPMN diagrams.
 It allows you to make your processes public without exposing critical data, thereby enhancing both transparency and security.
+
+```{tags} how_to_guide
+```

docs/DevOps_installation_integration/admin_and_permissions.md

@@ -177,3 +177,6 @@ This similarity can help clarify or make it easier for you to understand the DMN
 
 To ensure that User Groups and Permissions take effect, it is necessary to run the process at least once.
 Whenever changes are made to any of these diagrams, like adding a user group or permission, the process should be started and completed successfully in order for the changes to be applied.
+
+```{tags} how_to_guide, dev_docs
+```

docs/DevOps_installation_integration/configure_connector_proxy.md

@@ -52,3 +52,6 @@ Run the process and once it's complete, you can see the response in the workflow
 You have successfully configured a `Connector Proxy` for use with `SpiffArena`.
 You made a call from a workflow to get a dog fact.
 Now, imagine if that call was to communicate with an external system relevant to your business processes.
+
+```{tags} how_to_guide, devops
+```

docs/DevOps_installation_integration/deploy_aws_lambda.md

@@ -65,3 +65,6 @@ Click your function URL again to see a greeting from our deployed Connector Prox
 
 Congratulations, your Connector Proxy has been deployed as a Lambda function.
 For information on configuring SpiffArena to use the new Connector Proxy URL, please see [Configure a Connector Proxy](configure_connector_proxy).
+
+```{tags} how_to_guide, devops
+```

docs/DevOps_installation_integration/deployment.md

@@ -26,3 +26,6 @@ graph TD;
 
 API, Celery Worker, Connector Proxy, and Frontend can run any number of replicas.
 The Background container is like a cron container, so it should run only one replica.
+
+```{tags} how_to_guide
+```

docs/DevOps_installation_integration/okta_config.md

@@ -81,4 +81,7 @@ For one of our users, the following setup was used to pass group information to
 🔗 **Helpful Links**:  
 - [Okta App Integration Wizard](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm)  
 - [Groups Claim Documentation](https://developer.okta.com/docs/guides/customize-tokens-groups-claim/main/)  
-- [Active Directory Groups in Okta](https://support.okta.com/help/s/article/Can-we-retrieve-both-Active-Directory-and-Okta-groups-in-OpenID-Connect-claims?language=en_US).  
+- [Active Directory Groups in Okta](https://support.okta.com/help/s/article/Can-we-retrieve-both-Active-Directory-and-Okta-groups-in-OpenID-Connect-claims?language=en_US).  
+
+```{tags} how_to_guide, devops
+```

docs/DevOps_installation_integration/path_based_routing.md

@@ -47,3 +47,6 @@ SPIFFWORKFLOW_BACKEND_WSGI_PATH_PREFIX=/api
 
 This will be used as the WSGI `SCRIPT_NAME`, which essentially removes the prefix before handing the URL to the app for routing, but also allows URLs generated by the app to return things like /api/v1.0/status.
 WSGI is a standard for serving Python apps, and there are implementations like Gunicorn, Green Unicorn, uWSGI, mod_wsgi, CherryPy, etc.
+
+```{tags} how_to_guide, devops
+```

docs/DevOps_installation_integration/permission_url.md

@@ -126,3 +126,6 @@ It provides administrator-level permissions, allowing the user to perform any ac
   /users/exists/by-username:
   /users/search:
 ```
+
+```{tags} reference
+```