Understanding Rules

Rules Overview

Rules enable Study Builders to create custom conditional actions in studies. A rule can be created using the following rule templates:

To create a rule template, the study builder defines the trigger, any preconditions that must be met, and what action the rule should complete when the rule runs.

Because rules can be based on survey answers provided by participants, they can also 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 prescribed set components with configuration settings that enable users to create conditional actions. They include the following components:

  • Trigger: This element initiates the evaluation of a rule.
  • Precondition: This element defines what data is needed to run the expression. For an object to pass through the precondition, every step in the path has to evaluate as TRUE.
  • Reference: This element is a defined path to a data object that already exists in ePRO 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.
  • 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 ePRO 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.

  1. Survey
  2. Survey Name
  3. Schedule Name
  4. Start Event Name
  5. Instance Number

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

  1. Block, Score, Status, or Datetime
  2. Block Name or Score Name
  3. Answer, numericScore, or derivedScore

Image illustrating the position numbers mentioned above. Squares represent the objects across a horizontal axis with period symbols between them to mimic the formatting that will be used when building a reference. In position six, the following squares are stacked vertically to show that you can select any of them: block, store, status, and datetime. In position 7, the block name and score name squares are stacked vertically and placed next to the block and score squares to indicate the relationship between them. The answer, numericScore, and derivedScore squares are in the 8th position and listed near block name and score name to ndicate the relationship between them.

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 Object List Pulled from Survey? Options Example Notes Required?
Survey 1 The object type that all of the other values are related to. No survey survey None Required
Survey Name 2 The name of the survey you want to include in the reference. Yes Survey name hads None Required
Schedule Name 3 The name of the schedule you want to include in the reference. Yes
  • 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. Yes
  • 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. No - You add a 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 6 This object enables you to select a specific block name in position 6. No - You select this exact value. block block None Optional
Block Name 7 This object enables you to reference a specific question based on the name you use for it in the block. Yes Block Name q6 None Required if you selected block for Position 6.
Answer 8 This object checks an expression for the answer. No - You select this exact value. answer answer None Either answer or score is required if you selected block for Position 6.
Score (Block) 6 This object enables you to reference a specific score name in Position 6. No - You select this exact value. score score None Optional
Score Name 7 This object enables you to reference a specific score based on the name you use for it in the block. Yes Score name scorad None Required if score was added for Position 6.
Score (Score) 8 This enables the reference of score name, numericScore, or derivedScore in the expressions. No - You select this exact value. score score None Required if score was added for Position 6.
Status 6 This status returns the status of the referenced Survey. No - You select this exact value. status status None Optional
Datetime 6 This object references the datetime associated with the status change for MISSED and COMPLIANT surveys. No - You select this exact value. 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. It shortens the length of the reference significantly, and you have a copy button you can select to copy the shortened variable name.

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

  1. From a rule template creation page, in the Rule Tools section, select Create New Variable.
  2. Enter a short name for the variable in the Name field. For example: Q1ANS
  3. 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.

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 ePRO 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

  1. Identify the references or variables that identify the location of the data you want to verify.
  2. Identify which answers, scores, statuses, or datetimes you want to assess.
  3. 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.
Block or Score Type Associated Data Object Value Type Value to Add Example Notes
Single Choice Answer Block Answer Text Answer name ans_1 None
Multiple Choice Answer Block Answer Array Each answer name ans_1, ans2, ans4 Answers return as comma separated values in an array.
Numeric Rating Scale Answer Block Answer Number Number from the scale 5 None
Visual Analog Scale Answer Block Answer Number Number from the scale 92 None
Number Entry Answer Block Answer Number Number entered by user 152.4 None
Number Entry (2 Fields) Answer Block Answer Array Each number entered by the user 152,5 Separate the answers with commas
Date Entry Answer Block Answer Date Date selected by the user 2024-01-15 None
Datetime Entry Answer Block Answer Datetime Datetime selected by the user 2024-01-15T13:30+05:00 None
Time Entry Answer Block Answer Time Time selected by the user 13:30 None
Text Entry Answer Block Answer Text Text entered by the user I loved participating in this study! None
Optional Answer Block Answer Text Answer name opt_ans_1 None
Score (Block) Block Score Number Block score 5 None
Score (Score) Block Score Number Numerical result of the formula for the score 84 None
Status Status Text status COMPLIANT Two options are available:
  • COMPLIANT
  • MISSED
Datetime Datetime Text datetime datetime None

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:

  1. Complete UAT testing for the study collection through the Approval status. See Performing User Acceptance Testing (UAT) on a Collection for more information.
  2. Create a study country, site, and site user to complete testing from the site perspective.
  3. Log in to Veeva ePRO as a site user and accept the new collection.
  4. Once your site is set up, create a new test participant and note the birthday you enter for the test participant.
  5. 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.
  6. Select Start in Person.
  7. Enter the test participant’s birthdate.
  8. 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.
  9. 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.