Define rule variables

As you create custom rules, define variables referring to collected data to use within your rule expression.

Note:

Want to reference an uploaded document in a custom rule? There are certain limitations that you need to consider. See Can I reference an uploaded file in a custom rule?.

Custom rules are created from the Rule editor, see Access the rules interface.

As you create a rule you must enter a rule name and description before defining your rule variables, expression and action.

  1. In the Rule editor, at the top, click the plus sign icon (Add variable) next to the Variables section title.
    A row with editable fields appears.
  2. In the first field, enter a name for the variable.
  3. Select a visit, a form, and a question from each drop-down.
    For example:
    Var BP_Sys = Screening visit, Vital Signs form, Blood Pressure Systolic question.

    Table 2-1 Variable set up for different use cases

    Use case Set up Behavior
    Retrieve data from the current visit

    Select -All Visits- in the visits field.

    In this scenario the variable value will be retrieved from the form in the current visit where rule is being run. This option only allows the rule to refer to forms in the same visit as the target form.
    Retrieve data from a specific visit

    Select the specific visit in the visits field. For example the Screening visit.

    If you select a specific visit,the variable data will be retrieved from the form in the specified visit, in this case the Screening visit, for every visit where the rule is executed.
    Retrieve data from a form that is not in the current visit

    Select -Any Visit-in the visits field.

    In this scenario the variable value will be retrieved from a form that is not present in the same visit where the rule is being created. This type of variable can only be used in conjunction with getValues( ) helper function.

    Retrieve visit date data as a variable

    Select Visit Date as both form and question.

    A visit's date is considered a separate form and is included in all visits. Because of this, rules that are configured with the visit date field as their target will run against all subject visits unless the rule logic dictates differently.

    Caution: Visit Date should only be used as a variable in a rule or as a rule's target when required.

    This is because the Visit Date is a system item in its own form (not created by a study designer), and when used as a variable or a target, the system can take longer than usual to run rules.
    • If you need to create a custom rule to compare a Visit Date to another form question, the form question should be the target rather than the Visit Date.
    • Visit Date should only be used as a variable to trigger a calculation rule when no other form questions can be used as the trigger.
    Retrieve visit-related context (dose, dispensation date, visit window) Select the visit in the All Visits field, leave the Form field blank, then choose Visit Information as the variable type. When you pass a Visit Information variable to helper functions like getDispensationInfo() and getVisitWindw() they use that variable's visit context to access visit-specific data.
For each variable you want to create, repeat the steps above as needed.
To specify a relation between two simple repeating forms make sure you set the Relation Mapping Definition field. For more information see About relation mapping definition for repeating forms.

Note:

This field is only available when rule target is on a repeating form.
Now that you have defined your rule variables, see how to:

Parent topic: Create rules using the rule editor