Multi-Language Management
Summary: Users can create and configure multiple display languages for their projects for surveys, data entry forms, alerts, survey invitations, etc. Users can design data collection instruments and have them be displayed in any language that they have defined and translated so that their survey participants or data entry persons can view the text in their preferred language. This eliminates the need to create multiple instruments or projects to handle multiple languages. NOTE: The MLM feature will not auto-translate text, but provides tools so that users may easily translate them themselves. Usage: When entering data on a data entry form or survey, users and participants will be able to choose their language from a drop-down list or buttons on the page to easily switch to their preferred language for the text displayed on the page. This feature allows users to translate all text related to the data entry process, both for surveys and for data entry forms. Even various survey settings and email text can be translated. For users on data entry forms, if a language is selected, that selection is stored in the user's user account settings internally (in the REDCap backend database), whereas a survey participant's selected language will be stored in a cookie in their web browser as a way to remember their language preference if they return in the future (and also to maintain their selected language from page to page). The language can be pre-selected for a participant, if desired, using the "Language preference field" setting on the MLM page in the project or via the @LANGUAGE-FORCE action tags (seen below). When using the survey setting "Save a PDF of completed survey response to a File Upload field", users can now optionally set this feature to store the translated version of the PDF if the Multi-language Management feature is being utilized for the survey. This can be enabled by checking the "Store the translated version of the PDF" checkbox below the "Save a PDF..." setting on the Survey Settings page for the desired survey. When using Multi-Language Management on a survey, the current language name is displayed next to the globe icon at the top right of the survey page so that participants more intuitively understand what the current language is and to click it to change the language. User Rights: Users must have Project Design/Setup privileges in a project in order to see the link to the Multi-Language Management page on the left-hand menu. Note: When a project is in production, the MLM page and all translations can only be modified when the project is in Draft Mode. So if the user desires to make edits or additions to their translations, they must first enable Draft Mode via the Online Designer, and then return to the MLM page to make translation changes while in Draft Mode. When the drafted changes are approved, their translation changes made while in Draft Mode will automatically be approved together with them. Form Display Logic
Form Display Logic is an advanced feature that provides a way to use conditional logic to disable specific data entry forms that are displayed on the Record Status Dashboard, Record Home Page, or the form list on the left-hand menu. You might think of it as 'form-level branching logic'. Form Display Logic can be very useful if you wish to prevent users from entering data on a specific form or event until certain conditions have been met. The forms will still be displayed on the page, but they will be disabled in order to prevent users from accessing them. Below you may define as many conditions as you want. A form may be selected in multiple conditions, but if so, please note that the form will be enabled if at least one of the conditions is met. The Form Display Logic does not impact data imports but only operates in the data entry user interface to enable/disable forms. Additionally, Form Display Logic is not utilized by the Survey Queue at all but can affect the behavior of the Survey Auto-Continue feature if the checkbox for it is enabled in the setup dialog. The Form Display Logic setup can be found by clicking the "Form Display Logic" button at the top of the instrument list in the Online Designer.
Protected Email Mode
Users can enable the Protected Email Mode on any project on the Project Setup via the Additional Customization dialog. This setting prevents identifying data (PHI/PII) from being sent in outgoing emails for alerts, survey invitations, and survey confirmation emails.
If enabled, either A) all alerts, survey invitations, and survey confirmation emails or B) those whose email body is attempting to pipe data from Identifier fields will be affected, in which it will not send the full email text to the recipient but will instead send a surrogate email containing a link that leads them to a secure REDCap page to view their original email. If someone is accessing an email in the Protected Email Mode for the first time (or for the first time in the past 30 days), it will send a security code to their inbox that will allow the recipient to view any protected emails for up to 30 days on that same device. The Protected Email Mode is similar to Microsoft Outlook's "sensitivity label" feature. Repeating Automated Survey Invitations (ASIs)
Users can now set ASIs to send multiple times on a recurring basis for any repeating survey in a project. If the survey is a repeating instrument or if it exists on a repeating event, then users will see a new section "How many times to send it" in the ASI setup popup in the Online Designer. There users may set the ASI to send survey invitations repeatedly at a regular interval, in which it can repeat forever or a set number of times. This new repeating ASI feature works similarly to how recurring alerts have always worked for Alerts & Notifications. Note: If an instrument is not a repeating survey, then this new section will not appear for that survey in the ASI setup dialog.
When an ASI is set up to recur for a repeating survey, the REDCap Upgrade New Features and Improvements Summary Smart Variable in the invitation text will always point to a different repeating instance of the survey for each time the invitation is sent. For example, if the ASI is set to recur daily, then the first day's invitation will have a link pointing to instance #1 of the survey, the next day's invitation will point to instance #2, then the next to #3, and so on. Embedding images in text & emails
Users may now embed one or more inline images into the text of a survey invitation, an alert, or a field label on a form/survey, among other things, by clicking the image icon in the rich text editor and then by uploading an image from their local device. Anywhere that the rich text editor is used, users may embed an image into its text (with one exception: the @RICHTEXT action tag on public surveys).
Integration of many features from the "Survey UI Tweaks" External Module
If custom question numbering is used on a survey page in which no questions have a custom question number defined, the extra space on the left of the questions will be removed to give the questions more room for display on the page.
On the Survey Settings page, the setting "For Required fields, display the red 'must provide value' text on the survey page?" now has a new option: "Display only the red asterisk". This provides an additional option rather than having to choose between the binary options to hide or not hide the text.
When taking a survey while on a mobile device, the survey page will auto-scroll whenever selecting a value for a drop-down or radio button field to help the participant scroll down the page more easily.
New survey setting allows users to set a custom width of the survey displayed on the page between 50% and 100%. The default value for the setting is "Fixed width (default)".
New survey setting allows users to display or hide the font resize icons at the top of the survey page. By default, it is set to display the font resize options.
New survey setting allows users to show or hide the Submit buttons displayed at the bottom of every survey page (including the 'Next Page' and 'Previous Page' buttons).
New survey setting allows users to provide alternative text for the 'Submit', 'Next Page', and 'Previous Page' buttons displayed at the bottom of every survey page. Instrument-level Data Export Rights
Users may specify instrument-level privileges regarding a user's data export capabilities on the User Rights page in a project. A user may be given "No Access", "De-Identified", "Remove All Identifier Fields", or "Full Data Set" data export rights for EACH data collection instrument. This improvement will make it much easier to match a user's Data Exports Rights with their Data Viewing Rights, if you wish, and will give users more granular control regarding what data a user can export from your project. Note: Whatever a user's data export right was in the previous version, that export right will be subsequently extrapolated to all instruments after upgrading. Thus, their export privileges will behave exactly the same as before.
The table displayed on the User Rights page that lists all users' privileges now includes an instrument count for each category for both Data Viewing Rights and Data Export Rights - e.g., "3 No access, 2 Full Data Set". This helps provide summary information regarding the user's instrument-level rights.
When adding/editing a user's or user role's privileges in the popup on the User Rights page, as a convenience, users may click the table headers for each Data Export Rights setting or Data Viewing Rights setting to set that setting for all instruments in the project (i.e., as a "check all checkboxes").
Note: When adding a new data collection instrument to a project, if the project is in development status, all users will automatically receive "Full Data Set" data export rights for that new instrument. Whereas if the project is in production, all users will automatically receive "No Access" data export rights for the new instrument. This behavior matches how instrument-level rights currently work for Data Viewing Rights when adding a new instrument. Survey Start Time and related Smart Variables
REDCap now collects when participants begin a survey (i.e., the initial time the survey page is opened). Going forward, any responses collected (partial or completed) will have their start time displayed at the top of the data entry form when viewing the response. 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.
New Smart Variables for Survey Start Date/Time: Users can access the start time via piping by using the new Smart Variables [ survey-time-started:instrument ] and [ survey-date-started:instrument ], which can be used inside the "@DEFAULT" or "@CALCTEXT" action tags, among other places. If users wish to have them return the raw value, which will be in 'YYYY-MM-DD HH:MM:SS' format and would be more appropriate for conditional logic or calculated fields, simply append ':value' after the unique instrument name - e.g., [ survey-date-started:instrument:value ].
New Smart Variables for Survey Duration: Users can obtain the total amount of time that has elapsed since the survey was started (in seconds, minutes, etc.) by using [ survey-duration:instrument:units ] and [ survey-duration-completed:instrument:units ]. The Smart Variable [ survey-duration ] 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), whereas [ survey-duration-completed ] represents the difference between the survey's start time and completion time, in which 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). Conditional logic for Survey Auto-Continue
When enabling Survey Auto-Continue on the Survey Settings page for a survey, users may now optionally specify conditional logic to determine whether or not the auto-continue should be applied. As such, REDCap will auto-continue to the next survey *only* if the conditional logic is TRUE or if the logic textbox has been left blank. This new option can be used as a simpler alternative to the Survey Queue, which can require more complex instrument-event level configurations for longitudinal projects.
Dynamic min/max range limits for fields
Instead of using exact values as the minimum or maximum range of Textbox fields (e.g., "2021-12-07"), you may now also use "today" and "now" as the min or max so that the current date or time is always used. These can be used to prevent a date/time field from having a value in the past or in the future. Additionally, you can now pipe a value from another field into the field's min or max range setting - e.g., [visit_date] or [event_1_arm_1][age]. This can help ensure that a Textbox field (whether a date, time, or number) has a larger or smaller value than another field, regardless of whether the field is on the same instrument or not.
Email Logging page
This is a new project page that contains a search interface to allow users with User Rights privileges to search and view ALL outgoing emails for that project.
"Re-send email" feature - When viewing an individual email after performing a search on the page, a "Re-send email" button will be displayed in the dialog to allow users to re-send the email. Note: If the original email contained email attachments, the attachments will not be included in the email that is re-sent.
Only users with User Rights privileges in the project may access the page, and additionally they must opt-in and agree to a disclaimer before being able to view the page. The following text will be presented to the user before accessing the page: "Before viewing and accessing this page, you must first agree that you understand the following important information and conditions. This page is only accessible by users having User Rights privileges in this project. The Email Logging feature allows users to search and view *all* outgoing emails related to this project, and this includes being able to view all aspects of any given email (i.e., the recipient(s), sender, subject, message body, attachment names). If you are using anonymous surveys in this project, keep in mind that viewing this page and the emails displayed therein might inadvertently cause anonymous survey responses to be identifiable/de-anonymized. Additionally, if the project is using Data Access Groups, you will be able to view the emails related to all DAGs in this project (and thus possibly any data piped into the body of those emails). If you understand and agree to these conditions, click the button below. Please note the act agreeing to this disclaimer will be documented on the project Logging page." New data export option
Export blank values for gray instrument status
All instrument complete status fields having a gray icon can be exported either as a blank value or as "0"/"Incomplete". In previous versions, they could only be exported as "0". By default, they are now exported with a value of "0", but this option can be changed via a drop-down option in the "Advanced data formatting options" section of the data export dialog.
When exporting the Project XML file with both metadata & data, the option to export gray instrument status as a blank value will be preselected by default, whereas in other data export contexts (e.g. My Reports & Exports page), the option to export them as "0" will be preselected by default.
The API method "Export Records" has a new optional parameter "exportBlankForGrayFormStatus" that can accept a boolean (true/false) with default value = false, and it functions the same as its equivalent data export option in the user interface.
Note: Exporting gray instrument statuses as blank values is recommended if the data will be re-imported into REDCap. For example, when users export a Project XML file for a project and then create a new project with it, all the gray instrument status icons will be preserved in the new project, whereas in previous versions they were all converted into red status icons. New Action Tags
"@FORCE-MINMAX" - The action tag "@FORCE-MINMAX" can be used on Textbox fields that have a min or max validation range defined so that no one will not be able to enter a value into the field unless it is within the field's specified validation range. This is different from the default behavior in which out-of-range values are permissible. Note: "@FORCE-MINMAX" is also enforced for data imports to ensure the value is always within the specified range.
New Action Tags for Multi-Language Management "@LANGUAGE-CURRENT-FORM" - Allows you to capture the currently used language in projects where multilingual data is enabled on data entry forms. The "@LANGUAGE-CURRENT-FORM" action tag can be used on fields of type 'Text Box' (no validation), and 'Drop-down List', or 'Radio Buttons' (these need to have choices whose codes correspond to the IDs of the defined languages - e.g., 'en'). This action tag is only active on data entry forms and will always, when possible, set the field's value to the currently active language. "@LANGUAGE-CURRENT-SURVEY" - Same as "@LANUGAGE-CURRENT-FORM", but works only on survey pages. For multi-page surveys, "@LANGUAGE-CURRENT-SURVEY" needs to be used on a field of each page where capture of the language is relevant (e.g. for performing branching). "@ LANGUAGE-FORCE" - When used on a field, the data entry form or survey on which the field is located will be rendered in the specified language (which must have been set up using the Multi-Language Management feature). The format must follow the pattern "@ LANGUAGE-FORCE"="???", in which the ID of the desired language should be inside single or double quotes - e.g., "@LANGUAGE-FORCE"="de". Piping is supported - e.g., "@LANGUAGE-FORCE"="[field_name]". When the language is forced successfully (i.e., it exists and is active), the language selector is hidden. Using this together with "@LANGUAGE-CURRENT-FORM/SURVEY" on the source field for "@LANGUAGE-FORCE" may be used to 'lock in' a user to their selected language. "@LANGUAGE-FORCE-FORM" - Same as "@LANGUAGE-FORCE", but the effect is limited to data entry forms (i.e. this does not affect surveys). "@LANGUAGE-FORCE-SURVEY" - Same as "@LANGUAGE-FORCE", but the effect is limited to surveys (i.e. this does not affect data entry forms). "@LANGUAGE-SET" - When used on a Drop-down or Radio Button field only, this action tag will allow the field's value to control the currently shown language (in the same way as switching the language via the buttons at the top of the page). Tip: When used in a survey, this field could be prepopulated (and thus auto-selected) by embedding a participant's language ID in the survey URL itself (for details, see the FAQ's "How to pre-fill survey questions" section).
"@IF" - Allows various action tags to be set based on conditional logic provided inside an "@IF"() function - e.g., "@IF"(CONDITION, ACTION TAGS if condition is TRUE, ACTION TAGS if condition is FALSE). Simply provide a condition using normal logic syntax (similar to branching logic), and it will implement one set of action tags or another based on whether that condition is true or false. For example, you can have "@IF"([yes_no] = '1', "@HIDDEN", "@HIDE-CHOICE"='3' "@READ-ONLY"), in which it will implement "@HIDDEN" if the 'yes_no' field's value is '1', otherwise, it will implement the two action tags "@HIDE-CHOICE"='3' and "@READ-ONLY". If you wish not to output any action tags for a certain condition, set it with a pair of apostrophes/quotes as a placeholder - e.g., "@IF"([my_radio]='1', "@READONLY", ''). You may have multiple instances of @IF for a single field. You may also have multiple nested instances of @IF() inside each other. Both field variables and Smart Variables may be used inside the @IF condition. The @IF action tag is also evaluated for a given field when downloading the PDF of an instrument/survey, in case there are any PDF-specific action tags used inside of "@"IF(). Note: The conditional logic will be evaluated only when the survey page or data entry form initially loads; thus the action tag conditions will not be evaluated in real time as data is entered on the page.
"@RICHTEXT" - Adds the rich text editor toolbar to a Notes field to allow users/participants to control the appearance (via styling and formatting) of the text they are entering into the field.
"@DOWNLOAD-COUNT" - P rovides a way to automatically count the number of downloads for a File Upload field or a Descriptive field attachment. It can be used on a Text field or Notes field so that its value will be incremented by '1' whenever someone downloads the file for either a File Upload field or a Descriptive field attachment. The variable name of the File Upload field or Descriptive field whose downloads are to be counted should be provided inside the "@DOWNLOAD-COUNT"() function. For example, the Text field 'my_download_count' might have its action tag defined as "@DOWNLOAD-COUNT" (my_upload_field), in which 'my_upload_field' is the variable of a File Upload field. Whenever the file is downloaded on a data entry form, survey page, or report, the value of the field with this action tag will be incremented by '1'. If that field has no value or has a non-integer value, its value will be set to '1'. NOTE: The download count field must be in the same context as the File Upload field or a Descriptive field. This means that in a longitudinal project the two fields must be on the same event, and in a repeating instrument context, they must be on the same repeating instrument. New Smart Variables
[ event-number ]
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. [ new-instance ] This new Smart Variable [ new-instance ] can be appended to [ survey-link ], [ survey-url ], [ form-link ], and [ form-url ] to create a URL that points to a new, not-yet-created repeating instance for the current record. In this way, [ new-instance ] functions essentially as [ last-instance ]+1. This new Smart Variable works for repeating instruments and also for instruments on repeating events.
[ new-instance ] can also be used as stand-alone, in which it will return an integer. But it will only work when used within the context of a repeating instrument or repeating event, in which it will essentially return 1+1 for the current repeating context.
[ new-instance ] will auto-append "&new" to the end of the form link or survey link (when used with [ form-link/url ] or [ survey-link/url ]) and thus will cause the user/participant to be redirected to the next repeating instance if the current repeating instance (i.e., the instance number in the URL) already exists for the record. Thus, using [ form-link ] or [ survey-link ] appended with ______ will ensure that you always end up on a new, not-yet-created instance. And if two participants arrive at the same repeating survey instance with both using the exact same link created by [ survey-link ][ new-instance ], then the second participant to submit the survey page will not override the first participant's response. Instead, it will add the second participant's response as another repeating instance that does not exist yet.
TIP: One of the main intended usages of [ new-instance ] is to utilize it as [ survey-link:instrument ][ new-instance ] inside the text of a recurring alert to allow users/participants to enter data easily into a repeating survey. In this way, it works very similarly to a repeating ASI. However, repeating ASIs do not need their survey link appended with [ new-instance ] because it is already implied from the ASI setup. *Ignore spaces before/after the brackets.
New Field Validations
"Time (HH:MM:SS)"
This new time-based field validation (unique name "time_hh_mm_ss") will be added automatically and enabled by default during the upgrade process. This validation forces users/participants to enter a time value that contains the hour, minute, and second components. It also includes the usage of the "Now" button and the timepicker popup widget, both of which are displayed next to the field on the survey page or data entry form. Note: Fields with this field validation can be utilized inside the datediff() function.
General Appearance and Performance
Stop Actions (for multiple choice fields) and Video Display Format settings (for Descriptive Text fields with videos) are now included in Instrument Zip files when downloading or uploading them for an instrument in the Online Designer. In previous versions, stop actions were not included, and while the video URL was included, the setting that defines if the video is displayed inline or not was not included.
In many places that display a drop-down list of records (e.g., Logging page, Email Logging, Field Comment Log, Data Quality page, ad hoc calendar event popup, Alerts & Notifications Log, Survey Notification Log), it will display a normal drop-down list if the project contains 5000 records or less, and if the project contains more than 5000 records, it will instead automatically revert to displaying an auto-suggest textbox to allow the user to manually enter the record name (rather than attempting to display an extremely long drop-down). This should make these pages load much faster and also make them easier to use in projects containing many records.
"Previous instrument" and "Next instrument" buttons were added at the top right of the Online Designer field-view page to allow easier navigation between instruments.
The Define My Events page now displays a new column to display each event's Event ID number. Also, the Smart Variable corresponding to each column in the table on the Define My Events page (e.g., 1, [event-label) are displayed in small gray text below the header text in the table to help users more easily learn where the values of those Smart Variables originate. Surveys
When setting up an ASI, the sub-section "When to send invitations AFTER conditions are met" now contains the new drop-down choice "the same day (beginning at midnight) that the automated invitation was triggered" in the sub-option "Send the invitation X days Y hours Z minutes before/after [drop-down]". This new choice in the drop-down allows users to schedule the invitation based on the day the ASI was triggered and provides greater control and precision with regard to when exactly the invitation will be sent. For example, if this new drop-down option is selected along with setting it to "send the invitation 1 day 8 hours after...", this will cause the invitation to be scheduled to be sent at exactly 8:00am the next morning. In previous versions, it was not possible to get this level of precision for the invitation send-time based upon ASI trigger-time unless you used a date field's value as a reference.
When setting up an Automated Survey Invitation, the setting to make the ASI "Active" or "Not Active" has been moved to the top right of the ASI setup dialog.
When a survey participant partially completes a survey that has the Save & Return Later feature enabled, and an email is then sent to the participant to remind them to finish their survey later, instead of sending that email from the system-level "Email Address of REDCap Administrator" (as in previous versions), the "From" email address of the "Survey partially completed" email will be set to the sender's address from the most recent survey invitation received by the participant. This will create more consistency and will reduce confusion for participants when attempting to reply back to the email, as has been a problem in the past. Reports
Any HTML used in the value of a Text field or Notes field will no longer be escaped on a report (i.e., displayed as-is) but instead the HTML will be interpreted on the report to allow for the styling of text on the page. This means that while previous versions would have displayed the text value "< b > Word< /b >" literally as "Word " (without quotes) on a report, it now instead displays "Word" as bolded text on a report.
Note: This does not affect data exports or any pages other than reports.
DAG
If a user is not assigned to a Data Access Group in a project, the user will now see a new "[No assignment]" option in the "Displaying Data Access Group" drop-down list on the Record Status Dashboard, in which selecting that option will display only records that have not been assigned to any DAG.
Data Import
When using the ''Reason for Change'' feature in a project, a new button is displayed underneath each "reason for change" textbox on the Data Import Tool summary page. Users can simply click the button to copy the text to all other "reason for change" textboxes on the page, thus saving lots of time of having to add text to each individually.
Project Revision History
The Project Revision History page now displays icons next to each production revision and snapshots, and after being clicked, will display options to compare that revision/snapshot with any other revision/snapshot in the project.
Online Designer
The Online Designer now denotes whether a field on the instrument contains embedded fields inside its label, choices, notes, etc. by displaying a blue box saying "Contains embedded fields", similar to the green "Field is embedded elsewhere on page" boxes for embedded fields themselves. This will provide users with visual cues to know when and where field embedding is occurring.
Codebook
The Codebook now contains a "Field Finder" to allow users to quickly search for a field by keyword or phrase in the field label or by variable name. Also, the gray "Instrument Name" rows in the table will float at the top of the page while scrolling so that it is always apparent the instrument to which a field belongs. Additionally, when scrolling down the page, an up-arrow image will appear at the bottom right of the page that (when clicked) will quickly scroll the page back to the top.
Piping
Piping can now be performed inside the value of the @PLACEHOLDER action tag - e.g., @PLACEHOLDER="[first_name] [last_name]". Help & FAQ Page
Each tab on the "Help & FAQ" page now has a drop-down list of subsections that, when selected, will auto-scroll the webpage down to that subsection on the page.