Creating Rules (V2)

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.

Data validation rules display as clickable links in the User Defined 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 Rules tab.

See Tips & Best Practices for Rules for information on timezones as well as tips for using rules.

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)

By default, Vault doesn’t list system-managed rules in the User Defined Rules tab. If your organization wants to display these rules in Studio, you can choose to do so.

Rule Properties

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:

1. From Studio > Rules, click + New Rule.

2. Enter a Name for your rule.
3. 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.
4. Optional: Enter a Description.
5. 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.
6. Select a Form to apply the rule to. This is only required when the rule expression or action contains @Form identifiers or the rule uses the Override Review Plan, Set Item Value, or Send Email rule action types.
7. 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.
8. Optional (Number Fields): Select a Blank Handling option. This controls how Vault handles blank values when evaluating your rule expression. See details below.
9. 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. If you are defining a variable to refer to an Item with a Name that starts with an underscore (_), you must rename the variable to remove the underscore in the #define statement. Otherwise, a syntax error will occur.
10. Click Validate 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.
11. Select a Rule Action. See details about the different actions available below.
12. Depending on the Rule Action you chose, Vault prompts you to make various selections about the actions to execute. See details below.
13. When you are finished creating your rule, click Save and Close.

Using the Function Selector

You can use the Function Selector to search for and add functions.

To add a function from the selector:

1. Click Functions to open the Function Selector.

2. Optional: Select a function type from the drop-down to filter the list by type of function.

3. Locate your function in the list.
4. Click the Function in the list to view details about the function. Double-click on the Function to immediately add it to your expression.

5. Optional: Click Help on this function to view additional documentation about this function.

6. Click Insert to add the function into the Expression field.

To search for a specific function:

1. Enter the function name in the Search field.
2. Press Enter.
3. Click the Function in the list to view details about the function. Double-click on the Function to immediately add it to your expression.
4. Optional: Click Help on this function to view additional documentation about this function.
5. Click Insert to add the function into the Expression field.

Unsupported Functions

In the current release, the Function Selector shows several functions from the Vault Platform that aren’t supported for use in rules. The following functions aren’t supported:

• AddMonths
• Ascii
• Begins
• BlankValue
• Contains
• CurrencyRate
• DayOfYear
• FromUnixTime
• Id
• InitCap
• IsoWeek
• IsoYear
• Pi
• PicklistCount
• Rand
• TimeNow
• TimeValue
• Trunc
• UnixTimestamp
• Urlencode

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:

1. If it isn’t already open, click Items.

2. Optional: Select All Forms to search in all of your study’s forms. Leave this as This Form to only search in the Form you selected in the Rule Details panel.

3. Click into the Search field.
4. 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”).

5. Vault searches for Items as you type. Select an Item from the Results dropdown to view it.

6. Optional: Hover over an Item and click Add () to add the item’s identifier to your rule expression.

7. 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 Floating Identifiers (@Form, @Event, @EventGroup)

As of 20R1 (April 2020), for any new rules that use a floating identifier such as @Form (also known as “wildcard identifier”), Vault automatically evaluates the rule each time the identified form is submitted.

Reciprocal Rules

When a rule expression references data from multiple Forms, even when both floating (@) and fully qualified identifiers are used, Vault will evaluate the rule upon the submission of the Form that is selected in the Rule Details panel and will also re-evaluate the rule each time data changes on any Form that is referenced in the rule expression. This process is called Reciprocal Rules. For example, if you use @Form to point to a Vitals form that you use in multiple Events, and also use a fully qualified identifier to point to a PE form, Vault will run the rule and evaluate the data in the Study object that is pointed to each time a Vitals form or the specific PE form is submitted.

If the Form that you selected in the Rule Details panel is repeating and fully qualified, Vault will evaluate the rule on each Form instance.

Reciprocal form behavior also applies to the Rule Action. For Query rules, for example, in order to ensure that the query fires on the same instance(s) being evaluated in the rule expression, it is important for the Query Rule action identifier to match the expression identifier. When the identifier in the rule expression uses @Form, @Event, or @Event Group, the query action should match with ‘this form’, ‘this event’, or ‘this event group’, respectively.

