Smart Variables

A review of REDCap Field Variables and Field Notation

In REDCap, all fields on data collection instruments will have a corresponding 'field name' or 'variable name' that is unique to it. A field's variable name can be defined in the Online Designer or in the Data Dictionary when adding/modifying a field in the project. The variable name can be utilized in various places and functionality in REDCap, such as in conditional logic, calculations, and piping. REDCap variable names are referenced by placing square brackets [ ] around it - e.g., [variable_name]. And if the project is longitudinal, in certain contexts you may need to additionally provide the unique event name, which must also be in brackets and prepended to the variable name, in order to target that field on a particular event - e.g., [event_2_arm_1][variable_name]. The usage of variable names inside brackets is often referred to as REDCap Field Notation.

An introduction to Smart Variables

In REDCap Field Notation, variable names always point to data fields in the project. However, another type of entity exists called 'Smart Variables' that allow you to reference information other than data fields. Smart Variables are context-aware and thus adapt to many different situations in which they can know who the current user is, what event is currently being viewed, whether or not an instrument is being viewed as a survey or data entry form, etc. In this way, Smart Variables are dynamic (and thus 'smart') because they adapt to the current context in which they are used. Smart Variables are easily distinguishable from field variable names because Smart Variables will have dashes and colons whereas field variable names cannot.

Smart Variables can be used...

• On their own - e.g., [record-dag-name]
• In conjunction with field variables - e.g., [previous-event-name][weight_measurement]
• In conjunction with other Smart Variables - e.g., [previous-event-name][survey-url:prescreening_survey]

How and where to use Field Notation & Smart Variables

Field notation (whether referencing variable names or using Smart Variables) can be utilized in many places throughout REDCap. This makes it very powerful to use for a variety of purposes. Regardless of where it is utilized, the format of variable names in field notation is always the same. If a variable is used on its own, it will simply be [variable], and if you wish to specify that field variable for a specific event (for longitudinal projects), you must prepend the unique event name - e.g., [event][variable]. If you are referencing a specific repeating instance of the field, you append (not prepend) the repeat instance number in brackets - e.g., [variable][2], in which the format is the same for both repeating instruments and repeating events. If you are referencing the second instance of a repeating event, for example, you would use the format [event][variable][2]. If you are wanting to determine if a certain option for a checkbox field is checked or not, you may include the checkbox option value inside parentheses which follow the variable name inside the brackets - e.g., [my_checkbox(4)]. All these components can be used together, if needed, such as if you want to reference checkbox option 3 that exists on the fifth instance of a repeating instrument on 'Event 1' - e.g., [event_1_arm_1][my_checkbox(3)][5].

Field notation and Smart Variables can be used for...

• Calculated fields - using mathematical operations to calculate a numerical result
• Conditional logic - includes branching logic, advanced filters for reports, and logic for Survey Queue, Data Quality rules, Custom Record Status Dashboards, and Automated Survey Invitations
• Piping - using field notation to insert values into labels on a survey/form or inside a survey invitation

NOTE: While Smart Variables can be utilized in Data Quality rule logic, in many cases they will cause Data Quality rules to take much longer to complete.

Smart Variable List

Listed below are all available Smart Variables, in which the description is given for each, along with an example of how it might be used. Please keep in mind that while Smart Variables can be used in calc fields, conditional logic, and piping, it does not mean that every Smart Variable should be used all of those places. For instance, you will likely only use [survey-link] and [form-url] for piping purposes. Also, [is-survey] and [next-event-name] will likely never make sense to be utilized in piping but instead in conditional logic (branching logic most likely). So remember that just because you *can* use Smart Variables in certain places does not necessarily mean that you *should*.