Updated docs — Workflows

release-scripts/generate-release-notes.ipynb

@@ -222,9 +222,9 @@
     "\n",
     "### Create release folder and file\n",
     "\n",
-    "These lines will create a folder inside of `~/site/releases` for the release notes with a new `release-notes.qmd` file. The folder name is the release date, as per our convention. \n",
+    "These lines will create a folder inside of `~/site/releases` for the new release notes to live in and sets stage for the release notes to be generated. The folder name is the release date, as per our convention. \n",
     "\n",
-    "**If the directory and file already exists, you will be prompted to confirm whether or not you want to overwrite the contents.**"
+    "**If the directory and release file already exists, you will be prompted to confirm whether or not you want to overwrite the contents.**"
    ]
   },
   {
@@ -243,7 +243,9 @@
     "<a id='toc3_2_'></a>\n",
     "\n",
     "### Add the date to release notes \n",
-    "This block writes the specified date as the title of the new release notes file."
+    "This block writes the specified date as the title of the new release notes file.\n",
+    "\n",
+    "**It will also open up the newly created `release-notes.qmd` file for you so you don't have to go looking for it.**"
    ]
   },
   {

release-scripts/generate_release_objects.py

@@ -453,6 +453,7 @@ def create_release_folder(formatted_release_date):
     # Create directory and output file
     os.makedirs(directory_path, exist_ok=True)
     print(f"{output_file} will be created or overwritten")
+
     return output_file
 
 def create_release_qmd(output_file, original_release_date):
@@ -468,6 +469,11 @@ def create_release_qmd(output_file, original_release_date):
     with open(output_file, "w") as file:
         file.write(f"---\ntitle: \"{original_release_date}\"\n---\n\n")
 
+    try:
+        subprocess.run(["code", output_file], check=True)
+    except Exception as e:
+        print(f"Error opening the file in VS Code: {e}")
+
 def update_release_components(release_components, categories):
     """
     Updates a dictionary of release components with the given categories.

release-scripts/year-end-cleanup.ipynb

@@ -203,7 +203,9 @@
     "\n",
     "### Create yearly listing page \n",
     "\n",
-    "This cell copies the template from `~internal/templates/yearly-releases.qmd` and slots it into the new yearly folder as `{year}-releases.qmd` so we can begin building the yearly listings."
+    "This cell copies the template from `~internal/templates/yearly-releases.qmd` and slots it into the new yearly folder as `{year}-releases.qmd` so we can begin building the yearly listings.\n",
+    "\n",
+    "**It will also open up the newly created `{year}-releases.qmd` file for you so you don't have to go looking for it.**"
    ]
   },
   {

release-scripts/yearly_cleanup.py

@@ -3,6 +3,7 @@
 import re
 import shutil
 from IPython import get_ipython
+import subprocess
 
 ansi_escape = re.compile(r'\x1B\[[0-?]*[ -/]*[@-~]')
 
@@ -140,6 +141,11 @@ def copy_template(yearly_path, year):
         shutil.copy(template_path, destination_file)
         print(f"Copied '../internal/templates/yearly-releases.qmd' template to: '{destination_file}'")
 
+        try:
+            subprocess.run(["code", destination_file], check=True)
+        except Exception as e:
+            print(f"Error opening the file in VS Code: {e}")
+
         return destination_file
 
     except Exception as e:
@@ -490,7 +496,7 @@ def search_links(yearly_path):
     matching_files = 0
     total_lines_found = 0
 
-    print("Searching for relative links in moved release notes that may need adjusting...\n")
+    print("Searching for relative links in moved release notes that may need adjusting ...\n")
 
     for root, _, files in os.walk(search_dir):
         for file in files:

site/guide/model-workflows/_configure-workflow-steps.qmd

@@ -7,10 +7,10 @@ To add or edit workflow steps:
 
 1. Click on **Inventory Model**:
 
-    - To add a step, drag and drop a new step onto the canvas. Hover over the step until the **{{< fa ellipsis-vertical >}}** menu appears, then click on it and select **{{< fa gear >}} Configure**.
-    - On the new step, click **{{< fa gear >}} Configure**.
+    - To add a step, drag and drop a new step onto the canvas. 
+    - Double-click the new step to open up the configuration modal.
 
-1. After you're finished with step configuration, click **Save** to apply your changes before closing the configuration panel with **{{< fa x >}}**. 
+1. After you're finished with step configuration, click **Update Step** to apply your changes before closing the configuration panel with **{{< fa x >}}**. 
 
     ![Workflow step configuration](/guide/model-workflows/configure-steps.gif){fig-alt="A gif workflow step configuration" .screenshot}
 
@@ -31,10 +31,10 @@ To add or edit workflow steps:
 
 1. Click on **Inventory Model**:
 
-    - To add a step, drag and drop a new step onto the canvas. Hover over the step until the **{{< fa ellipsis-vertical >}}** menu appears, then click on it and select **{{< fa gear >}} Configure**.
-    - On the new step, click **{{< fa gear >}} Configure**.
+    - To add a step, drag and drop a new step onto the canvas.
+    - Double-click the new step to open up the configuration modal.
 
-1. After you're finished with step configuration, click **Save** to apply your changes before closing the configuration panel with **{{< fa x >}}**. 
+1. After you're finished with step configuration, click **Update Step** to apply your changes before closing the configuration panel with **{{< fa x >}}**. 
 
 1. After you've configured a step, you can then link your workflow together.
 

site/guide/model-workflows/_link-workflow-steps.qmd

@@ -7,13 +7,17 @@ To initiate the beginning of your workflow:^[After you’ve [configured your wor
 
 ### Link steps together
 
+::: {.callout}
+Hover over a workflow step to view an animation of the steps connecting to and from that step.
+:::
+
 To link subsequent steps together:
 
 1. Click **{{< fa circle >}}** above or below the earlier step and drag it to connect to the top **{{< fa circle >}}** on the subsequent step.
 
     You're also able to link several different steps together at various points in the workflow, including stages that may circle back to previous steps: 
 
-    ![Multiple steps linked together at various points in the default Inventory Model workflow](/guide/model-workflows/linked-workflow.png){fig-alt="A screenshot showing an example of multiple steps linked together at various points in the default Inventory Model workflow" .screenshot}
+    ![Multiple steps linked together at various points in the default Inventory Model workflow](/guide/model-workflows/linked-workflow.gif){fig-alt="An animated gif showing an example of multiple steps linked together at various points in the default Inventory Model workflow" .screenshot}
 
 1. When you are finished, click **Save Workflow** to apply your changes.
 
@@ -34,7 +38,7 @@ To link subsequent steps together:
 
     You're also able to link several different steps together at various points in the workflow, including stages that may circle back to previous steps:
 
-    ![Multiple steps linked together at various points in the default Inventory Model workflow](/guide/model-workflows/linked-workflow.png){fig-alt="A screenshot showing an example of multiple steps linked together at various points in the default Inventory Model workflow" .screenshot}
+    ![Multiple steps linked together at various points in the default Inventory Model workflow](/guide/model-workflows/linked-workflow.gif){fig-alt="An animated gif showing an example of multiple steps linked together at various points in the default Inventory Model workflow" .screenshot}
 
 1. When you are finished, click **Save Workflow** to apply your changes.
 

site/guide/model-workflows/_model-workflows-see.qmd

@@ -8,7 +8,14 @@
     - Click **{{< fa arrow-right-arrow-left >}} See Workflow** to open the detailed workflow associated with that model.
     - The current workflow state will be highlighted on this detail view.
 
-   ![Summary view of example workflow steps for a model](/guide/model-workflows/model-workflow.png){width=85% fig-alt="A summary view of example workflow steps for a model" .screenshot}
+   ![Summary view of example workflow steps for a model](/guide/model-workflows/model-workflow.png){fig-alt="A summary view of example workflow steps for a model" .screenshot}
+
+<!-- 2025-jan-07 // There is a bug ATM where this doesn't work: https://app.shortcut.com/validmind/story/7998/viewing-a-model-workflow-doesn-t-have-hover-animations -->
+
+::: {.callout}
+Hover over a workflow step to view an animation of the steps connecting to and from that step.
+
+:::
 
 While your lifecycle statuses and workflows are custom to your organization, some examples are:
 

site/guide/model-workflows/customize-model-lifecycle-statuses.qmd

@@ -29,7 +29,7 @@ Model lifecycle statuses are manipulated via workflow transitions and are used t
     - To add a status, click **{{< fa plus >}} Add New Model Lifecycle Status**.
     - To edit a status, click on the status itself. 
 
-3. On the status detail popup that appears:
+3. On the Add Model Lifecycle Status modal that appears:
 
     a. Provide a status **[name]{.smallcaps}** 
     b. Provide a status **[description]{.smallcaps}** 
@@ -45,7 +45,7 @@ Model lifecycle statuses are manipulated via workflow transitions and are used t
 
 1. In the left sidebar, click **{{< fa gear >}} Settings**.
 
-2. Under Workplace Settings, select **Statuses**.
+2. Under Workplace Settings, select **Model Lifecycle Statuses**.
 
 3. Hover over the status you'd like to delete, and click **{{< fa trash-can >}} Delete**.
 

site/guide/model-workflows/set-up-model-workflows.qmd

@@ -125,21 +125,18 @@ Please note that roles or users must be assigned to the **Approval Group** field
 | [approval message]{.smallcaps} | When your resource reaches this approval step, the users in the selected group will recieve the following message. |
 : **Approval Group** step configuration {.hover tbl-colwidths="[35,65]"}
 
-
-![Approval message shown to the APPROVAL GROUP](approvals-message.png){fig-alt="A screenshot showing the approval message shown to the APPROVAL GROUP" .screenshot group="approval"}
-
 :::: {.flex .flex-wrap .justify-around}
 
 ::: {.w-50-ns}
-
-![APPROVAL GROUP step configuration with an inventory field selection of Approval Users](approval-group-setup.png){fig-alt="A screenshot showing an APPROVAL GROUP step configuration with a inventory field selection of Approval Users" .screenshot group="approval"}
+![APPROVAL GROUP step configuration with a User Roles selection of Validator](configure-approval-step.png){fig-alt="A screenshot showing an APPROVAL GROUP step configuration with a User Roles selection of Validator" .screenshot group="approval"}
 
 :::
 
 ::: {.w-40-ns}
+![Setup for the Approval Message shown to the APPROVAL GROUP of User Roles — Validator](approval-group-setup.png){fig-alt="A screenshot showing the setup for the Approval Message shown to the APPROVAL GROUP of User Roles — Validator" .screenshot group="approval"}
 
 Example
-: A message shown to the user type inventory field `Approval Group` users requesting approval of model documentation.
+: A message shown to the User Roles — Validator requesting review of a model for compliance.
 
 :::
 
@@ -156,7 +153,7 @@ Workflows cannot be saved until condition branches are connected to other steps.
 To configure a condition branch:
 
 1. On the Configure Condition Branch module, click **+ Add Branch**.
-2. Enter in the **[name]{.smallcaps}** and designate the **[conditions]{.smallcaps}**[^12] that apply to this path.
+2. Enter in the **[path name]{.smallcaps}** and designate the **[conditions]{.smallcaps}**[^12] that apply to this path.
 3. Continue with steps 1 and 2 until your conditional branch logic is complete.
 
     To remove a path, click **{{< fa ellipsis-vertical >}}** and select **{{< fa trash-can >}} Remove Path**.
@@ -167,7 +164,7 @@ To configure a condition branch:
 For example, if you wanted your models where the field `GenAI Model` is set to `true` to undergo a special legal approval process:
 
 - First, you'd set up a Condition Branch path to look for instances where `GenAI Model` is set to `true`.
-- Then, you would add an Approval step[^14] that requests a review of the model from the User group `Legal Team`.
+- Then, you would add an Approval step[^14] that requests a review of the model from the User Roles — `Legal Team`.
 - Finally, configure the `default` path to bypass this special approval. 
 
 :::: {.flex .flex-wrap .justify-around}
@@ -178,13 +175,16 @@ For example, if you wanted your models where the field `GenAI Model` is set to `
 :::
 
 ::: {.w-50-ns}
-![Legal team Approval step configuration](legal-team-approval.png){fig-alt="Screenshot showing the Legal team Approval step configuration" .screenshot group="condition"}
+![Legal Team Approval step configuration](legal-team-approval.png){fig-alt="Screenshot showing the Legal Team Approval step configuration" .screenshot group="condition"}
 
 :::
 
 ::::
 
-![Example Condition Branch where GenAI models require special approval from the User group Legal Team](example-condition-branch.png){fig-alt="A screenshot showing an example Condition Branch where GenAI models require special approval from the User group Legal Team" .screenshot group="condition"}
+::: {.column-margin}
+![Example Condition Branch where GenAI models require special approval from the User Roles — Legal Team](example-condition-branch.png){fig-alt="A screenshot showing an example Condition Branch where GenAI models require special approval from the User Roles — Legal Team" .screenshot group="condition"}
+
+:::
 
 ### Add conditional requirements
 
@@ -195,7 +195,7 @@ Conditional requirements can be configured for all four available step types:
 | Status Change | Under **[when these conditions are met]{.smallcaps}**, you are able to set both `AND` and `OR` conditions. |
 | User Action | Under **[display action button when]{.smallcaps}**, you are able to set both `AND` and `OR` conditions.  |
 | Approval | Under **[threshold]{.smallcaps}**, you are able to set the minimum percentage of approvers required for the resource to be approved. |
-| Condition Branch | Under each branch's **[conditions]{.smallcaps}**, you're able to designate the conditions that apply to that path. |
+| Condition Branch | Under each branch's **[conditions]{.smallcaps}**, you're able to designate the `AND` and `OR` conditions that apply to that path. |
 : Step type conditional options {.hover tbl-colwidths="[20,80]"}
 
 For Status Change[^15], User Action[^16], and Condition Branch[^17] conditions, you're able to add a single independent **Rule** or a linked condition **Group**. These rules and groups can be nested if desired:
@@ -219,7 +219,10 @@ Approval steps need to be subsequently linked to both a [Rejected]{.bubble .red
 
 3. Connect the **Approval** step to the [Rejected]{.bubble .red .red-bg} and [Approved]{.bubble .green .green-bg} **Status Change** steps with the red and green **{{< fa circle >}}** respectively by dragging from the colored **{{< fa circle >}}** to the top **{{< fa circle >}}** of the subsequent step.
 
-![Linked REJECTED and APPROVED Status Change steps](approved-rejected.png){fig-alt="A screenshot showing linked REJECTED and APPROVED Status Change steps" .screenshot}
+::: {.column-margin}
+![Linked REJECTED and APPROVED Status Change steps](approval-group-setup.png){fig-alt="A screenshot showing linked REJECTED and APPROVED Status Change steps" .screenshot}
+
+:::
 
 ## Delete workflow steps
 

site/guide/model-workflows/working-with-model-workflows.qmd

@@ -35,24 +35,7 @@ To review the overall workflow status for a model:
 
 {{< include _model-workflows-see.qmd >}}
 
-![Detailed workflow under the MODEL STATUS section](see-workflow.gif){fig-alt="A gif showing the detailed workflow under the MODEL STATUS section" .screenshot}
-
-<!-- Model documentation stauses/workflows have been removed as of Aug 2024 -->
-
-<!-- #### See model documentation statuses
-
-To review the workflow status of a model's documentation:
-
-1. In the left sidebar, click **{{< fa cubes >}} Inventory**.
-
-2. Select a model or find your model by applying a filter or searching for it.[^6]
-
-3. In the left sidebar that appears for your model, click **{{< fa book-open >}} Documentation**. 
-
-    On this **{{< fa book-open >}} Documentation** page, locate [document status]{.smallcaps}:
-
-    - Click **{{< fa arrow-right-arrow-left >}} See workflow** to open the detailed workflow associated with that model's documentation.
-    - The current workflow state will be highlighted on this detail view.  -->
+![Detailed workflow under the MODEL STATUS section](see-workflow.gif){fig-alt="A gif showing the detailed workflow under the MODEL STATUS section" .screenshot width=90%}
 
 ## Transition workflow statuses
 
@@ -66,22 +49,7 @@ To transition the overall workflow status for a model:
 
 {{< include _model-workflows-transition.qmd >}}
 
-![Transitioning a workflow status under the ACTIONS section](transition-workflow.gif){fig-alt="A gif showing transitioning a workflow status under the ACTIONS section" .screenshot}
-
-<!-- #### Transition model documentation statuses
-
-To transition the workflow status of a model's documentation:
-
-1. In the left sidebar, click **{{< fa cubes >}} Inventory**.
-
-2. Select a model or find your model by applying a filter or searching for it.[^8]
-
-3. In the left sidebar that appears for your model, click **{{< fa book-open >}} Documentation**.
-
-4.  If an action is available to your role, you'll see it listed under your document status under your **{{< fa book-open >}} Documentation** or **{{< fa shield >}} Validation Report**. 
-
-    - Click **{{< fa arrow-right >}}** to open up the transition panel for your selected action. This arrow will be followed by the action name.
-    - Enter your **Notes** then click **Submit**.  -->
+![Transitioning a workflow status under the ACTIONS section](transition-workflow.gif){fig-alt="A gif showing transitioning a workflow status under the ACTIONS section" .screenshot width=90%}
 
 ### Reset your model workflow
 
@@ -97,6 +65,7 @@ If you need to reset your model's workflow to the beginning:
 
     After you confirm, that model's workflow will be returned to its initial state. 
 
+![Resetting a workflow to its initial state](reset-workflow.gif){fig-alt="A gif showing resetting a workflow to its initial state" .screenshot width=90%}
 
 ## What's next