Fully Qualified vs Floating Identifiers Format

The format you use when entering the identifier into the Rule Expression field indicates to the system whether you are using a fully qualified identifier or a floating identifier (also known as “wildcard identifiers”).

In most cases, fully qualified identifiers begin with a dollar sign ($), which indicates to the system that you are fully qualifying the reference to the study object.

Fully qualified identifier format example:

$EVENTGROUP.EVENT.FORM.ITEMGROUP.ITEM

Floating identifiers always begin with an at sign (@), which indicates to the system that you want it to look at the study object that is pointed to based on the context.

Floating identifier format example:

@EventGroup.EVENT.FORM.ITEMGROUP.ITEM, @Event.FORM.ITEMGROUP.ITEM, or @Form.ITEMGROUP.ITEM

In the Rule Action, the “@” is denoted as “this Event”, “this Event Group”, or “this Form.”

When a rule contains a repeating Event Group, Event, or Form that is fully qualified, Vault looks at every instance that matches that identifier. For this reason, it’s recommended that you not use fully qualified identifiers on repeating objects unless you want the rule to execute against all of them.

If you need to create a new Rule using the non-reciprocal behavior (pre-20R1), work with your Veeva Services representative to do so.

Rule Identifiers and Permutations

How the identifiers in a rule are defined, or qualified, determines how the rule engine evaluates the study data those identifiers reference. The way identifiers are written impact the behavior of the rule and, in some cases, the performance of EDC. Rule permutations are the different ways a rule will be evaluated against study object data.

The identifier is the path to the study object that the rule is bound to. The system looks at every object instance that matches the location where the object is identified, and runs against that record. A rule containing a fully qualified identifier will only permute against the study object in the location pointed to. If a rule contains a fully qualified identifier for a repeating object, the rule will evaluate against all instances of the repeating object. This may lead to unintended results and excess permutations when the rule runs against and performs a rule action based on repeating event groups, forms, or item groups.. Learn more about best practices for optimizing rule permutations.

When the rule has too many permutations, this can unintentionally impact the submission time for forms and the performance of your vault. In most cases, we recommend you use a floating identifier such as @Form, @Event, or @Event Group (also known as “wildcard identifiers”) when writing a rule expression that references a repeating object. It is recommended to use fully qualified identifiers only when you want your rule to evaluate the following:

• A single instance of an object in the schedule, for example:

  $SCREEN.SCREEN.DM.igDM.AGE
  

• Aggregate logic, for example:

  $LOGS.LOGS.AE[*].igAE.AEOUT
  

• Specific instances of event groups or forms, for example:

  $TRT[1].WEEK.EX.igEX.EXSTDTC
  

The following examples demonstrate how the use of fully qualified identifiers and floating identifiers impact the number of rule permutations.

In each incorrect example, the AEITEM is fully qualified, even though the AE form is a repeating form. This tells the rules engine to multiply the rule for each occurrence of the AE form. If a subject has 100 AE form instances in their casebook, then whenever the other form is saved, the rule permutes 100 times to evaluate the data the identifier points to in each of the AE forms.

Example of incorrect identifier usage, one repeating form:

$LOGS.LOGS.AE.igAE.AEITEM 

In the following example, only 1 AE form instance in the subject’s casebook is referenced, so the rule only permutes once each time the other form referenced in the rule expression is submitted.

Example of correct identifier usage, using a floating identifier for the main repeating form:

@Form.igAE.AEITEM 

If multiple repeating forms are referenced using fully qualified identifiers, then the number of possible permutations grows as a multiple of the number of instances of both forms. For example, if the rule uses fully qualified identifiers to reference both the repeating Screen form and AE form, and if there are 100 AE form instances and 20 MH form instances in the subject’s casebook, the rule has 100 AE x 20 MH form repeats = 2000 permutations.

Example of incorrect identifier usage, two repeating forms:

$SCREEN.SCREEN.MH.igMH.MHITEM     
$LOGS.LOGS.AE.igAE.AEITEM 

