Document vm_today and datetime support in calculated fields

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

site/guide/model-inventory/_example-next-review-date-and-days-remaining.qmd

@@ -0,0 +1,126 @@
+<!-- Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+Refer to the LICENSE file in the root of this repository for details.
+SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial -->
+
+:::: {.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.
+:::
+:::
+
+::::

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"}:
 

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:

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: