Creating Rules (V2)
19R2 & Later
You can create data validation rules by using the rules engine to validate data in Vault EDC. Vault can then perform certain tasks based on the evaluation of the rule:
- Create a system-generated query once a user leaves the field.
- Display Event Groups, Events, and Forms in a Study based on entered data.
- Conditionally enable and disable certain Items and Item Groups based on entered data.
- Derive values to automatically populate Items based on other entered data.
You can also use formulas to define unit conversions. When you have defined unit conversions for your Study, Vault EDC can convert and store entered values with the correct unit, regardless of a data entry user’s localized entry format.
Expression Engine Version: The content below refers to the updated formula grammar and new text-based rule editor (Expression Engine V2), which was released in April 2019 with 19R1. If your Study was created prior to the 19R1 release, see Creating Rules (V1).
System-Managed Data Validation Rules
Data validation rules can enforce constraints on single Items. Vault EDC uses the properties you define in the Properties panel for Item Definitions to create system-managed data validation rules. Vault EDC automatically creates data validation rules for the following properties:
- Required field (Required checkbox)
- Range validation (Minimum Value and Maximum Value)
- Future date validation (Future Date)
System-managed rules are viewable in Studio’s Rules tab, but you can only edit them from the related Item Definition’s Properties panel. System-managed rules will not have the rule name highlighted in blue and clickable.
Data validation rules display as clickable links in the Rules tab. Clicking the link reopens the Add Study Rules dialog, where you can edit rules. To open the Properties panel for a rule, click anywhere in the rule’s row.
If you have permission to access EDC Tools, you can view query-action rules in the Query Rules tab.
You can perform additional configuration on your rules from the Properties panel. Required properties have a yellow background. For an explanation of available properties, see Rule Design Properties.
How to Create a Rule
You can create new Rule Definitions in Studio from Studio > Rules. Depending on when your Study was created, you may have Version 1 or Version 2 of the rules editor and formula expression grammar. If your Study uses Version 1 of the Rule Editor and formula expression grammar, see Defining Rules in Studio (V1) for information about creating rules.
To create a new rule:
- Enter a Name for your rule.
- Optional: If you don’t want your rule to be immediately active in your Study, deselect the Active checkbox. You can later activate the rule by selecting the Active checkbox again.
- Optional: Enter a Description.
- Optional: For Evaluate Rule When, select Event Group Creation. With this selection, Vault evaluates your rule when creating a new Event Group (for repeating Event Groups), instead of upon Form submission. When you select Default for this field, Vault evaluates all rules upon Form submission.
- Select a Form to apply the rule to.
- Optional: Select the Within Current Event Group checkbox. For Add Event and Add Form rules, this setting prompts Vault to only add the Event or Form within the current Event Group, instead of any instance of that Event Group.
- Optional: Select a Blank Handling option. This controls how Vault handles blank values when evaluating your rule expression. See details below.
- Add your formula or expression in the Expression field. First, set any variables using #define statements, and then enter your formula on a new line. To get help with building formulas, click Formula Language Reference. This opens the Vault CDMS Formula Reference. in CDMS Help. You can use the Function Selector to add functions to your expression. See details below. Vault can also attempt to autocomplete identifiers, variables, operators, and functions. Press Ctrl + Space to see a drop-down list of autocomplete options.
- Click Check Syntax to validate your expression. If there are any errors, Vault shows an Error icon on the line number. You can hover over the icon to see details about the error. Vault also lists all errors below the Expression field.
- Select a Rule Action. See details about the different actions available below.
- Depending on the Rule Action you chose, Vault prompts you to make various selections about the actions to execute. See details below.
- When you are finished creating your rule, click Save.
- Optional: Click Save and New to save your rule and then return to the Rule Editor to create a new rule.
Using the Function Selector
You can use the Function Selector to search for and add functions.
To add a function from the selector:
- Locate your function in the list.
- Click Insert to add the function into the Expression field.
To search for a specific function:
- Enter the function name in the Search field.
- Press Enter.
- Click the Function in the list to view details about the function. Double-click on the Function to immediately add it to your expression.
- Optional: Click Help on this function to view additional documentation about this function.
- Click Insert to add the function into the Expression field.
Using the Item Selector
When creating a rule, you can search for Item identifiers in your Study and insert them into your rule expression. By default, Vault lists all Items on the Form you selected in the Rule Details panel.
To search for an Item:
- Click into the Search field.
- Type one or more terms in the search box. You can search for the Name or the Label from your item. To search for an exact string, use double quotes around the terms (“informed consent”).
- Click Clear () to clear your search.
For each Item in your search results, Vault shows the Name and the Label. Items are grouped by Item Group.
Rules with Wildcard Identifiers (@Form)
As of 20R1 (April 2020), for any new rules that use a wildcard identifier (
@Form), Vault automatically evaluates the rule each time the identified form is submitted. When a rule expression references data from multiple Forms, even when using both @ and fully-qualified identifiers, Vault will evaluate the rule upon submission of the Form (selected in the Rule Details panel), and then it will re-evaluate the rule each time data changes on any Form referenced in the rule expression. This is called “reciprocal rules”. For example, if you use
@Form to point to a Vitals form that you use in multiple Events, Vault evaluates the rule on each occurrence of the Vitals form.
If the Form you selected in the Rule Details panel is a repeating one, Vault will only evaluate the rule on the Form instance being submitted.
If you need to create a new Rule using the non-reciprocal behavior (pre-20R1), work with your Veeva Services representative to do so.
Reference Sequence Number in Rules
You can reference the Sequence Number of a repeating Event Group, Form, or Item Group to only evaluate the rule against or perform the rule action upon a specific instance of the repeating object. For example, you could configure a Set Item Value rule to only set the item’s value in the first sequence of the repeating Item Group containing it.
To reference the sequence number in the rule expression, append the number in square brackets after the repeating object’s identifier but before the period of any subsequent identifiers.
To reference the sequence number in the rule action configuration, select One instance for the repeating object and enter the sequence number.
For repeating Event Groups, Forms, or Item Groups, as well as linked Forms, you can use an aggregate identifier to point to a value across all instances. For example, you could use an aggregate identifier to look up the Lesion Size item on all instances of the repeating Measurements form.
Unsupported Data Types: Vault does not support aggregate identifiers on Items with the boolean (checkbox) or time data types, or any property that returns a boolean. Use regular identifiers to refer to these Items.
Aggregate identifiers use square brackets around an asterisk (
[*]) after the Name of the repeating object. See the examples below.
Aggregate identifiers are “bottom up”. If you have an aggregate identifier, all repeating identifiers below it in the hierarchy must also be aggregate. For example, if a repeating Form contains a repeating Item Group, you must use an aggregate identifier for the Item Group if you use one on the Form. Note that this does not apply if the lower components aren’t repeating (a repeating Form with a non-repeating Item Group).
$Visit_1.Visit_1.Measurements[*].Lesions.Lesion_Size $Treatment_Visits[*].Visit.event_date__v @Form.Physical_Exam[*].Abnormalities
- Any combination of the above with a Property (except for
did_not_occur__v, as these return a boolean)
- Any of the above with a sequence number instead of ‘*’, except for the linked form.
There is a special set of functions for use with aggregate identifiers. You can only use these functions on the aggregate identifier. Note that some of these functions, for example,
Sum, can be used on regular identifiers as well. It is only aggregate identifiers that are limited to this list. These functions include:
You can review the details of these functions and examples for their use here.
Referencing Data from Linked Forms
During data collection, it’s often necessary to relate the data from two or more repeating forms together to group similar or related data or indicate cause and effect. For example, an Adverse Event can be linked to one or more Concomitant Medications that are related to that Adverse Event.
You can reference data in a rule expression from both the rule’s form and any forms that are linked to it. For example, if you’re writing a rule on a Concomitant Medication form, you can reference data from the linked Adverse Event form.
An expression can’t contain identifiers that are outside the context of the linked form. The form chosen in the Form field on the rule is the “main” form. You can access data from any Forms that are linked to this main form. All other identifiers in the expression must be in either this main form or on one of the linked forms. For example, if a ConMeds form is linked to an AE form, but not linked to a Medical History form, you could write a rule and check that the AE start date is before the CM start date, but you couldn’t check that the Medical History start date is before the CM start date. This is because in this example, the Medical History form isn’t linked to the Concomitant Medication form.
To reference an Item or form-level attribute of a linked Form, include the linked form’s identifier after the form identifier or
@Form, separated by a forward slash (/). For example, the following identifiers point to the Is the adverse event ongoing item on the Adverse Event form, which is linked to the Concomitant Medication form:
For example, on a Concomitant Medication form, you could write a rule to check whether the Adverse Event is still ongoing.
#define ongoing @Form/AdverseEvent.AdverseEventDetails.Ongoing ongoing = true
Vault allows you to copy rules from both the current Study and from another Study in your vault.
From the Current Study
Open an existing Rule Definition and click Save a copy to save a copy of your rule.
From Another Study
You can also copy Rule Definitions from another Study. Note that if matching identifiers don’t exist in your (the target) Study, Vault copies the rules as “invalid”, and you’ll need to update the identifiers and reactivate the rules before they are available for use.
See Reusing Design Definitions for details on copying rules from another study.
To resolve an invalid rule:
- Open the invalid rule in the Rule Editor from Studio > Rules.
- Replace any invalid identifiers with valid ones.
- Select the Active checkbox.
- Click Save.
Repeat that process for each invalid rule.
Available Rule Action Types
The following Action Types are available for rules in Vault EDC:
|When the expression evaluates as True, Vault will create a query on the selected Item or Event Date with the entered Query Message.|
|Add Event Group||Event Group||When the expression evaluates as True, Vault will add the selected Event Group to the casebook schedule.|
|Add Event 1||Event||When the expression evaluates as True, Vault will add the selected Event to the casebook schedule.|
|Add Form 1||Form||When the expression evaluates as True, Vault will add the selected Form to the casebook schedule.|
|Disable 4||Identifier||When the expression evaluates as True, Vault will disable the selected Item.|
|Set Item Value 1||Item||Vault populates the selected Item with the calculated result of the expression.|
|Add Assessment 2||Assessment||When the expression evaluates as True, Vault will create an Assessment.|
|Set Subject Status||Status||When the expression evaluates as True, Vault updates the subject's status to the selected status, and records the status change date. If the subject's current status and the status for the rule are the same, no change occurs.|
|Send Email||N/A||When the expression evaluates as True, Vault sends an email, using the configured Subject and Message, to a pre-configured recipient group.|
|Progressive Display 2, 3, 4||N/A||In the current release, this action type is only available for system-generated rules. To configure Progressive Display, edit an item's properties from Studio > Schedule. Learn more.|
|Override Review||Review Plan Task, Override default plan with||When the expression evaluates as True, Vault overrides the default Review Plan for the Form (the _Form Definition_ selected in the Rule Details panel) with the chosen Review Plan.|
|Create Protocol Deviations||Summary, Category, Subcategory, Severity, Date of Deviation, Link to, Description||When the expression evaluates as true, Vault creates a programmatic Protocol Deviation with the chosen Category, Subcategory, and Severity, and sends that Protocol Deviation to the appropriate monitoring users.|
|Ready to Randomize 5||N/A||When the expression evaluates as True, the subject will be marked as ready for Randomization and the Randomization option will be enabled in Data Entry.|
1 Contact Veeva Support to enable this action type.
2 This action type is only available in vaults where Role by Study is enabled. Contact Veeva Support to enable Role by Study in your vault.
3 This action type is only available in studies using the automated deployment model.
4 The availability of this action type depends on the Rules Version field on the Study Configuration record. If the Rules Version is "2", the Disable action is not available.
5 This action type is only available in studies with Randomization configured.
Rule Processing Order
After a site user completes a Form, Vault EDC processes rules in the following Action Type order:
- Set Item Value
- Add Event Group
- Add Event
- Add Form
Within each rule type, Vault EDC processes rules in the following order:
- Single Form Rules (controlling and dependent objects are in the same Form)
- Cross Form - Same Event Rules (controlling and dependent objects are in different Forms)
- Cross Form - Cross Event Rules (controlling and dependent objects are in different Events)
Vault processes rules in this order so that any Query-type rules that are affected by the derived Item value or any added Event Groups, Events, and Forms can be processed with all expected data present.
Disable action rules don’t follow the rule processing order because unlike other rule actions, disabling an Item or Item Group is not potentially impacted by the actions of other rules. Vault evaluates Disable action rules when a user saves a Form containing the controlling Item.
Data Validation Queries with Rules
You can create data validation rules across multiple items, as well as create rules for single items not based on the properties for system-managed rules. When an entered Item value does not match your defined criteria, Vault creates a query. To create a data validation rule, select Query for the Rule Action.
Data validation rules display as clickable links in the Rules tab. Clicking the link reopens the Add Study Rules dialog, where you can edit your rule. To open the Properties panel for a rule you created, click anywhere in the rule’s row.
Query Rule Execution
By default, rules execute upon form submission (when the site user clicks the Complete button). For query rules, you can choose to delay execution of the rule. This means that once the user submits the form, instead of creating and displaying the query immediately, Vault adds the rule to a processing queue and displays the query when finished. This is helpful for improving rule performance, especially for complex rules that check many data points.
To set a rule as delayed, select the Delayed checkbox under Query Rule Execution in the Rule Details panel.
Study administrators can monitor the execution of delayed rules and view any errors from Tools > EDC Tools > Rules > Error Console. Vault sends a notification to any study users with the Run Rules permission whenever an error occurs.
Example Data Validation Rule
@Event.Vitals.Blood_pressure.Diastolic_blood_pressure > @Event.Vitals.Blood_pressure.Systolic_blood_pressure
In this example, Vault EDC generates a query if the leftmost item value, Diastolic Blood Pressure, is greater than the rightmost item value, Systolic Blood Pressure. Both of these items are on the Vitals form.
Create a Query Only in Certain Casebook Versions
You can configure a data validation rule to evaluate only subject Casebooks on a certain version. For example, you could have a rule run on all Casebooks with a Version less than 8 and only on Events where the Event Date is earlier than the date of the casebook version amendment from 7 to 8. This type of rule is useful when you’ve updated your Casebook Definition in such a way that a certain rule is no longer valid based on the new design.
To reference a Version number, use the following syntax:
((@Event.event_date__v > date(2018, 12, 15) && (@Casebook.version__v > 7)) && ((@Event.event_date__v - $Screening.Screening.Demographics.Creation_criteria.BirthDate.value__v) <= 18)
In the example formula above, when the Event Date is after 2018-12-15 and the casebook version is greater than 7, the rule creates a query if the subject is not 18 at the time of the Screening Event.
Dynamic Study Design with Rules
You can use data validation rules in your Study to dynamically add Event Groups based on user-entered data. For example, you can configure rules to control which Event Groups appear in a Casebook based on a subject’s cohort or randomization number. You can also use data validation rules to dynamically enable and disable data collection items based on another Item value.
With this data validation rule, when a user enters data that Vault EDC evaluates as True, Vault EDC automatically adds the specified Event Group or Event Groups to that Casebook.
You must use data validation rules to surface any Event Groups after the first Event Group in a Study. If you simply want to display all of your Event Groups for a Study at once, you can configure rules to do so. See the example below.
To display all Event Groups, use an Item on the first Form in your Study. You can check that the Item is not blank. Once a site user completes that first Form, Vault then adds all the remaining Event Groups to the casebook. You’ll need to configure a rule for each Event Group you want to display. For example, if a study has two cohorts, and the cohorts are split into Event Group A and Event Group B, you must create one rule to add Event Group A and another rule to add Event Group B.
To add multiple Event Groups with a single rule, select an Event Group in the Actions panel, then click Add () and select another Event Group. Continue until you’ve added all the Event Groups you want to add using this rule.
You can add up to ten (10) Event Groups with a single rule.
Events & Forms
Before using dynamic Events and Forms, you must contact Veeva Support to enable this feature.
You can conditionally add Events and Forms to a Casebook based on user-entered data by configuring a rule using the Add Event or Add Form action type on the controlling Item. When that rule evaluates as True, Vault EDC automatically adds the dependent Event or Form to the Casebook. If the rule evaluates as False, Vault does not add the Event or Form.
To use an Event Definition or Form Definition with these rules, you must select the Dynamic checkbox on that Event or Form in the Properties panel.
For example, you can create a rule that adds the Follow Up Visit event when a user selects the Follow Up Visit Required checkbox on a form.
To conditionally add multiple Events or Forms, select multiple Events and Forms to apply the Rule Action to. Note that you can only enter multiple Events for an Add Event rule and multiple Forms for an Add Form rule.
Unlike dynamic Event Groups, you do not have to create Add Event and Add Form rules to show any Event or Form in your Study. These rules are intended for use on an ad hoc basis to conditionally add Events and Forms, similar to the functionality available for dynamic fields.
Add Form Rules for Repeating & Common Forms
When you add a repeating or common Form with a rule, Vault adds tje Form to the study schedule without creating the first instance of the form. To have Vault add the Form to the schedule and create the first instance of the Form, contact Veeva Services to set the Dynamic Repeating Form Instance field to Yes on your study’s Study Configuration record.
Deleting Add Event & Add Form Rules
Unlike other rule types, Add Event and Add Form rules create an additional object record upon rule execution: Rule Result. If you need to delete a rule of these types, and the rule has already been executed, you will first need to delete all existing Rule Result records related to the rule.
Note that you can delete these rules without the steps below if you have not yet published your Casebook Definition.
To delete Rule Result records:
- Navigate to the Rule Result object from Admin > Business Admin.
- Locate all Rule Result records with the rule you want to delete in the Rule Definition field. You can choose to add a Rule Definition column by choosing Edit Columns from the Actions menu.
- On each Rule Result record, choose Delete from the Actions menu for each Rule Result record.
- Click OK.
Item Groups & Items (Fields)
To conditionally disable a data entry Item or Item Group, configure a rule using the Disable action type (formerly known as “Skip Item”) on a single, controlling Item. When the disable rule evaluates as True, Vault EDC automatically disables the dependent Item or Item Group. If the rule evaluates as False, Vault EDC leaves that dependent Item or Item Group enabled.
In the current release, you can only use a single, boolean- or codelist-type Item as your controlling Item in the expression.
However, you can choose to set multiple possible values for the controlling Item as conditions for disabling a dependent Item or Item Group by using
OR statements in your expression.
For example, you can build a rule that conditionally disables the Pregnancy Test Result item based on the Gender item.
$Demographics.Creation_criteria.Gender.value__v = “Male”
With this rule, set the Disable action to the Pregnancy Test Result item. Vault evaluates the user-entered data for Gender and disables the Pregnancy Test Result item when the Gender item is set to Male.
To conditionally disable multiple Items or Item Groups, select multiple Items and Item Groups to apply the Rule Action to.
Note that Vault does not create required Item queries on disabled Items.
Derive Values with Rules
You can use rules in your Study to automatically fill an Item field with a derived value. Before you can use this feature, an Admin must contact Veeva Support to enable it.
In the current release, Set Item Value-type rules are single-Form. Any Items you reference in the expression must be on the same Form as the derived Item.
You can only create Set Item Value rules for Items with the Derived item type.
Example Set Item Value Rule
On a Form, you may want to include an Item field for BMI. Instead of having your investigators calculate each subject’s BMI independently, you can configure Vault EDC to derive this Item value automatically. Create an Item Definition for BMI and set the Item Type property to Derived. The BMI item must be on the same Form as the Height and Weight items.
Create a rule with the following expression, and then choose the Set Item Value action and select your BMI item.
@Form.Vitals.Weight.value__v / (@FormVitals.Height.value__v * @Form.Vitals.Height.value__v)
Once the user completes the Form, Vault EDC will automatically populate the BMI item field with the result of the expression.
Set Subject Statuses with Rules
You can use rules in your Study to automatically set a subject’s Status based on user-entered data.
Vault maintains a history of each subject’s status over time. If a user later edits the controlling data, causing the rule to evaluate as false, Vault returns the Subject to the previous (most recent) status.
Available Subject Statuses
The following options are available for subject Status:
- Pre Screen
- In screening
- Screen Failure
- End of Treatment
Vault only allows you to move a Subject into a more advanced Status. For example, you can move a subject from Randomized to Enrolled, but you can’t move a subject from Complete to Enrolled.
Vault records either the Event Date or the vale for a date or datetime Item as the date for the status change. Vault records this date using different fields on the Subject object (
subject__v), depending on the target Status. Note that the Pre Screen status doesn’t have a date field on Subject because it’s the initial subject status.
- In screening → Screened Date (
- Screen Failure → Screen Failed Date (
- Enrolled → Enrolled Date (
- Randomized → Randomized Date (
- End of Treatment → End of Treatment (
- Withdrawn → Withdrawn Date (
- Complete → End of Study Date (
If you choose an Item for the status change date, that Item must be of the Date or DateTime data types and must not belong to a repeating Item Group. For unknown dates and times, Vault replaces the unknown part of the date or time with the minimum (earliest) possible value.
Set Subject Status Rules Created Pre-20R1
If you created any Set Subject Status rules prior to the 20R1 release (April 2020), you can continue to use them without choosing a date. However, if you edit the rule, you won’t be able to save your rule until you’ve chosen a date for the status change.
Set Subject Status & Subject IDs
If your Study uses the by_site subject ID generation method, Vault will increment the subject’s ID each time that a rule returns that Subject to the In Screening, regardless of existing Subject ID values.
Example Set Subject Status Rule
You may want to automatically set a subject’s Status as In screening once there is an Event Date for your screening event. You can do so using a Set Subject Status rule.
Create a rule with the following expression, and then choose the Set Subject Status action type and the In screening status.
Once the Event Date for the Screening event is not blank (after a data entry user enters a date), Vault will update the Status for that Subject to In screening.
Send Email Notifications with Rules
You can use rules in your Study to automatically send an email notification to a group of users when certain conditions occur.
Learn more about sending email notifications.
Override a Form’s Assigned Review Plan
You can use the Override Review Plan rule action to override the default Review Plan assigned to a Form (the Form Definition selected in the Rule Details panel) with another Review Plan. For example, an Adverse Event form may have a lower-risk SDV plan assigned, with fewer items required for review. You can use a rule to override that assignment with a 100% SDV required plan when the adverse event is marked as serious, with, for example, an Is this adverse event serious? item.
Using the expression and rule action configuration below, you could perform the example above.
#define aeser @Form.adverse_event_seriousness.aeser aeser = "Y"
Once you select a Review Plan, you can click View Plan to review the form’s review requirements.
Formulas for Unit Conversion
You can also use formulas to define unit conversions. See Defining Default Units & Conversions in Studio.
Available Operators & Functions
Several operators and functions are available for use in data rule validation. See the Vault CDMS Formula Reference for a complete list.
Blank Value Handling
This dictates how Vault handles blank field values within the formula:
- As zero: Vault substitutes a zero for the blank value, allowing you to complete the formula calculation.
- As null: Vault treats the blank value as null, causing the entire expression to return a null/blank value.
This example shows how different blank handling options affect the outcome of this formula:
@Form.adverse_event_details.event_length_in_days.value__v - @Form.adverse_event_treatment.day_of_treatment.value__v
|Adverse Event Length in Days||Number of Days After Event Beginning that Treatment Occurred||“As zero” result||“As null” result|