The following example uses a floating identifier, so only 1 AE form instance in the subject’s casebook is referenced. This rule has 1 AE instance x 20 MH form repeats for the casebook = 20 permutations.

Example of correct identifier usage, using a floating identifier for the main repeating form:

@Form.igAE.AEITEM1 
$SCREEN.SCREEN.MH.igMH.MHITEM   

The permutations continue to multiply as more fully qualified identifiers are used in the rule expression to indicate multiple items on multiple repeating forms.

In the following example, with 100 AE form instances and 20 MH form instances in the subject’s casebook, the rule has 100^2 AE instances x 20^3 MH form instances for the casebook = 80,000,000 permutations.

Example of incorrect identifier usage, two repeating forms with multiple identifiers:

$LOGS.LOGS.AE.igAE.AEITEM1 
$LOGS.LOGS.AE.igAE.AEITEM2
$SCR.SCR.MH.igMH.MHITEM1
$SCR.SCR.MH.igMH.MHITEM2 
$SCR.SCR.MH.igMH.MHITEM3 

In the following example, only 1 AE form instance in the subject’s casebook is referenced. This rule has 1 AE instance x 20^3 MH form instances for the casebook = 8,000 permutations.

Example of correct identifier usage, using floating identifiers for the main repeating form:

@Form.igAE.AEITEM1 
@Form.igAE.AEITEM2
$SCR.SCR.MH.igMH.MHITEM1
$SCR.SCR.MH.igMH.MHITEM2 
$SCR.SCR.MH.igMH.MHITEM3 

You can further optimize the rule permutations when you write rules referencing repeating objects by using item-to-form and form-to-form linking.

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.

@Form[2] or TreatmentCycle[2].Visit1.event_date__v

When using floating (@) identifiers (also known as “wildcard identifiers”), you can also reference either the previous or next instance of a repeating object, instead of a specific sequence number. To do so, include “+1” (for next) or “-1” (for previous) between the brackets, instead of the sequence number. For example, @EventGroup[-1].Visit1.event_date__v.

Previous/next identifiers require an anchor identifier within the expression. An anchor identifier is an identifier that is the same as the identifier using previous/next, upward in the hierarchy from the previous/next identifier. For example, if @Form.PK[-1].Measurement is used in the expression, then you must also reference @Form.PK.Measurement, or another Item in the PK item group.

The following use cases are supported:

• @Form.ItemGroup[-1/+1].Item
• @Form[-1/+1].ItemGroup.Item
• @Form/LinkedForm.ItemGroup[+1/-1].Item
• @EventGroup[-1/+1].Event.Form.ItemGroup.Item
• @EventGroup[-1/+1].Event.event_date__v

Note that you can only use a previous/next modifier once per identifier.

To reference the sequence number in the rule action configuration, select One instance for the repeating object and enter the sequence number. Note that, if you use a floating identifier (also known as “wildcard identifier”) in your rule expression, you must select the referenced form in the Rule Details panel. In most cases, you should also use the same identifier in your rule action and both the rule expression and rule action should be qualified to the same level.

Reference Value from Previous Event (Non-repeating)

When you re-use an Item across non-repeating objects in your Study, you can reference its value on the previous Event using @PreviousEvent.

For example, your Study may use a single Dosing form across multiple Events. You can use @PreviousEvent to compare the value of an Item on the Dosing form in Visit 2 to the value of that Item in the previous event, Visit 1.

#define dose_amount @Form.dosing.dose_amount
#define previous_amount @PreviousEvent.dosing.dosing.dose_amount

dose amount != previous_amount

Rule Details Form: Dosing

You can use @PreviousEvent more than once in a single rule expression, but @PreviousEvent can only point to one Form. When using @PreviousEvent, you must also use an @Form identifier to anchor the rule to the previous instance.

@PreviousEvent supports the same attributes and identifiers as @Event (change_reason__v, did_not_occur__v, event_date__v, name__v, sequence__v, and all valid attributes and identifiers on .Form.)

