diff --git a/site/guide/model-inventory/_add-edit-inventory-fields.qmd b/site/guide/model-inventory/_add-edit-inventory-fields.qmd index 127bb57cbe..2317339d86 100644 --- a/site/guide/model-inventory/_add-edit-inventory-fields.qmd +++ b/site/guide/model-inventory/_add-edit-inventory-fields.qmd @@ -23,6 +23,8 @@ a. Include optional information for your field: a. When you are satisfied with the setup of your inventory field, click **Save**. +{{< include /guide/model-inventory/_example-next-review-date-and-days-remaining.qmd >}} + ### Edit inventory fields #### Edit custom inventory fields diff --git a/site/guide/model-inventory/_example-next-review-date-and-days-remaining.qmd b/site/guide/model-inventory/_example-next-review-date-and-days-remaining.qmd new file mode 100644 index 0000000000..187aba895b --- /dev/null +++ b/site/guide/model-inventory/_example-next-review-date-and-days-remaining.qmd @@ -0,0 +1,126 @@ + + +:::: {.content-visible unless-format="revealjs"} + +::: {.callout-button .pl4 .nt2} +::: {.callout collapse="true" appearance="minimal"} + +### Example — Next review date & days remaining + +Combining different inventory field types provides a flexible way to automatically track model review schedules. This example creates fields that calculate the next review date based on approval date and validation frequency, adjusted by risk tier, and then computes the days remaining until that review. + +Common date and time field types available in your formulas include: + +- `vm_today` — Today's date (updates each time the formula runs) +- `date` — Python's `datetime.date` class +- `datetime` — Python's `datetime.datetime` class +- `timedelta` — Duration in days, seconds, or microseconds +- `relativedelta` — Duration in months, years, etc. (from `dateutil`) + +Here, we show you how to use `date`, `relativedelta`, and `vm_today`. + +#### Calculate the next review date + +Determine the next review date based on an approval date and a frequency of validation that adjusts based on the risk tier: + +1. Create an `Approved Date` date field. + +2. Create a `Frequency of Validation` string field with the following options: + + - Weekly + - Monthly + - Yearly + +3. Create a `Risk Tier` calculation field that depends on the frequency of validation: + + ```python + def formula(params): + if params.frequencyOfValidation == "Weekly": + return "Tier 1" + elif params.frequencyOfValidation == "Monthly": + return "Tier 2" + elif params.frequencyOfValidation == "Yearly": + return "Tier 3" + else: + return "N/A" + ``` + +4. Create a `Next Review Date` calculation field that depends on the `Approved Date` and `Risk Tier` fields: + + ```python + def formula(params): + """ + Calculate the next review date based on the approval date and review frequency. + + Args: + params.dmApprovedDate (str): The approval date in 'YYYY-MM-DD' format. + params.dmRiskTier (string): The review tier (Tier 1, Tier 2, or Tier 3). + + Returns: + datetime: The next review date. + """ + # Guard against empty dates + if params.dmApprovedDate == "": + return "N/A" + + # Convert the approved_on date string to a datetime object + approved_date = date.fromtimestamp((int(params.dmApprovedDate))/1000) + + # Define the review frequency mapping + review_frequency = { + "Tier 1": relativedelta(months=3), # Quarterly + "Tier 2": relativedelta(months=6), # Semi-annually + "Tier 3": relativedelta(years=1), # Annually + } + + # Get the appropriate time delta based on the tier + frequency = review_frequency.get(params.dmRiskTier) + if not frequency: + # "Invalid tier. Must be Tier 1, Tier 2, or Tier 3." + return "N/A" + + # Calculate the next review date + next_review_date = approved_date + frequency + return next_review_date.isoformat() + ``` + +![Adding a calculation type field that automatically calculates the next review date](calculation-field-next-review-date.png){fig-alt="A screenshot showing the screen for adding a calculation type field that automatically calculates the next review date" width=90% .screenshot} + +You can now determine the next review date in workflows by making a workflow depend on `Approved Date`. To test, change the `Approved Date` after the fact and see how `Next Review Date` changes. + +#### Calculate the days remaining until the next review + +1. Create a `Days Remaining` calculation field that depends on the `Next Review Date` field: + + ```python + def formula(params): + """ + Calculate days remaining until the next review. + + Args: + params.nextReviewDate (str): The next review date in ISO format. + + Returns: + str: Days remaining until review (example:"45 days remaining"). + """ + # Get next review date (stored as ISO format string) + next_review_date = getattr(params, "nextReviewDate", "") + if not next_review_date: + return "Not applicable" + next_review = date.fromisoformat(next_review_date) + + # Calculate days until review using built-in vm_today + difference = next_review - vm_today + return f"{difference.days} days remaining" + ``` + + +![Adding a calculation type field that automatically calculates the days remaining until the next review](calculation-field-days-remaining.png){fig-alt="A screenshot showing the screen for adding a calculation type field that automatically calculates the days remaining until the next review" width=90% .screenshot} + +You can now check the number of days remaining until the next review. +::: +::: + +:::: diff --git a/site/guide/model-inventory/_field-types.qmd b/site/guide/model-inventory/_field-types.qmd index 3a29d11c5e..677fa30897 100644 --- a/site/guide/model-inventory/_field-types.qmd +++ b/site/guide/model-inventory/_field-types.qmd @@ -22,7 +22,7 @@ Aggregation ::: {.callout-button .pl4 .nt4} ::: {.callout collapse="true" appearance="minimal"} -### Example — Aggregation Use Cases +### Example — Aggregation use cases ##### Open validation issue count @@ -78,7 +78,7 @@ Calculation ::: {.callout-button .pl4 .nt4} ::: {.callout collapse="true" appearance="minimal"} -### Example — Risk Tier Calculation +### Example — Risk tier calculation You have numeric model inventory fields of `materiality` and `complexity`, where a larger value indicates a lower risk. @@ -107,7 +107,6 @@ Your calculated field is grouped under `Model Risk` inventory fields, and can on ::: ::: - :::: :::: {.content-visible when-format="html" when-meta="includes.artifacts"} @@ -120,7 +119,7 @@ Your calculated field is grouped under `Model Risk` inventory fields, and can on ::: {.callout-button .pl4 .nt4} ::: {.callout collapse="true" appearance="minimal"} -### Use artifact types in your formulas to create dynamic calculations. +### Example — Use artifact types in your formulas to create dynamic calculations Use simple dot notation to include [artifact types](/guide/model-validation/manage-artifact-types.qmd){target="_blank"}: diff --git a/site/guide/model-inventory/calculation-field-days-remaining.png b/site/guide/model-inventory/calculation-field-days-remaining.png new file mode 100644 index 0000000000..b7044e1eec Binary files /dev/null and b/site/guide/model-inventory/calculation-field-days-remaining.png differ diff --git a/site/guide/model-inventory/calculation-field-next-review-date.png b/site/guide/model-inventory/calculation-field-next-review-date.png new file mode 100644 index 0000000000..718c8ce01d Binary files /dev/null and b/site/guide/model-inventory/calculation-field-next-review-date.png differ diff --git a/site/guide/model-inventory/manage-model-inventory-fields.qmd b/site/guide/model-inventory/manage-model-inventory-fields.qmd index 3970ac700f..1119c23448 100644 --- a/site/guide/model-inventory/manage-model-inventory-fields.qmd +++ b/site/guide/model-inventory/manage-model-inventory-fields.qmd @@ -22,6 +22,10 @@ includes: ::: +## Inventory field types + +{{< include /guide/model-inventory/_field-types.qmd >}} + ## View, search, and filter inventory fields 1. In the left sidebar, click **{{< fa gear >}} Settings**. @@ -87,10 +91,6 @@ To rename the field keys for custom inventory fields: {{< include /guide/model-inventory/_rename-field-keys.qmd >}} -#### Inventory field types - -{{< include /guide/model-inventory/_field-types.qmd >}} - ## Add inventory field groups To group model inventory fields, first create an inventory field group: diff --git a/site/guide/model-validation/manage-artifact-fields.qmd b/site/guide/model-validation/manage-artifact-fields.qmd index d9f5874395..1f2d6d15d4 100644 --- a/site/guide/model-validation/manage-artifact-fields.qmd +++ b/site/guide/model-validation/manage-artifact-fields.qmd @@ -21,6 +21,10 @@ includes: ::: +## Artifact field types + +{{< include /guide/model-inventory/_field-types.qmd >}} + ## View, search, and filter artifacts fields 1. In the left sidebar, click **{{< fa gear >}} Settings**. @@ -86,10 +90,6 @@ To rename the field keys for artifact fields: {{< include /guide/model-inventory/_rename-field-keys.qmd >}} -#### Artifact field types - -{{< include /guide/model-inventory/_field-types.qmd >}} - ## Add artifact field groups To group artifact fields, first create an artifact field group: