Understanding Rules | Veeva Vault Help

Rules Overview

Rules enable Study Builders to create custom conditional actions in studies. The following actions are available:

Survey-Based Notification Template: This template allows you to configure notifications to be sent when specific conditions are met.
Criteria Check Rule Template: This template allows you to configure an action that site staff can use to analyze participant data and display outputs that inform decision-making during the study.

To create a rule template, the study builder defines the trigger, any preconditions that must be met, and the actions that are executed or available.

Because rules can be based on or display survey data, rules can be configured to protect restricted data from users who do not have access to view it.

We recommend building your rules after you have built surveys, schedules, events, and groups. If you edit values in other tabs while working on a rule, it can break references and prevent you from completing UAT until the references are updated.

Element Types

Rule templates are a set of components that enable users to create conditional actions. They include the following elements:

Building Blocks

Reference: This element is a defined path to a data object that already exists in eCOA and uses a specific format so that it can be used to trigger a rule.
Variable: This element is a named reference to a specific object that is used in expressions. You can save longer reference strings as variables to make it easier to reference them in expressions.
Expression: This element defines how the data in the rule should be evaluated.

Components of Rule Templates

Trigger: This expression initiates the evaluation of a rule.
Precondition: This expression defines what conditions are needed to run the expression. For an object to pass through the precondition, every step in the path has to evaluate as true.
Action: This element defines what should happen if the expression evaluates to true. Actions may be triggered automatically, depending on how they are configured.

Creating a Reference

Reference Overview

References are a defined path to a data object that already exists in eCOA and uses a specific format so that it can be used in a rule. To create a reference, you add a reference type and add all related objects.

Reference Types

There are two types of references you can create: relative and absolute. Relative references begin with the ‘@’ character and refer to the survey that triggered the rule evaluation. Absolute references start with the ‘$’ character and refer to a specific survey defined by the reference path.

Use Category	Type @	Type $
Can I Use It to Refer to Any Survey?	No. you can only use this type to refer to the survey name that is referenced in the trigger definition.	Yes. You can use this reference to refer to any of the survey names you select.
Can I Use It to Reference Multiple Survey Names?	No. You can only use one @ survey per rule. So you can create multiple @ references, but each reference will refer to the the survey that triggered the rule.	Yes. You can reference different survey names each time you add a reference with this type.
Can I Add Any Instance I Want?	No. You must use [-1] (which means the most recent survey) as the instance.	Yes, as long as you enter a positive or negative integer, and you do not enter 0.

Survey Objects and Hierarchy

A standard reference that uses survey as the first object includes a minimum of five values that are separated by periods. The objects below are included in a standard survey reference in the order in which they are displayed.

Survey
Survey Name
Schedule Name
Start Event Name
Instance Number

You can add the following additional objects in positions 6 through 8 to further define a reference:

block, score, status, or datetime
Block Name or Score Name
answer or score

To help ensure that you select valid options in each position, the available options are displayed in a list under the position when you enter any of the following characters: @, $, or period (.) The only item you may need to enter manually is the integer for the instance number. See Survey Reference Parameter Dictionary for more information about the objects you can add.

Survey Reference Parameter Dictionary

Data Object	Position	Description	Type of Value	Options	Example	Notes	Required?
Survey	1	The object type that all of the other values are related to.	Static text	survey	survey	None	Required
Survey Name	2	The name of the survey you want to include in the reference.	Name of a survey in collection	Survey name value	hads	None	Required
Schedule Name	3	The name of the schedule you want to include in the reference.	List of schedules in collection	Schedule name value [*]	six_hours	[*] indicates that the reference should consider all available schedules.	Required
Start Event	4	The name of the start event for the schedule.	List of start events in schedule from position 3	Start event name value [*]	epro_activated	Ensure that you select the start event to make sure this rule evaluates the data appropriately. If multiple schedules are being considered, you may select [*] to make sure all are considered.	Required
Instance	5	The instance of the survey. You can define the specific instance based on the order in which it was submitted or based on the most recent submissions.	Positive or negative integer based on the instance you want to use.	[#] [-#] [*]	[1] or [-5] or [*]	The instance is usually representing in brackets [] If you used a type of @, you must use [-1]. [1] is the first instance of a survey. Non-recurring surveys only have 1 instance. [2], [3], [4], and so on refer to subsequent submissions of recurring surveys [-1] refers to the most recent survey that aligns with the survey name, schedule name, and start event that are earlier in the hierarchy. [-2], [-3], [-4], and so on refer to the second most recent submission, third most recent submission, fourth most recent submission, and so on.	Required
Block (Answer or Score)	6	This object enables you to select a specific block name in position 7.	Static text	block	block	None	Optional
Block Name	7	This object enables you to reference a specific question by block name.	List of values pulled from survey in position 2	Block Name value	q6	None	Required if you selected block for Position 6.
Answer	8	This object references the answer of the block in position 7.	Static text	answer	answer	None	Either answer or score is required if you selected block for Position 6.
Score (of a block)	8	This object references the score of the block in position 7.	Static text	score	5	None	Either answer or score is required if you selected block for Position 6.
Score (Derived in survey)	6	This object enables you to reference a specific score name in Position 7.	Static text	score	score	None	Optional
Score Name	7	This object enables you to reference a specific score by score name.	List of values pulled from survey in position 2	Score name value	scorad	None	Required if score was selected for Position 6.
Score	8	This object references the value calculated from the function of the score referenced in position 7.	Static text	score	score	None	Required if score was selected for Position 6.
Status	6	This status returns the status of the referenced Survey.	Static text	status	status	None	Optional
Datetime	6	This object references the datetime associated with the status change for MISSED and COMPLIANT surveys.	Static text	datetime	datetime	None	Optional

Creating a Variable

Variable Overview

Variables can be helpful if you want to use the same reference in multiple expressions or actions. Using variables can shorten the length of the expressions or actions significantly and make them easier to read with human-friendly variable names.

For example, if you want to evaluate that the statuses of two surveys are COMPLIANT and then include that information in the criteria check without using variables, the reference evaluation looks similar to the example below, and you’d need to copy and paste it in multiple places:

($survey.survey_caregiver.five_hours.[*].[-1].status = "COMPLIANT") && ($survey.survey_caregiver.five_hours.[*].[-2].status = "COMPLIANT")

If you add a variable for each reference, the following example shows what you may see: (STAT1 = "COMPLIANT") && (STAT2 = "COMPLIANT")

Variable names can also be easier to remember as you are creating expressions.

Creating Variables

From a rule template creation page, in the Rule Tools section, select Create New Variable.
Enter a short name for the variable in the Name field. For example: Q1ANS
Enter a reference in the Definition field. For example: @survey.hads.[*].[*].[-1].block.HADS0101.answer

Tip: Enter $ or @ to begin, and then select from the options that are displayed. After you select each option, enter a period and select from the next list of options that are displayed. You can select [*] if you want the path to include all items that fall in that category.
Save the variable.
You can now copy the variable name for use.

Creating an Expression

Expression Overview

Expressions define how the data in a rule should be evaluated. You can use references or variables to identify specific eCOA data for analysis, calculation, and display. Expressions can be simple or complex, and multiple expressions can be used for a rule to ensure that you can create actions that run based on very specific conditions.

Creating Expressions

Identify the references or variables that identify the location of the data you want to verify.
Identify which answers, scores, statuses, or datetimes you want to assess.
Create an expression using formulas supported by the Vault Expression Engine. See Vault Formula Reference Guide for more information on which values you can include in your expression formula.

Associated Data Object	Block or Score Type	Value Type	Value to Add	Example	Notes
Block Answer	Single Choice Answer	Text	Answer name	ans_1	None
Block Answer	Multiple Choice Answer	Array	Each answer name	ans_1, ans2, ans4	Answers return as comma separated values in an array.
Block Answer	Numeric Rating Scale Answer	Number	Number from the scale	5	None
Block Answer	Visual Analog Scale Answer	Number	Number from the scale	92	None
Block Answer	Number Entry Answer	Number	Number entered by user	152.4	None
Block Answer	Number Entry (2 Fields) Answer	Array	Each number entered by the user	152,5	Separate the answers with commas
Block Answer	Date Entry Answer	Date	Date selected by the user	2024-01-15	None
Block Answer	Datetime Entry Answer	Datetime	Datetime selected by the user	2024-01-15T13:30	None
Block Answer	Time Entry Answer	Time	Time selected by the user	13:30	None
Block Answer	Text Entry Answer	Text	Text entered by the user	I loved participating in this study!	None
Block Answer	Optional Answer	Text	Answer name	opt_ans_1	None
Block Score	Score (Block)	Number	Block score	5	None
Block Score	Score (Score)	Number	Numerical result of the formula for the score	84	None
Status	Not applicable	Text	status	COMPLIANT	Two options are available: COMPLIANT MISSED
Datetime	Not applicable	Text	datetime	2025-02-01T12:00+	None

Example

CountIf(“COMPLIANT”,
$survey.ItchNRS.[*].[*].[-1].status,
$survey.ItchNRS.[*].[*].[-2].status,
$survey.ItchNRS.[*].[*].[-3].status)>0

The rule above returns true if at least 1 of the last 3 ItchNRS survey instances was compliant.

Average($survey.ItchNRS.[*].[*].[-1].block.INRS01.answer,
$survey.ItchNRS.[*].[*].[-2].block.INRS01.answer)

The rule above returns the average of the last 2 survey instances’ INRS01 blocks (Numeric Rating Scale).

Text(Average($survey.ItchNRS.[*].[*].[-1].block.INRS01.answer,
$survey.ItchNRS.[*].[*].[-2].block.INRS01.answer),”#.#”)

The rule above returns the average value as text where the number is rounded to 1 decimal place.

If(CountIf(“COMPLIANT”,
$survey.ItchNRS.[*].[*].[-1].status,
$survey.ItchNRS.[*].[*].[-2].status)=2,
Text(Average($survey.ItchNRS.[*].[*].[-1].block.INRS01.answer,
$survey.ItchNRS.[*].[*].[-2].block.INRS01.answer),”#.#”),
“N/A”)

If the last 2 ItchNRS survey instances were both compliant, the rule above returns the average as text where the number is rounded to 1 decimal place.

Else, returns N/A.

Testing a Rule

To test your rule, generate data in UAT that activates the rule and meets any requirements. See the following steps for a more detailed overview:

Complete UAT testing for the study collection through the Approval status. See Performing User Acceptance Testing (UAT) on a Collection for more information.
Create a study country, site, and site user to complete testing from the site perspective.
Log in to Veeva eCOA as a site user and accept the new collection.
Once your site is set up, create a new test participant and note the birthday you enter for the test participant.
View all of the new participant’s events and select the event associated with the rule you created. You should see the survey you used in the rule available under the Participant section.
Select Start in Person.
Enter the test participant’s birthdate.
Complete any surveys and add the data needed to trigger the rule, meet the preconditions, and initiate the action. Alternatively, if you are checking for failure, ensure that you enter data that will enable you to see what you’re looking for.
Sign out of the test participant’s account by ending the session, sign in again as the site user, and check to see whether the actions that are configured for the rule were completed successfully.