Vault uses the sort order you define in the Sort Events By property to determine the previous event. Options for Sort Events By include:

• Event Date: Vault sorts Events by their Event Date when determining the previous Event. For example, a Casebook contains events 1, 2, and 3. This subject had event 2 after event 3. When sorting by Event Date, if a rule checked the previous event during event 3, Vault would use 1 as the previous event, as it was the most recent by date.
• Schedule: Vault sorts Events as they appear in the casebook schedule (as designed in Studio), regardless of Event Date. For example, a Casebook contains events 1, 2, and 3. The events appear in the schedule in that order. Even if a subject had event 2 after event 3, Vault would still use 2 as the previous event when evaluating a rule in 3, as that is the schedule order. Repeating and unscheduled events are sorted by Sequence Number.

@PreviousEvent can only be used for Open Query rules and Set Derived Value rules.

Handling Intentional Blanks

When you choose Schedule for Sort Events By, you can choose how to handle intentional blanks when referencing a previous or next value, for both repeating and non-repeating objects. For @PreviousEvent rules, Vault skips any data point marked as Intentionally Left Blank or Did Not Occur by default.

For @PreviousEvent rules, this is controlled by the Skip Intentionally Left Blank and Did Not Occur Values checkbox in the Rule Details panel.

Aggregate Identifiers

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. Note that floating identifiers (also known as “ identifiers”) can’t use an aggregate identifier.

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

• $eventgroup.event.form.itemgroup[*].item
• @eventgroup.event.form.itemgroup[*].item
• @event.form.itemgroup[*].item
• @form.itemgroup[*].item
• $eventgroup.event.form[*].itemgroup[*].item
• @eventgroup.event.form[*].itemgroup[*].item
• @event.form[*].itemgroup[*].item
• @form.itemgroup[*].item
• $eventgroup[*].event.form[*].itemgroup[*].item
• @event.form[*].itemgroup[*].item
• $eventgroup.event.form1/form2.itemgroup[*].item
• @eventgroup.event.form1/form2.itemgroup[*].item
• @event.form1/form2.itemgroup[*].item
• @form1/form2.itemgroup[*].item
• $eventgroup.event.form1/form2[*].itemgroup[*].item
• @eventgroup.event.form1/form2[*].itemgroup[*].item
• @event.form1/form2[*].itemgroup[*].item
• @form1/form2[*].itemgroup[*].item
• $eventgroup.event.form1[*]/form2[*].itemgroup[*].item
• @eventgroup.event.form1[*]/form2[*].itemgroup[*].item
• @event.form1[*]/form2[*].itemgroup[*].item
• $eventgroup[*].event.form1[*]/form2[*].itemgroup[*].item

• @event.form1[*]/form2[*].itemgroup[*].item

• Any combination of the above with a Property
• 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. Other functions cannot be used with aggregate identifiers. Note that some of these functions, for example, Sum, can be used on regular identifiers as well. Learn more about functions used with aggregate identifiers and see some 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.

A rule expression can’t contain identifiers that are outside the context of the linked form. The Form selected in the Rule Details panel is the “main” form that the @Form floating identifier (also known as “wildcard identifier”) references. 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.

Note that, when you use the @Form floating identifier, you must select the referenced form in the Rule Details panel. In most cases, if you use a floating identifier in your rule expression, you should use the same identifier in your rule action and both the rule expression and rule action should be qualified to the same level. This ensures that the rule action and rule expression are scoped to the same object instances in the Casebook. Otherwise, the rule action may impact unintended forms.

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 (/). You can reference a linked Form in a fully qualified identifier or a floating identifier. In the following examples, the identifiers point to the Is the adverse event ongoing item on the Adverse Event form, which is linked to the Concomitant Medication form:

Fully qualified form link identifier example:

$Logs.CommonForms.ConcomitantMedication/AdverseEvent.AdverseEventDetails.Ongoing

Floating identifier form link identifier example:

@Form/AdverseEvent.AdverseEventDetails.Ongoing

Rule Details Form: Concomitant Medication

For example, on the Concomitant Medication form, you could write a rule to check whether the linked Adverse Event record is still ongoing.

