From f22ade96e391c63fa404b537987f30feda112230 Mon Sep 17 00:00:00 2001 From: Steven Chand Date: Wed, 26 Aug 2026 14:14:11 -0700 Subject: [PATCH] Document inventory field variables in Long Text fields (sc-17836) Covers both surfaces that shipped in frontend#2822 / backend#3492: the variable picker in a Long Text field's template editor (Settings) and in the field's value on an individual record. Documents the behavior as implemented rather than as specified. The story called for one-level resolution and for the edited field to remain in its own picker; what shipped resolves two levels with cycle detection and excludes self, so the guidance follows the code. The Long Text entry in _field-types.qmd is split into inventory- and artifact-scoped variants, following the pattern the Attachments entry already uses in that file. Variables apply only to inventory record fields, so the artifact page and the RevealJS training deck (which renders the include in an artifact context) keep the original text. Co-Authored-By: Claude Opus 5 --- site/guide/inventory/_field-types.qmd | 9 +++++++- .../inventory/_field-variable-resolution.qmd | 21 ++++++++++++++++++ .../inventory/_insert-field-variables.qmd | 16 ++++++++++++++ .../guide/inventory/edit-inventory-fields.qmd | 15 +++++++++++++ .../inventory/manage-inventory-fields.qmd | 22 ++++++++++++++++++- 5 files changed, 81 insertions(+), 2 deletions(-) create mode 100644 site/guide/inventory/_field-variable-resolution.qmd create mode 100644 site/guide/inventory/_insert-field-variables.qmd diff --git a/site/guide/inventory/_field-types.qmd b/site/guide/inventory/_field-types.qmd index 4738e3e00..7190904d6 100644 --- a/site/guide/inventory/_field-types.qmd +++ b/site/guide/inventory/_field-types.qmd @@ -255,11 +255,18 @@ Date Time Email : Text value in valid email (`user@domain.com`) format. +:::: {.content-visible when-format="html" when-meta="includes.inventory"} +Long Text +: Toggle **Enable rich text formatting** to create a template using the rich text editor. With rich text formatting enabled, you can reference other field values on the record by inserting them as variables — in the template^[[Insert field variables into a Long Text template](/guide/inventory/manage-inventory-fields.qmd#insert-field-variables)] and in the value on an individual record.^[[Insert field variables into a Long Text field](/guide/inventory/edit-inventory-fields.qmd#insert-field-variables)] +:::: + +:::: {.content-visible when-format="html" when-meta="includes.artifacts"} Long Text : Toggle **Enable rich text formatting** to create a template using the rich text editor. +:::: Multiple Select -: Click **{{< fa plus >}} Add Option** to define a list of options. +: Click **{{< fa plus >}} Add Option** to define a list of options. Number : Text value in valid number format. Number display (comma, fullstop, etc.) is determined by your browser's locale. Select a **Number Type**: diff --git a/site/guide/inventory/_field-variable-resolution.qmd b/site/guide/inventory/_field-variable-resolution.qmd new file mode 100644 index 000000000..057fb82b9 --- /dev/null +++ b/site/guide/inventory/_field-variable-resolution.qmd @@ -0,0 +1,21 @@ + + +Variables resolve when the field is displayed, so a referenced value stays current as the record changes. Inventory exports contain the resolved values rather than the variables.^[[Export inventory](/guide/reporting/export-inventory.qmd)] + +Where a value can't be shown, {{< var vm.product >}} displays a marker in place of the variable so that you can tell restricted or unresolvable content apart from an empty field: + +{{< fa lock >}} **Access denied** +: You don't have read permissions for that field.^[[Manage permissions](/guide/configuration/manage-permissions.qmd)] The value is never sent to your browser. + +**Circular reference** +: Two or more fields reference each other in a loop. + +**Exceeded max depth** +: Expansion stopped at two levels. If you reference a Long Text field that itself contains variables, those nested variables resolve one level further — anything beyond that is not expanded. + +::: {.callout title="Attestation snapshots keep the values they were captured with."} +Variables in a snapshot resolve from the snapshot itself, not from the current record, so an attestation continues to show the values as of the time it was captured.^[[Working with attestations](/guide/attestation/working-with-attestations.qmd)] + +::: diff --git a/site/guide/inventory/_insert-field-variables.qmd b/site/guide/inventory/_insert-field-variables.qmd new file mode 100644 index 000000000..298beafa5 --- /dev/null +++ b/site/guide/inventory/_insert-field-variables.qmd @@ -0,0 +1,16 @@ + + +3. Click **{ } Insert Variable {{< fa angle-down >}}** in the rich text editor toolbar. + +4. Select the variable you want to reference from the **Record {{< fa arrow-right >}}** drop-down menus: + + - **Core Fields** — Default fields on the record. + - `{Group}` — Custom fields, listed under the inventory field group they belong to.^[[Add inventory field groups](/guide/inventory/manage-inventory-fields.qmd#add-inventory-field-groups)] + - **No Group** — Custom fields that aren't assigned to a group. + - **Stakeholders** — Assigned users, by record stakeholder type.^[[Manage record stakeholder types](/guide/configuration/manage-record-stakeholder-types.qmd)] + + Only fields available on the record type are listed. Artifact fields cannot be referenced,^[[Manage artifact fields](/guide/validation/manage-artifact-fields.qmd)] and a field can't reference itself — the field you're editing is left out of its own drop-down. + +5. Click **Save** to apply your changes. diff --git a/site/guide/inventory/edit-inventory-fields.qmd b/site/guide/inventory/edit-inventory-fields.qmd index 6bddba7eb..16ed7ba27 100644 --- a/site/guide/inventory/edit-inventory-fields.qmd +++ b/site/guide/inventory/edit-inventory-fields.qmd @@ -87,6 +87,19 @@ Learn more: [Work with content blocks](/guide/documentation/work-with-content-bl ::: +### Insert field variables into a Long Text field + + +On a **Long Text** field that has rich text formatting enabled,[^13] you can reference other field values on the same record instead of retyping them — for example, composing a summary that stays in sync with the record's owner, tier, and review dates. + +1. On the record's detail page, click on the Long Text field you want to edit. + +2. In the rich text editor: + +{{< include /guide/inventory/_insert-field-variables.qmd >}} + +{{< include /guide/inventory/_field-variable-resolution.qmd >}} + ### Manage attachments on records @@ -162,6 +175,8 @@ In addition to editing individual fields on a per record basis, you can edit fie [^12]: [Customize inventory layout](/guide/inventory/customize-inventory-layout.qmd#swap-between-views) +[^13]: [Inventory field types](manage-inventory-fields.qmd#inventory-field-types) + diff --git a/site/guide/inventory/manage-inventory-fields.qmd b/site/guide/inventory/manage-inventory-fields.qmd index 42dd03367..7fed8f06c 100644 --- a/site/guide/inventory/manage-inventory-fields.qmd +++ b/site/guide/inventory/manage-inventory-fields.qmd @@ -87,6 +87,24 @@ For example, if you first search by keyword for `date` under **Title** without c {{< include /guide/inventory/_add-edit-inventory-fields.qmd >}} +### Insert field variables into a Long Text template + + +Reference other field values from a Long Text template so that every record of that type starts from the same structure — for example, a summary that pulls in a record's owner and tier alongside your own narrative. + +1. Add or edit a **Long Text** inventory field, then toggle **Enable rich text formatting** on.[^insert-variables] + +2. In the template editor: + +{{< include /guide/inventory/_insert-field-variables.qmd >}} + +::: {.callout-important title="A template can only reference fields that all of its record types share."} +Because a template is applied to records of every **Inventory Record Type** you assign the field to, only variables available on all of those types can be inserted. Assign at least one record type before inserting variables. + +::: + +{{< include /guide/inventory/_field-variable-resolution.qmd >}} + ### Rename custom field keys To rename the field keys for custom inventory fields: @@ -161,4 +179,6 @@ Deleted records and archived workflows no longer block field deletion, even if t [^8]: [Manage record stakeholder types](/guide/configuration/manage-record-stakeholder-types.qmd) -[^9]: [Add or edit inventory fields](#add-or-edit-inventory-fields) \ No newline at end of file +[^9]: [Add or edit inventory fields](#add-or-edit-inventory-fields) + +[^insert-variables]: [Add or edit inventory fields](#add-edit) \ No newline at end of file