REDCap 8.4

NEW FEATURES, BUG FIXES, & OTHER CHANGES:

• New feature: Smart Variables

  • Smart Variables are dynamic variables that can be used in calculated fields, conditional/branching logic, and piping. Similar to using project variable names inside square brackets - e.g., [heart_rate], Smart Variables are also represented inside brackets - e.g., [user-name], [survey-link], [previous-event-name][weight], or [heart_rate][previous-instance]. But instead of pointing to data fields, Smart Variables are context-aware and thus adapt to the current situation. Some can be used with field variables or other Smart Variables, and some are meant to be used as stand-alone. There are many possibilities.

  • 35 Smart Variables are available. They can reference things with regard to users, records, forms, surveys, events/arms, or repeating instances. Documentation and examples for using Smart Variables are included on the Project Setup page, Online Designer, and other places throughout REDCap in a popup and alternatively as a standalone page.

  • Note: While Smart Variables can be used for filters in reports and for filters for Custom Record Status Dashboards, they are not yet able to be utilized in Data Quality rule logic.

• Improvement: SQL fields can utilize Smart Variables

  • Note: This feature can only be set up by REDCap administrators. Please contact the support team at redcap@ualberta.ca if you believe you need it for your project.

  • SQL queries is an existing feature that allows a multiple choice "drop-down" variable to be populated with data that is derived from the REDCap database. Typically this would be data from another project but it could be any data in the database. 

  • Utilizing Smart Variables in SQL fields can be very powerful because they allow the query to be truly dynamic and change from context to context or record to record, rather than it always being a static query that gets executed against the database.

• Improvement: Custom Record Labels now use proper piping syntax and can also utilize Smart Variables.

  • Because Custom Record Labels existed long before the concept of piping was created in REDCap, they did not adhere to typical piping concepts – e.g., they could not use prepended event names; they would display the raw value of a multiple choice field whereas piping would instead display the label of a multiple choice field. There also used to be certain limitations Custom Record Labels, in which they could only use data from fields on the very first event (of the current arm). Now that Custom Record Labels can be used like regular piping, they can target fields on any event in a project, and they can also utilize Smart Variables.

  • Note: Any longitudinal projects existing before the upgrade that currently use Custom Record Labels will automatically have all fields in the Custom Record Label prepended with the [first-event-name] Smart Variable in order to maintain the existing behavior from previous versions that could only pull data from the first event of the current arm. So prepending [first-event-name] allows existing longitudinal projects to maintain the way they worked prior to the upgrade to this REDCap version.

• Improvement/change: New method for composing survey invitation text using Smart Variables for survey link

  • When composing a survey invitation, the standard text and survey link are no longer automatically appended to the survey invitation text at the time the email is sent. Instead, users must now specify all the entirety of the text of the email (including the stock text and survey link that used to be appended automatically, if they wish) and therefore must supply [survey-url] and/or [survey-link] in the text if they wish to provide the participant with a link to the survey.

  • If the user forgets to enter the survey URL Smart Variable in the text, REDCap will automatically suggest to them that they should.

  • If using the Twilio telephony module for sending invitations, the standard instructional text will still be appended in the SMS message as in previous versions EXCEPT for the “Email invitation” and “SMS invitation (contains survey link)” invitation types, which require [survey-url] and/or [survey-link] in the SMS text in order for the participant to receive a survey link.

  • Note: All survey invitations that were scheduled prior to this upgrade will still have the standard text and survey link appended to their survey text. Additionally, during the upgrade to this version, all saved configurations for Automated Survey Invitations (ASIs) will have the standard text and survey link automatically appended to the saved ASI email text, thus allowing the ASI behavior to remain exactly the same after the upgrade and allowing it to be backward compatible.

• New feature: New syntax for referencing fields on repeating instances in piping, logic, and calculations

  • Fields that exist on a repeating instrument or on a repeating event can be referenced using a new syntax (note: repeating events and instruments are used the exact same way). This is done by appending the “repeat instance” number to the field inside square brackets – e.g., [weight][2], which points to repeating instance #2 for the field “weight”.

  • Please note the distinction that unique event names should be *prepended* to variables whereas repeating instance numbers must be *appended* to them. For example, if the field “weight” exists on a form in the event “Visit Data” in a longitudinal project, you might reference instance #2 for that field on that specific event with the following: [visit_data_arm_1][weight][2].

  • Smart Variables can be used in place of the repeating instance number, in which there are 5 instance-related Smart Variables: [previous-instance], [next-instance], [current-instance], [first-instance], and [last-instance]. For example, if you wish to use @DEFAULT action tage to carry over data from the previous instance of a repeating instrument, it might be set up as follows: @DEFAULT=”[weight][previous-instance]”.

• Improvement: Piping can now be used for checkbox fields

  • Piping from Checkbox fields is slightly different than with other field types because checkboxes allow for multiple saved values. There are options to display a list of checked choices, unchecked choices, or a specific choice.

    • [my_checkbox:checked] - Appending ':checked' will display a comma-delimited list of choice labels that have been checked - e.g., 'Sunday, Tuesday, Thursday'. Note: If neither ':checked' nor ':unchecked' is appended to the variable, then it will default to ':checked'.

    • [my_checkbox:unchecked] - Appending ':unchecked' will display a comma-delimited list of choice labels that have NOT been checked - e.g., 'Monday, Wednesday, Friday, Saturday'.

    • [my_checkbox(code)] - If a coded value of the checkbox is included inside parentheses after the variable name - e.g., [my_checkbox:(2)] - then it will output the word 'Checked' or 'Unchecked' regarding whether or not that specific choice has been checked off.

  • Please note that while the checkbox piping options listed above will return the text labels, you may also append ':value' to the variable to return the raw value instead of the label. For example, [my_checkbox:checked:value] and [my_checkbox:unchecked:value] might return '1, 3, 5' and '2, 4, 6, 7', respectively, and [my_checkbox(2):value] will return 1 or 0 if checked or not checked, respectively.

• Improvement: Multiple choice fields can now have their raw value (as opposed to their choice label) piped by appending “:value” to the variable name – e.g., [my_radio_field:value]. Note: This can also be used for SQL Fields to display the raw value of the SQL Field drop-down.

• Improvement: Multiple choice fields can now have their raw value (as opposed to their choice label) piped inside an @DEFAULT action tag by appending “:value” to the variable name – e.g., @DEFAULT=”[my_radio_field:value]”.