#define ongoing @Form/AdverseEvent.AdverseEventDetails.Ongoing

ongoing = true

Rule Details Form: Concomitant Medication

Item to form link identifier example

#define ongoing @Form.ig_CM.STDAT/AdverseEvent.AdverseEventDetails.Ongoing

ongoing = true

Rule Details Form: Concomitant Medication

Archiving (Deleting) Rules

Deleted rules are Archived. Archived rules behave in the same way as Inactive rules. Vault excludes these rules from validations and documentation, deploys them (in the Archived status), and prevents users from marking them as Active. That prevents these rules from executing.

By default, archived rules aren’t included in the User Defined Rules listing. Select the Show Archived Rules checkbox to include them. Archived rules have a green checkmark () in the Archived column.

How to Archive a Rule

To archive a rule:

1. Navigate to Studio > User Defined Rules for your Study.
2. Locate your rule in the list.
3. Hover over the rule’s Name to show the Actions menu.

4. From the Actions menu, select Archive.

5. In the Archive Rule confirmation dialog, click Archive.

Your rule is now Archived. Select the Show Archived Rules checkbox to show it in the list.

How to Restore a Rule

To restore an archived rule:

1. Navigate to Studio > User Defined Rules for your Study.
2. Select the Show Archived Rules checkbox.
3. Locate your rule in the list.
4. Hover over the rule’s Name to show the Actions menu.
5. From the Actions menu, select Restore Archived Rule.

Vault restores the rule. The rule is now active and will execute normally.

Copying Rules

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:

1. Open the invalid rule in the Rule Editor from Studio > Rules.
2. Replace any invalid identifiers with valid ones.
3. Select the Active checkbox.
4. Click Save.

Repeat that process for each invalid rule.

Available Rule Action Types

The following Action Types are available for rules in Vault EDC:

Rule Processing Order

After a site user completes a Form, Vault EDC processes rules in the following Action Type order:

1. Set Item Value or Set Derived Value
2. Add Event Group
3. Add Event
4. Add Form
5. Query

Within each rule type, Vault EDC processes rules in the following order:

1. Derivation Rules
2. Cross Form - Same Event Rules (controlling and dependent objects are in different Forms)
3. Cross Form - Cross Event Rules (controlling and dependent objects are in different Events)
4. All other rules except Send Email
5. Send Email rules

Vault processes rules in this order so that any Query-type rules that are affected by derived values or any added Event Groups, Events, and Forms can be processed with all expected data present.

Disable Rules

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.

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 by marking it as a post-save 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 a post-save rule, select the Post-save rule checkbox under Rule Execution in the Rule Details panel.

Study administrators can monitor the execution of post-save 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 Open Query Rule

#define DIASBP @FORM.Blood_pressure.Diastolic_blood_pressure
#define SYSBP @FORM.Blood_pressure.Systolic_blood_pressure

DIASBP > SYSBP

Rule Details Form: Vital Signs

In this example, the form containing the DIASBP and SYSBP items to be evaluated is selected in the Rule Details panel. In this case, Vault EDC evaluates whether the Diastolic_blood_pressure item is greater than the Systolic_blood_pressure item. The study designer can configure the rule action to generate a query when the expression evaluates to true. Both DIASBP and SYSBP are numbers, so the study designer must consider blank handling. Since this form uses a floating identifier (also known as “wildcard identifier”), in most cases the same identifier should be used in the rule action and both the rule expression and the rule action should be qualified to the same level.

Create a Query Only in Certain Casebook Versions

You can configure a 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 where the Screening 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: @Casebook.version__v.

#define EVDAT $Screening.Screening.event_date__v
#define CBV @Casebook.version__v
#define BRTHDAT $Screening.Screening.Demographics.DM.BirthDate.value__v

(( EVDAT > date(2018, 12, 15) 

&& 

CBV > 7))

&& 

((EVDAT - BRTHDAT) <= 18)

In the example formula above, when the Screening 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. It would also be possible to write this rule using the @Form floating identifier (also known as “wildcard identifier”), as long as the demographics form only exists in the Screening Event.

