REDCap Smart Variables
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.
ADMINISTRATOR NOTE: Since you are a REDCap administrator, please be advised that you may also use Smart Variables inside the query of a dynamic SQL Field that is displayed on a survey or data entry form. You may see the SQL Field instructional popup in the Online Designer for tips on how to do this.
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*.
| |||
Name of Smart Variable | Description | Example of Usage | |
|---|---|---|---|
Example input | Example output | ||
User | |||
user-name | The current user's REDCap username. |
| jane_doe |
user-fullname | The current user's first and last name (as listed on their Profile page). |
| Jane Doe |
user-email | The current user's primary email address (as listed on their Profile page). |
| |
user-dag-name | The Data Access Group (the unique group name) to which the current user belongs (blank if not in a DAG). |
| vanderbilt_group |
user-dag-id | The group ID number of the Data Access Group to which the current user belongs (blank if not in a DAG). |
| 324 |
user-dag-label | The name/label of the Data Access Group to which the current user belongs (blank if not in a DAG). |
| Vanderbilt Group |
user-role-id | The Role ID of the user role to which the current user is assigned (blank if not assigned to any user role). This value is auto-generated for each user role. NOTE: This value is not just unique for all roles within the project but is also unique across all REDCap projects. Thus, if the project and its user roles are copied, the Role IDs of the user roles in the resulting copy will be different from the ones in the original project. |
| 127 |
user-role-name | The unique role name of the user role to which the current user is assigned (blank if not assigned to any user role). This value is auto-generated for each user role. NOTE: This value is only unique for roles within the project. Thus, if the project and its roles are copied, the new project will retain the same unique role names, which allows you to utilize the unique role names in conditional logic, calculations, branching logic, etc. that will not break when the project is copied. |
| U-699N7ET9KR |
user-role-label | The name/label of the user role to which the current user is assigned (blank if not assigned to any user role). This value is defined by the user that creates the user role. |
| Data Entry Person |
Record | |||
calendar-link:Custom Text | The HTML web link that, when clicked, will navigate to the calendar feed or downloadable ICS calendar file belonging to the current record. 'Custom Text' is an optional parameter whereby you can specify the visible link text, and if it is not provided, it defaults to simply displaying the URL as the link text. |
| |
calendar-url | The web address (URL) of the calendar feed or downloadable ICS calendar file belonging to the current record. |
| |
record-dag-id | The group ID number of the Data Access Group to which the current record belongs (blank if not in a DAG). |
| 96 |
record-dag-label | The name/label of the Data Access Group to which the current record belongs (blank if not in a DAG). |
| Harvard Site |
record-dag-name | The Data Access Group (the unique group name) to which the current record belongs (blank if not in a DAG). |
| harvard_site |
record-name | The record name of the current record. |
| 108 |
Form | |||
is-form | Detects if the current instrument is being viewed as a data entry form (returns 1 for True, 0 for False), as opposed to a survey. |
| 1 |
form-url:instrument | The web address (URL) of the specified data entry form for the current record/event/instance. The format must be [form-url:instrument], in which 'instrument' is the unique form name of the desired instrument. |
| |
| |||
form-link:instrument:Custom Text | The HTML web link that, when clicked, will navigate to the specified data entry form for the current record/event/instance. The format must be [form-link:instrument] or [form-link:instrument:Custom Text], in which 'instrument' is the unique form name of the desired instrument. 'Custom Text' is an optional parameter whereby you can specify the visible link text, and if it is not provided, it defaults to the form label of the data entry form. The format [form-link:Custom Text] can also be used if the instrument is assumed, such as when viewing a form or in a survey invitation. Also, it can be used simply as [form-link] inside the content of a survey invitation, in which 'instrument' is assumed to be the current survey instrument. |
| |
| |||
| |||
instrument-name | The unique instrument name of the current survey or data entry form. It will return a blank value if not in an instrument context. |
| demographics |
| prescreening_survey | ||
instrument-label | The instrument label of the current survey or data entry form. It will return a blank value if not in an instrument context. |
| Demographics |
| Pre-Screening Survey | ||
Survey | |||
is-survey | Detects if the current instrument is being administered as a survey (returns 1 for True, 0 for False), as opposed to a form. |
| 0 |
survey-url:instrument | The web address (URL) of the specified survey for the current record/event/instance. The format must be [survey-url] or [survey-url:instrument], in which 'instrument' is the unique form name of the desired instrument. This can be used simply as [survey-url] inside the content of a survey invitation, in which 'instrument' is assumed to be the current survey instrument. |
| |
| |||
survey-link:instrument:Custom Text | The HTML web link that, when clicked, will navigate to the specified survey for the current record/event/instance. The format must be [survey-link], [survey-link:instrument], or [survey-link:instrument:Custom Text], in which 'instrument' is the unique form name of the desired instrument. 'Custom Text' is an optional parameter whereby you can specify the visible link text, and if it is not provided, it defaults to the survey title of the survey. The format [survey-link:Custom Text] can also be used if the instrument is assumed, such as when viewing a form or in a survey invitation. Also, it can be used simply as [survey-link] inside the content of a survey invitation, in which 'instrument' is assumed to be the current survey instrument. |
| |
| |||
| |||
survey-access-code:instrument | The Survey Access Code of the specified survey for a given record/event/instance. The format must be [survey-access-code] or [survey-access-code:instrument], in which 'instrument' is the unique form name of the desired instrument. This can be used simply as [survey-access-code] inside the content of a survey invitation, in which 'instrument' is assumed to be the current survey instrument. |
| LDNP3EW7W |
| DDFRLCTCR | ||
survey-return-code:instrument | The Survey Return Code of the specified survey for a given record/event/instance in order to allow a participant to return to a completed or partially completed survey response when using the 'Save & Return Later' survey feature. The format must be [survey-return-code] or [survey-return-code:instrument], in which 'instrument' is the unique form name of the desired instrument. This can be used simply as [survey-return-code] inside the content of a survey invitation, in which 'instrument' is assumed to be the current survey instrument. |
| TFX4E4YN |
| HEJNFHD4 | ||
survey-queue-url | The web address (URL) of the survey queue for the current record. |
| |
survey-queue-link:Custom Text | The HTML web link that, when clicked, will navigate to the survey queue for the current record. The format must be [survey-queue-link] or [survey-queue-link:Custom Text], in which 'Custom Text' is an optional parameter whereby you can specify the visible link text. And if it is not provided, it defaults to 'Survey Queue Link'. |
| |
| |||
survey-title:instrument | The survey title of the instrument specified by the 'instrument' parameter (if provided). If the 'instrument' parameter is not provided, the current survey instrument will be used, else it will return a blank value if not in an instrument/survey context. |
| Enter to Win a New Car |
| Cardiology Study: Pre-Screening Survey | ||
survey-time-started:instrument | The date and time on which the specified survey instrument was started for the current record/event (i.e., the initial time the survey page is opened). The format must be [survey-time-started:instrument], in which 'instrument' is the unique form name of the desired instrument. In a piping context, such as in a field label, survey invitation, or inside the @DEFAULT action tag, the format of the date and time will be displayed based on the current user's date/time display preferences. If you wish to have it return the raw value, which will instead be in 'YYYY-MM-DD HH:MM:SS' format and would be more appropriate for conditional logic or calculated fields, simply append ':value'. NOTE: If the start time is a blank value, it implies that the response began while on an earlier version of REDCap when start times were not yet collected. |
| 12/25/2018 09:00am |
| 2018-12-25 09:00:00 | ||
| 12/25/2018 09:00am | ||
| 2018-12-25 09:00:00 | ||
survey-date-started:instrument | The date on which the specified survey instrument was started for the current record/event (includes date component only, unlike [survey-timestamp]). The format must be [survey-date-started:instrument], in which 'instrument' is the unique form name of the desired instrument. In a piping context, such as in a field label, survey invitation, or inside the @DEFAULT action tag, the format of the date will be displayed based on the current user's date display preferences. If you wish to have it return the raw value, which will instead be in 'YYYY-MM-DD' format and would be more appropriate for conditional logic or calculated fields, simply append ':value'. NOTE: If the start time is a blank value, it implies that the response began while on an earlier version of REDCap when start times were not yet collected. |
| 12/25/2018 |
| 2018-12-25 | ||
| 12/25/2018 | ||
| 2018-12-25 | ||
survey-time-completed:instrument | The date and time on which the specified survey instrument was completed for the current record/event. The format must be [survey-time-completed:instrument], in which 'instrument' is the unique form name of the desired instrument. In a piping context, such as in a field label, survey invitation, or inside the @DEFAULT action tag, the format of the date and time will be displayed based on the current user's date/time display preferences. If you wish to have it return the raw value, which will instead be in 'YYYY-MM-DD HH:MM:SS' format and would be more appropriate for conditional logic or calculated fields, simply append ':value'. If the survey has not been completed, it returns a blank value. |
| 12/25/2018 09:00am |
| 2018-12-25 09:00:00 | ||
| 12/25/2018 09:00am | ||
| 2018-12-25 09:00:00 | ||
survey-date-completed:instrument | The date on which the specified survey instrument was completed for the current record/event (includes date component only, unlike [survey-timestamp]). The format must be [survey-date-completed:instrument], in which 'instrument' is the unique form name of the desired instrument. In a piping context, such as in a field label, survey invitation, or inside the @DEFAULT action tag, the format of the date will be displayed based on the current user's date display preferences. If you wish to have it return the raw value, which will instead be in 'YYYY-MM-DD' format and would be more appropriate for conditional logic or calculated fields, simply append ':value'. If the survey has not been completed, it returns a blank value. |
| 12/25/2018 |
| 2018-12-25 | ||
| 12/25/2018 | ||
| 2018-12-25 | ||
survey-duration:instrument:units | The amount of time that has elapsed since the survey was started (returned in the time units specified, defaults to 's'), and represents the difference between the survey's start time and either its 1) completion time (if completed) or 2) the current time (if not completed). Options for 'units': 'y' (years, 1 year = 365.2425 days), 'M' (months, 1 month = 30.44 days), 'd' (days), 'h' (hours), 'm' (minutes), 's' (seconds). Tip: The units value should not be wrapped in apostrophes or quotes. NOTE: If using [survey-duration] inside a calculated field or @CALCTEXT field, the value for partially completed surveys will always be changing until the survey is completed, and thus the value might not be accurate on reports or data exports unless you run Data Quality rule H immediately beforehand. |
| 845 |
| 2.34 | ||
| 3829 | ||
survey-duration-completed:instrument:units | The total time it took to complete the survey (returned in the time units specified, defaults to 's'), and represents the difference between the survey's start time and completion time. NOTE: A blank value will be returned if the survey has not been completed. Options for 'units': 'y' (years, 1 year = 365.2425 days), 'M' (months, 1 month = 30.44 days), 'd' (days), 'h' (hours), 'm' (minutes), 's' (seconds). Tip: The units value should not be wrapped in apostrophes or quotes. |
| 93 |
| 12.7 | ||
| 3.89 | ||
Event & Arm | |||
event-id | (longitudinal only) The event id number of the current event. |
| 112 |
event-number | (longitudinal only) The current event's ordinal number as listed on the Define My Events page that denotes the order of the event within a given arm. |
| 4 |
event-name | (longitudinal only) The current event (unique event name). Note: This can be used as stand-alone or can be prepended to a field variable. |
| event_2_arm_1 |
| 125 | ||
event-label | (longitudinal only) The current event (the event label, not the unique event name). |
| Event 2 |
previous-event-name | (longitudinal only) The event (unique event name) that occurs immediately before the current event (blank if current event is the first event). Note: This can be used as stand-alone or can be prepended to a field variable. Important: When using this as a stand-alone variable, it will always return the event that occurs *immediately* before the current event, whereas if it is prepended to another variable, it will instead return the closest previous event for which the field's instrument has been designated, which might be different than the event that occurs directly before the current event. This behavior is due to the fact that the field's instrument might not always be designated for the event that occurs directly before the current event. |
| visit_4_arm_2 |
| 62 | ||
previous-event-label | (longitudinal only) The event (the event label, not the unique event name) that occurs immediately before the current event (blank if current event is the first event). |
| Visit 4 |
next-event-name | (longitudinal only) The event (unique event name) that occurs immediately after the current event (blank if current event is the last event). Note: This can be used as stand-alone or can be prepended to a field variable. Important: When using this as a stand-alone variable, it will always return the event that occurs *immediately* after the current event, whereas if it is prepended to another variable, it will instead return the closest following event for which the field's instrument has been designated, which might be different than the event that occurs directly after the current event. This behavior is due to the fact that the field's instrument might not always be designated for the event that occurs directly after the current event. |
| event_3_arm_5 |
| Taylor | ||
next-event-label | (longitudinal only) The event (the event label, not the unique event name) that occurs immediately after the current event (blank if current event is the last event). |
| Third Timepoint |
first-event-name | (longitudinal only) The first event (unique event name) for the current arm. Note: This can be used as stand-alone or can be prepended to a field variable. Important: When using this as a stand-alone variable, it will always return the first event for the current arm, whereas if it is prepended to another variable, it will instead return the first event (for the current arm) for which the field's instrument has been designated, which might be different than the very first event. This behavior is due to the fact that the field's instrument might not always be designated for the very first event. |
| visit_1_arm_2 |
| 74 | ||
first-event-label | (longitudinal only) The first event (the event label, not the unique event name) for the current arm. |
| Visit 1 |
last-event-name | (longitudinal only) The last event (unique event name) for the current arm. Note: This can be used as stand-alone or can be prepended to a field variable. Important: When using this as a stand-alone variable, it will always return the last event for the current arm, whereas if it is prepended to another variable, it will instead return the last event (for the current arm) for which the field's instrument has been designated, which might be different than the very last event. This behavior is due to the fact that the field's instrument might not always be designated for the very last event. |
| week_22_arm_1 |
| Minor | ||
last-event-label | (longitudinal only) The last event (the event label, not the unique event name) for the current arm. |
| Week 22 |
arm-number | (longitudinal only) The current arm number. |
| 2 |
arm-label | (longitudinal only) The arm label text of the current arm. |
| Drug B |
Repeating Instruments and Events | |||
previous-instance | (repeating instruments/events only) The repeating instance number that occurs immediately before the current instance (e.g., current instance minus 1). 'Instance' refers to the instance of either a repeating instrument or a repeating event. Note: This can be used as stand-alone or can be appended to a field variable. |
| 3 |
| 145 | ||
current-instance | (repeating instruments/events only) The repeating instance number of a repeating instrument or a repeating event in the current context. Note: This can be used as stand-alone or can be appended to a field variable. |
| 2 |
| 84 | ||
next-instance | (repeating instruments/events only) The repeating instance number that occurs immediately after the current instance (e.g., current instance plus 1). 'Instance' refers to the instance of either a repeating instrument or a repeating event. Note: This can be used as stand-alone or can be appended to a field variable. |
| |