Configure Rules Based Narratives

Learn how to create outline templates with rules for narrative generation based on Case data.

About Rules Based Narratives

You can create Narrative Outline templates for different Case types, locations, and organizations. Narrative Outlines are composed of Narrative Statements, each with Narrative Statement Options where you can add the conditional rules that determine when Vault includes the associated Narrative Statement within a generated narrative and what Case data that statement includes. You can also order each Narrative Statement according to their appropriate alignment and sequence. Conditional rules and formulas allow you to create templates that generate grammatically correct, logical, orderly, and complete narratives, which require minimal editing from users.

When users run the Generate Narrative from Outline action on a Case, Vault generates a narrative document based on the type of Case. When users run the action on a Case that already has a narrative document, Vault:

• Re-renders and upversions the existing narrative document based on the applicable outline template.
• Generates Case Follow-Up Statements to track changes made since the action last ran, and includes those statements in the upversioned narrative to summarize the changes.
  • Vault does not generate Case Follow-Up Statements for Cases generated using the override merge method during automated Case promotion.

Types of Cases

You can create Narrative Outline templates to which Vault matches Case data for the following types:

• Post-Market Non-Serious: Applies to the following types of Cases:
  • Postmarket Cases (do not have Studies)
  • Non-clinical trial study Cases (Study Type is Other) with a Serious value of No or blank
• Post-Market Serious: Applies to the following types of Cases:
  • Postmarket Cases (do not have Studies)
  • Non-clinical trial study Cases (Study Type is Other) with a Serious value of Yes
• Clinical: Applies to clinical trial study Cases (Study Type is not Other)

Prerequisites

Before you can configure this feature in your Vault, you must complete all steps in Enable Rules Based Narrative Generation.

Overview

Complete the following procedures to configure Rules Based Narratives in your Vault:

1. Review the standard Narrative Outline records and activate and customize as needed.
2. Review Narrative Outlines using the Narrative Outline Preview report.
3. Define Narrative Outlines to use for each type of Case and, optionally, for specific locations and organizations.
4. Define Narrative Statements to specify the statements and their order Vault uses for each outline.
5. Define Narrative Statement Options to specify the content Vault includes in each statement.

Standard Records

Vault includes several standard Narrative Outline records that you can activate and customize for your organization’s needs by defining the Narrative Statement Outlines. You can update these custom records as needed or create new records from scratch, as applicable:

• Post-Market Non-Serious Sample Outline
• Post-Market Serious Sample Outline
• Clinical Sample Outline

Review Narrative Outlines

You can use the Narrative Outline Preview report to review a Narrative Outline and its associated Narrative Statements and Narrative Statement Options, including the conditions and formulas that define how Vault determines the narrative output. From within the report, select a record’s hyperlink name to open the record and, if applicable, make updates.

To view the report:

1. Access the report:
   • From a Narrative Outline record, select Preview Narrative Outline from the All Actions menu.
   • Navigate to Analytics > Reports > Narrative Outline View.
2. Select the Narrative Outline you want to review.
3. Select Continue.

Alternatively, you can access and create Narrative Outlines, Narrative Statements, and Narrative Statement Options in Business Admin.

Define Narrative Outlines

To define Narrative Outlines:

1. Navigate to the applicable standard record or create a new record.
2. Select the Case Type to which this template applies.
3. Optional: Select the Organization to which this template applies. If this field is blank, Vault does not consider it when matching a template to Case data.
4. Optional: Select the Localization to which this template applies. If this field is blank, Vault does not consider it when matching a template to Case data.
5. Select Save.
6. Add up to 100 Narrative Statements to this outline.
7. For each Narrative Statement, add up to 25 Narrative Statement Options to define the rules for when Vault includes the statement in a narrative.
8. In the Narrative Statement section, select the record to which you want to add options.
9. In the Narrative Statement Option section, open the applicable record or select Add.
10. In the Search: Narrative Statement Option window, select all applicable options.
11. Optional: Use the search bar and Filters to find specific records.
12. Optional: Select Create to create new records.
13. Select OK to add the selected options to the Narrative Statement.
14. Select Save.

Define Narrative Statements

To define Narrative Statements:

1. Navigate to the applicable standard record or create a new record.
2. Optional: Enter a description.
3. Optional: For Order in Outline, enter a numeric value to specify where in the template the statement appears.
4. Select a Paragraph Setting for the statement in the outline:
   • New Paragraph: Statement begins a new paragraph.
   • Concatenate to previous: Statement appends to the previously ordered statement.
5. Select Save or Save + Create to create another record.

Define Narrative Statement Options

To define Narrative Statement Options:

1. Navigate to the applicable standard record or create a new record.
2. Optional: Update or enter a Condition to specify when Vault includes the associated Narrative Statement in the narrative output. If you leave this field blank, Vault always considers the return to be true and includes the Narrative Statement.
3. Optional: Update or enter a Statement Formula to specify what content Vault includes for the associated Narrative Statement if the Condition returns true.
4. Optional: Select a Topic. This may help you to organize your options.
5. Optional: Define how you want to order statements in the output when Vault finds multiple records returned by the Statement Formula.
   • Select Multiple Records to specify the object for which you want to define an order.
   • Select an Order By value to specify the object field by which Vault will order statements.