Note that, since this rule expression uses a floating identifier, in most cases the rule action should be qualified to the same level.

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.

Event Groups

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.

not(IsBlank($First_event_group.First_event.First_form.First_item_group.First_item.value__v))

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.

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:

1. Navigate to the Rule Result object from Admin > Business Admin.
2. 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.
3. On each Rule Result record, choose Delete from the Actions menu for each Rule Result record.
4. 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.

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 (Studies created before 22R3)

You can use rules in your Study to automatically fill an Item field with a derived value.

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 set the item to your derived BMI item. Since this rule expression uses a floating identifier (@Form) (also known as “wildcard identifier”), you should qualify the action to the same level: select this form > ig_VS > BMI.

#define WEIGHT @Form.ig_VS.mu_WEIGHT
#define HEIGHT @Form.ig_VS.mu_HEIGHT

WEIGHT / (HEIGHT * HEIGHT)

Rule Details Form: Vital Signs

Once the user completes the Form, Vault EDC will automatically populate the BMI item field with the result of the expression.

Cross-form Derivations

With Cross-form Derivations, Vault will derive values across forms in a casebook when you add the Derived Items component to forms in Studio’s drag & drop editor and create Set Derived Value rules.

Derived item values don’t depend on the submission of a form and derived values are automatically updated without form resubmission. Derived items can be configured to display or not display in both Data Entry and extracts.

Set Derived Value rules require that the @Form floating identifier (also known as “wildcard identifier”) be used. Since this rule type uses the @Form floating identifier, you should qualify the rule action to the same level.

As of 23R2, derivation rules where the result does not match the target item’s data type must be fixed or inactivated in order to deploy from DEV.

For more information about Cross-form Derivations, see Cross-form Derivations.

Visit Method

If Visit Method is configured, you can create rules that reference visit method values and can be used to open queries, create protocol deviations, and more.

Note that you must use the picklist label value, not the code value, when referencing visit method in the rule editor.

For more information about Visit Method, see Visit Method.

Set Subject Statuses with Rules (23R2)

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
• Consented
• In screening
• Screen Failure
• Enrolled
• Randomized
• Started Treatment
• End of Treatment
• Withdrawn
• Started Follow Up
• Lost to Follow Up
• Complete

Vault records either the Event Date or the value 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 (screened_date__v)
• Screen Failure → Screen Failed Date (screen_failed_date__v)
• Enrolled → Enrolled Date (enrolled_date__v)
• Randomized → Randomized Date (randomized_date__v)
• End of Treatment → End of Treatment (end_of_treatment_date__v)
• Withdrawn → Withdrawn Date (withdrawn_date__v)
• Complete → End of Study Date (end_of_study_date__v)

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.

When a rule evaluates to true, Vault always adds a status date for a particular Status, regardless if that status is the latest or whether the subject actually moved into that status.

When the rule that sets the most advanced status is rolled back, for example, due to a form being reset, Vault also removes the subject status date for that status. If you have Enable Subject Status Date Rollback set to Yes in Studio > Settings, then any status date stored for a subject will be removed when the associated Subject Status rule evaluates to false.

When you have Enable Subject Status Date Rollback set to No in Studio > Settings, if a rule that is not setting the most advanced status evaluates to false, Vault doesn’t remove the subject status date for that status.

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.

Not(IsBlank(@Screening.Screening.event_date__v)

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.

Example override review plan rule:

#define aeser @Form.ig_AE.AESER

aeser = "Y"

Rule Details Form: Adverse Event

Rule Action: Override Review Plan: SDV or DMR

For the rule action, select Override Review Plan for SDV or DMR. Then, select the Review Plan that will override the default Review Plan when the rule evaluates true.

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

If you have an identifier that is a number data type, you must use the Blank Handling property in the Rule Editor to choose how Vault handles blank values. For numeric fields, this dictates how Vault handles blank field values within the formula. You can choose between these options:

• 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.

Example

This example shows how different blank handling options affect the outcome of this formula:

Formula:

NUM1 + NUM2