Understanding Rules

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.

  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 through 8 to further define a reference:

  1. block, score, status, or datetime
  2. Block Name or Score Name
  3. answer or score

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

  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.
  4. Save the variable.
  5. 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

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