6. Select Save.

Conditions

You can define Conditions for when Vault executes a Statement Formula and includes content for the associated Narrative Statement in a narrative. When a Condition returns true, Vault renders output based on the Statement Formula. When a Condition returns false, Vault ignores the Narrative Statement Option when generating the narrative. For more details about creating formulas, see Creating Formulas in Vault.

As a best practice, only one (1) Narrative Statement Option should return true for each Narrative Statement. If multiple options return true based on conditional criteria, Vault concatenates the Statement Formulas when generating the narrative.

When defining Conditions, you can use VQL, the functions and operators in the Vault Formula Reference Guide, and the following Safety-specific functions:

• VS_ANYOF
• VS_CONTAINS
• VS_HASONE
• VS_HASMANY
• VS_LET
• VS_MATCHES

VS_ANYOF

VS_ANYOF(array_expression, LAMBDA(array_element_alias, boolean_expression))

This function returns true or false depending on whether or not the boolean_expression is true for any of the array elements (array_element_alias) in the array_expression. For more information about this function, see Configure Custom Validation Criteria.

Example

The following example returns true if any Case Products have a Drug Role field value of Concomitant:

VS_ANYOF(case_version__v.case_products_case_version__vr, LAMBDA(cp, cp.drug_role__vr.api_name__v = 'concomitant__v'))

VS_CONTAINS

VS_CONTAINS(string array, string)

This function returns true or false depending on whether or not string is present inside string array. For more information about this function, see Configure Custom Validation Criteria.

VS_HASONE

VS_HASONE(objectreference)

This function returns true if there is exactly one (1) record of the specified object for the Case.

Example

The following example returns true if the Case Product has a Drug Role field value of Suspect, one (1) Case Product Dosage, and one (1) Case Product Indication:

VS_ANYOF(case_version__v.case_products_case_version__vr, LAMBDA(element, element.drug_role__vr.name__v = "Suspect" && VS_HASONE(element. case_product_dosages_case_product__vr) && VS_HASONE(element. case_product_indications__vr)))

VS_HASMANY

VS_HASMANY(objectreference)

This function returns true if there are multiple records of the specified object for the Case.

Example

The following example returns true if the Case Product has a Drug Role field value of Suspect, multiple Case Product Dosages, and multiple Case Product Indications:

VS_ANYOF(case_version__v.case_products_case_version__vr, LAMBDA(element, element.drug_role__vr.name__v = "Suspect" && VS_HASMANY(element.case_product_dosages_case_product__vr) && VS_HASMANY(element.case_product_indications__vr)))

VS_LET

VS_LET(var, path_to_validating_records, expression)

This function returns the result of a validation performed on the records of an object. For more information about this function, see Configure Custom Validation Criteria.

VS_MATCHES

VS_MATCHES(string, string)

This function returns true or false depending on whether or not string matches the regular expression (regex) in string. For more information about this function, see Configure Custom Validation Criteria.

Statement Formulas

Use VQL, expressions, and functions to define Statement Formulas to specify what content Vault includes for the associated Narrative Statement in a narrative if the Condition returns true. When defining Statement Formulas, you can use plain text, field references, VQL, Vault Platform operators, certain Vault Platform functions, and Safety-specific functions. For more details about creating formulas, see Creating Formulas in Vault.

Vault Platform Functions

The Statement Formula field supports the following Vault Platform functions:

• Math Functions:
  • Trunc
• Text Functions:
  • InitCap
  • Lower
  • Trim
  • Upper

Safety Functions

The Statement Formula field supports the following Safety-specific functions:

• VS_ExistCheck
• VS_OmitReason
• VS_PrefixDate
• VS_Repeat

The following syntax guidelines apply to these functions:

• To reference a field, use the following syntax: ${object_relation.field_api_name}
• If your function does not specify an object relationship, Vault assumes the specified field exists on the Case (case_version__v) object
• Specify object relationships as they relate to the Case (case_version__v) object
• To render quotation marks (“) and apostrophes (‘) within any output, include an escape sequence (\) before the character

VS_ExistCheck

${VS_ExistCheck(Object, PrimaryField, "text")}

This function renders an output when the specified field contains a value. You can nest up to three (3) VS_ExistCheck functions.

This function includes the following inputs:

• Object: Specifies the object on which the field exists
• PrimaryField: Specifies the field to confirm a value exists
• "text": Specifies the output to render if the PrimaryField value exists
  • Supports the listed Vault Platform and Safety functions as well as field references

Example

The following example returns an output when a value exists for the Case’s dob_idate__v field:

