Creating Rules in Studio
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.
The content below refers to the updated formula grammar and new text-based rule editor, released in April 2019 with 19R1. For details about the pre-19R1 rules, see the Defining Rules in Studio (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:
- From Studio > Rules, click + 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.
Open an existing Rule Definition and click Save a copy to save a copy of your 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||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.|
|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.|
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.
Rule Processing Order
After a data entry 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.
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 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 of 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.
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.
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.
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
ORstatements 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.
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
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.
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|