REDCap upgrade May 8 includes new features and improvements; expect downtime from 8 p.m. to 10 p.m.
On the evening of Tuesday, May 8, 2018, the CTS-IT will upgrade REDCap from version 8.3.0 to 8.4.0. You can expect a downtime for REDCap from 8:00 p.m. to 10:00 p.m. while we complete the upgrade. Some of the new features coming with the upgrade include Smart Variables, the ability to specify different email fields for each survey in your project and enhanced piping, calculation and branching logic for repeating forms.
- 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.
Survey-specific email invitation fields
- This is a new option on the Survey Settings page that can be enabled for any given survey, in which a user may designate an email field for sending survey invitations for that survey only.
- The email field being utilized for the survey can exist on any instrument in the project, and you may use a different email field on each survey. You may also use the same email field for multiple surveys.
- This feature is similar to the project-level email invitation field except that it is employed only for the survey where it has been enabled. This allows users to have data entry workflows that require multiple surveys where the participant is different for each survey. Using this feature, multiple people can be emailed a survey invitation, after which all the survey data they enter goes into the same record in the project.
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], 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].
- 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 tags to carry over data from the previous instance of a repeating instrument, it might be set up as follows: @DEFAULT=”[weight][previous-instance]”.
SQL fields can utilize Smart Variables
- 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.
- Note: When using Smart Variables inside the query of an SQL field, you do NOT need to wrap the Smart Variable in quotes or apostrophes because the Smart Variable itself will be replaced with a value already wrapped in single quotes. Also, the value of the Smart Variable will be SQL-escaped when placed inside the query so that no user can inject values to manipulate the query. This has no effect on how one constructs the query, but for security purposes it is good to know that this is being done.
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.
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.
- 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.
- 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]”.
Copying a project (via the Other Functionality tab on the Project Setup page)
- When using the Copy Project button on the Other Functionality page, it now copies the Record Locking Customization settings for the project.
- When using the Copy Project button on the Other Functionality page, it now displays an option to the user to copy all custom record status dashboards in the project.
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.
Exporting data into SPSS
- When exporting data to SPSS, the resulting SPSS syntax file now defines Text fields as A30000 rather than A500 to allow for Text fields with text longer than 500 characters.