"The following is the patient\'s data related to birth: "${VS_ExistCheck(case_version__v, dob_idate__v, ${VS_PrefixDate(case_version__v, uppercase, dob_idate__v)} " the patient was born."}

Depending on the returned values, the rendered output may look like the following:

• When the Case’s dob_idate__v field contains a value: The following is the patient's data related to birth: In 2024 the patient was born.
• When the Case’s dob_idate__v field is blank: The following is the patient's data related to birth:

VS_OmitReason

${VS_OmitReason(Object, PrimaryField, ReasonOmitField)}

This function renders an output depending on if the specified PrimaryField or ReasonOmitField contains a value. If both fields are blank, the rendered output is unknown.

This function includes the following inputs:

• Object: Specifies the object on which the field exists
• PrimaryField: Specifies the field value to render
• ReasonOmitField: Specifies the field value to render if the PrimaryField is blank

Example

The following example returns an output depending on the values of Case’s dob_idate__v and dob_reason_omitted__v fields:

"The patient date of birth is " ${VS_OMITREASON(case_version__v, dob_idate__v, dob_reason_omitted__v)}

Depending on the returned values, the rendered output may look like the following:

• When the PrimaryField contains a value: The patient date of birth is 10-Nov-2024
• When the PrimaryField is blank: The patient date of birth is "unknown" due to reason omitted "Asked but Unknown"
• When the PrimaryField and ReasonOmitField fields are blank: The patient date of birth is unknown

VS_PrefixDate

${VS_PrefixDate(Object, Case, DateField, ReasonOmitField_optional)}

This function displays a date value in a specified format and renders an output depending on the specified DateField or ReasonOmitField_optional values. If both fields are blank, the rendered output is [On/on] an unknown date.

This function includes the following inputs:

• Object: Specifies the object on which the DateField exists
• Case: Specifies the output for when there is no DateField value
  • lowercase: on an unknown date
  • uppercase: On an unknown date
• DateField: Specifies the field value to render
• ReasonOmitField_optional: This optional input specifies the date field value to render if the DateField is blank

Example

The following example returns an output depending on the values of Case’s event_onset_idate__v and event_onset_reason_omitted__v fields:

${VS_PrefixDate(case_version__v, uppercase, event_onset_idate__v, event_onset_reason_omitted__v)}

Depending on the returned values, the rendered output may look like the following:

• When the DateField contains a value that specifies the following:
  • Day, month, and year: On 26-Sep-2024
  • Month and year: In Sep-2024
  • Year: In 2024
• When the DateField is blank: On an unknown date due to reason omitted "Asked But Unknown"
• When the DateField and ReasonOmitField_optional fields are blank: On an unknown date

VS_Repeat

${VS_Repeat(Object, condition, GroupBy_optional, "textOrFunctionToRepeat")}

This function allows you to evaluate the same formula multiple times with different values by supporting references to child and grandchild object relationships related to the Case object. When multiple records meet the condition, Vault executes the statement for each record and consolidates the output instead of returning multiple outputs, minimizing repetition in the generated narrative. Vault orders output values by earliest to latest or lowest to highest, as applicable, and duplicated values ordered by creation date. You can nest up to two (2) VS_Repeat functions.

This function includes the following inputs:

• Object: Specifies the object on which the fields exists
• Supports the following objects:
  • case_adverse_event__v
  • case_assessment_result__v
  • case_drug_history__v
  • case_medical_history__v
  • case_product__v
  • case_test_result__v
• condition : Specifies the conditions for which Vault considers records for the output
  • Supports the listed Vault Platform and Safety functions as well as field references
  • Supports the ALL operator, which allows you to include all Case children within the output
• GroupBy_optional: This optional input specifies how Vault groups multiple statements when multiple records meet the condition
• Supports the following fields:
  • assessment_result__v
  • date_normalized__v
  • drug_role__v
  • indication__v
  • onset_normalized__v
  • source_type__v
  • start_date_normalized__v
• Vault orders the rendered records by when it encounters the first record of each group
• "textOrFunctionToRepeat": Specifies which text or function repeats
  • Supports the listed Vault Platform and Safety functions as well as field references

Example

The following example repeats the phrase ${adverse event reported} (${adverse event coded}) with outcome ${outcome} when there are multiple Case Adverse Events that meet the specified condition:

${VS_Repeat(
    case_adverse_event__v,
    VS_ANYOF(case_version__v.case_adverse_events_case_version__vr, LAMBDA(cae, cae.rank__v = 1 && ISBLANK(cae.resolved_normalized__v))),
    onset_normalized__v, // Group field
        // Text input
        ${VS_PrefixDate(case_adverse_event_v,onset_normalized__v)} " the patient experienced " 
        ${VS_Repeat(
            case_adverse_event__v,
            true,
            ${case_adverse_event__v.event_reported__v} ${VS_ExistCheck(case_adverse_event__v, event_meddra_pt__c, "("${case_adverse_event__v.event_meddra_pt__c}")")} "with outcome " ${case_adverse_event__v,outcome__vr.name__v})
        }
)}

The rendered output for this example may look like the following:

the patient experienced "upset stomach" (Nausea) with outcome resolved, "sore muscles" (Pain) with outcome ongoing, and "fever" with outcome resolved