New feature: Repeating Instruments and Events
Introduction to Repeating Instruments and Repeating Events
REDCap has the ability to repeat a data collection instrument or an entire event of instruments an unlimited number of times without having to specify the amount needed. This is sometimes called one-to-many data collection, in which a project can have one or more repeating parts. For example, if each record in a hypothetical project represents a person, then one might have a repeating instrument for medications, one for family members, one for adverse events, and one for collecting data over multiple visits (or weekly surveys), so that each repeating element is connected to the overall record but can repeat independently of the other instruments. So if using repeating instruments or repeating events, each record in the project can have a different number of repeated instances of any given instrument or event. One record may have five medications, but another may have two or none, for example. Such flexibility makes this feature very powerful, and setting up repeating instruments and/or repeating events in a project is very quick and easy. The repeating instruments/events feature can be enabled and set up by clicking the Enable button in the Optional Modules section on the Project Setup page.
To see these new features in action, click the video link below. The first 5-10 minutes provide a good understanding of why the features are useful, how they work, and how to set them up. But if you’re interested in seeing their full capabilities, then we recommend watching the whole video.
Video “REDCap: Repeating Instruments and Events” , permission granted and provided by Vanderbilt University
Repeating Instruments (for classic and longitudinal projects)
Classic projects (i.e., in which the longitudinal module is not enabled) can utilize repeating instruments as a very simple way of doing longitudinal data collection. When traditionally using the longitudinal module in a project, one downside is that one must specify all the events (i.e., the repetitions of instruments) ahead of time, making sure to build out the maximum number of events that one might need, even though all of them likely won’t be used by all records. However, with the repeating instruments functionality, one does not need to specify how many repetitions will needed ahead of time; one can simply repeat an instrument an unlimited amount of times. It is important to note that multiple instruments in a project can be enabled as repeating instruments (even all of them, if one wishes). Projects utilizing the longitudinal module can have repeating instruments as well, in which one or more instruments on any defined event can be set to repeat within that event. The repeating instruments functionality behaves very much the same way in both classic and longitudinal projects.
Repeating Events (for longitudinal projects only)
If a project has the longitudinal module enabled, it can utilize the repeating events feature, which works somewhat differently than the repeating instruments feature. While the repeating instruments feature allows one to repeat a given instrument as a single unit, the repeating events feature allows one to repeat an entire event of instruments together in unison. This might be useful if one has several instruments whose data correlates together, such as completing multiple surveys back to back for a specific time-point or visit, for example. Previously, one may have had to create X number of identical events to capture repeating data for the instruments on those events (e.g., Week 1, Week 2, …), but the repeating events feature makes this much simpler by allowing one to create only one single event that can be repeated in unlimited fashion.
Enabling Surveys for Repeating Instruments
If one wishes to allow survey respondents to enter their responses in a repeating fashion in survey mode alone, one must enable an optional setting near the bottom of the Survey Settings page (in the survey termination options section) *after* an instrument has been set as a repeating instrument. So it is one additional step to do after enabling the instrument itself as a repeating instrument. When the repeat survey setting is enabled, it will display a button at the end of the survey so that the respondent can choose to enter another response for the survey, thus essentially allowing them to take the survey multiple times in a row. In this way, they will be able to enter as many responses for that same survey as they need. For example, if a REDCap project is aimed at mothers, and the repeating survey is for collecting data about each of the mother’s children, the mother could complete the survey once for each child, thus allowing mothers with one child or six children to easily enter their data in a quick back-to-back fashion by repeating the survey.
Reports and Data Exports with Repeating Instruments and Events
If one creates a report that contains data from a repeating instrument or repeating event, a field named ‘redcap_repeat_instance’ will be included that represents the instance number, which is an auto-numbered value (starting with ‘1’) that gets incremented each time the instrument/event is repeated. And if the report contains data specifically from a repeating instrument (as opposed to a repeating event), then a field named ‘redcap_repeat_instrument’ will additionally be included that represents the instrument name that denotes to which instrument the row of data belongs. These two fields will only be included automatically in the report or data export if data originates from a repeating instrument or event. Note: Each repeated instance of an instrument or event will be displayed as a new row in the report or export file. This means that if a medications survey is repeated three times for one record, for example, it will be displayed as three rows in the report.
- While repeating instruments/events are fully supported when using Double Data Entry with regard to data entry workflow, please see the following notice for the Data Comparison Tool: “The Data Comparison Tool does not *fully* support the Repeating Instruments and Events feature, which appears to be enabled in this project. Data can be compared (and even merged if using Double Data Entry), but it will only allow comparison and merging of Instance #1 of a repeating instrument or repeating event. Thus all other repeating data will be ignored on this page. Also, all non-repeating data can still be compared and merged.”
- Added new project template to showcase the Repeating Instruments functionality.
- Please note that, while having these new repeating instruments and repeating events is exciting and wonderful, there are some things that you might think that you can do with them which you cannot, at least yet:
- See the previous bullet point about Double Data Entry.
- You cannot schedule surveys that are in repeated instruments or repeated events to go out on a regular basis. You need to compose the survey invitation for each instance manually using either the compose invitations in the participant list or the option to send a survey invitation in the survey instance itself.
- You cannot (yet) refer to a field in a repeated form or in a form in a repeated event by the instance number. I think this will come before long, but it is not yet available.
- Survey Queues in repeating events only work on the first instance of the event.
Click here to see the following new features in action.
New feature: REDCap Messenger
- This communication platform is built directly into REDCap, allowing users to communicate easily, efficiently, and securely. REDCap Messenger is a chat application that supports one-on-one direct messages and group conversations, as well as project-linking, document and image sharing.
New feature: Custom Record Status Dashboards
- Users can build and save custom versions of the Record Status Dashboard to customize the dashboard to their liking.
- Custom dashboards have many configuration options. Users can give each dashboard a title and a description/instructions, and can choose the instruments to include or exclude in the dashboard’s display. Similar to building reports in REDCap, Custom Record Status Dashboards allow users to sort the records in the dashboard by another field’s value, and one can set filter logic to filter the records displayed in the dashboard to a specific subset of the total records (e.g. [age] > 30 and [diabetes] = “1”). There are aesthetic controls as well, such as being able to display the dashboard headers vertically, which will transpose them 90 degrees for a more compact display on the page.
- Only users with Project Setup/Design privileges may create custom dashboards. Once a custom dashboard has been created, it will be viewable and usable by all users in the project. Users may create as many custom dashboards as they like in a project. To create a custom dashboard, navigate to the Record Status Dashboard in a project, and click the blue “Create custom dashboard” button to get started.
New feature: Text searching and ordering on reports
- Users now have a search box displayed at the top of every report where they can type text to search the report, in which it will only show the rows in the currently viewed report that match the search string that is typed. Additionally, any column in a report can have its column header clicked to sort the table according to the values in that column (in ascending or descending order).
New feature: Response Limit for surveys
- Users may set a response limit for any given survey to prevent respondents from starting the survey once a set number of responses have been collected. This works well if you only intend to collect a specific number of responses for your survey, after which the survey will automatically shut down so that no new responses can be added. It can be set so that the response count included either completed responses only or both partial and completed responses. Users may also set custom text to be displayed to respondents on the survey page when the response limit has been reached. You can find this setting in the “Survey Access” section of the “Survey Settings” page on the Online Designer.
New Feature: Time Limit for Survey Completion
- Users may set the amount of time (in days, hours, and/or minutes) that each respondent has to complete a given survey based on when they were initially sent the survey invitation. Note: This feature excludes public survey links. This feature is sometimes call “Survey Link Expiration” because it allows you to expire a respondent’s individual survey link. This is often better than using the “Survey Expiration” feature, which expires the entire survey for all respondents, because the Survey Link Expiration option allows respondents to begin the survey at different times while still all having the same amount of time to complete the survey. When enabled, a new column is displayed on the Participant List where it denotes if a participant’s survey link has expired and also displays the expiration time if you hover over the icon. If the icon is clicked, the user can permanently override the link expiration time by setting it further in the future (to give the respondent more time), or else to expire the link sooner (or even immediately).
New Feature: Log out and open survey
- The survey options at the top of a data entry form now include a new option “Log out + Open survey”, which will simultaneously open the survey in a new browser tab while logging out the REDCap user in the current tab. This makes it easier for users to log out of their REDCap session in case they walk away from the computer while a participant takes the survey, thus ensuring that the participant is not able to go into the first tab and access the user’s REDCap account and projects.
New feature: Custom Event Labels
- Custom Event Labels can now be optionally added for any event in a longitudinal project when adding/editing events on the Define Events page. These custom labels can be used for piping data from a given event into the event’s table header on the Record Home Page (i.e., Event Grid). For example, if each event represents a single visit of a person, then if you are collecting the date in a field called ‘visit_date’ on each event, then you can set the Custom Event Label as ‘[visit_date]’ for all those visit events. This will provide useful context for each event when viewing all the events of the record. You can also get more advanced with the piping by using multiple fields and even static text. For example, ‘[visit_date], [weight] lbs’.
New feature: Data dictionary snapshot
- Users can now click a button on the Online Designer to create a snapshot of their instruments (i.e., CSV data dictionary) that gets stored on the Project Revision History page. Additionally, a data dictionary snapshot is also created automatically whenever a data dictionary is uploaded on the Data Dictionary Upload page.
New feature: Field name (variable) auto-suggest when typing branching logic, calculations, or general conditional logic
- (Survey Queue, Automated Survey Invitation, Data Quality rule, report filter’s advanced logic). While typing logic/calculations into the text box, it will auto-suggest a REDCap variable name from your project that is clickable to inject into the text box. If the project is longitudinal, it will also suggest event names to inject unique event names.
New feature: Real-time validator for branching logic, calculations, or general conditional logic
- (Survey Queue, Automated Survey Invitation) that allows you to run your logic/calculation on a specific record in the project, and it returns the result. For example, if typing branching logic in the Add/Edit Branching Logic popup in the Online Designer, you can select a record, and it will tell you if the field will be displayed or hidden for that record based upon the record’s currently saved values. When typing calculations, it will return the actually calculated value of the field for a selected record. This makes it easier to formulate your logic and calculations so that you get them right the first time.
New action tags:
- @PLACEHOLDER – Is used to specify a short hint that describes the expected value of a Text field or Notes field (e.g. a sample value or a short description of the expected format). The placeholder is displayed inside the field before a value is entered. The format must follow the pattern @PLACEHOLDER=’????’, in which the text to be displayed should be inside single or double quotes. This action tag is compatible with all browsers, including Internet Explorer 8 and 9.
Improvements and other Changes
- The Data Search feature on data entry forms can now be used to search data over all fields in the project (excluding multiple choice fields). This is now the default option, although users may still choose a specific field to further narrow down their search.
- PDF exports of instruments are now able to display inline BMP image attachments for Descriptive fields. In previous versions, it would simply omit the image in the resulting PDF file.
- When reviewing drafted changes in a production project: It now provides a “Compare” button for multiple choice fields that have a change in one or more choices. Clicking the button opens a popup with a table displaying each choice on a row and noting if the choice is Unchanged, Altered, Added, or Removed. Additionally, it also displays how many records have a saved value for the given choice. This will help when reviewing draft changes when in production status.
- It will now give a warning on the page if a user has initialized the project in the REDCap Mobile App. It will note that the changes being made *may* affect the app user’s ability to sync data back to the project and recommends that perhaps the app user should first sync all their data back to the server before the changes are committed.
- It now truncates any text (field labels, choices, etc.) in the table that is very long, and provides a “Show more” link if you wish to view the full text.
- If any fields are being deleted and those fields contain data, it will note how many records will be affected for each field deleted. Also, if fields are being added and those fields previously existed in the project, in which they had data saved or them but then the fields were deleted, then it will note how many records have orphaned data for those fields (because that data will be restored if the fields are re-added – this is sometimes undesirable).
- The User Access Dashboard now only shows projects with more than one user. Since it makes no sense to display projects in which the user is the only person with access to the project, those projects will no longer be displayed on the page since they are irrelevant for the purpose of the UAD.
- Slider fields can be displayed as vertical by setting their Custom Alignment to right-vertical (RV) or left-vertical (LV). Note: Any already-existing slider fields will automatically be converted to RH and LH alignment during the upgrade process if they previously had RV and LV alignment, respectively (this is because in previous versions there was no difference between the vertical and horizontal alignments for slider fields).
- The results displayed from executed rules on the Data Quality page now display the field label above the variable name and value. This provides better context for users who might not know the variable names.
- A PDF of record data for all instruments/events for a given record can now be downloaded from the “Choose action for record” drop-down on the Record Home Page if the user has Data Export privileges.
- A zip file containing all uploaded documents (or signature files) for an individual record can now be downloaded from the “Choose action for record” drop-down on the Record Home Page if the user has Data Export privileges.
- File Upload fields that are displayed on reports will no longer display the text “[document]”, but will instead provide a “Download” button so that the user can actually download the file from the report.
- Assigning a record to a Data Access Group (or unassigning/reassigning a record) is now performed on the Record Home page using the “Choose action for record” drop-down list rather than on the data entry form. The only exception for this is when a record is being created on a data entry form (when the record does not yet exist), in which it will allow the user to set the Data Access Group using the drop-down list at the top right of the form. This is so a record can be assigned to a DAG at the moment of its creation.
- For records that have been assigned to a Data Access Group, it will now display their Data Access Group assignment under the record name on the Record Home Page.
- REDCap’s base font is now Open Sans, and is slightly bigger in size, providing better readability. In previous versions, the base font was Arial.
- Changed the text “Matrix Header Text” to “Section Header Text” when adding/editing matrix fields in the Online Designer to reduce confusion between matrix headers and section headers.
- The “lock all forms” and “unlock all forms” links that appear near the bottom of the “Record Home Page” (formerly known as the “Event Grid”) in longitudinal projects have now been replaced with an “Actions” drop-down higher up on the page above the table of events. In this way, users can still perform the same actions as before but by choosing an option in the drop-down near the top rather than clicking the links that used to exist near the bottom.
- Renaming a record is now performed on the Record Home page using the “Choose action for record” drop-down list rather than on the first data entry form.
- The location of the “Design your data collection instruments” step and “Define your events” step (longitudinal projects only) on the Project Setup page will now remain in the same location on the page when in production status as they did when in development status. In previous versions, these two steps were moved to the bottom of the page. This change is to provide more consistency for where things are located during the entire development of a project.
- The method in which to delete an entire record has been changed. It is no longer done by clicking a button at the bottom of the data entry form, but rather it is done by selecting the Delete Record option in the record actions drop-down on the Record Home Page.
- The method in which to delete an entire event of a record has been changed (this applies to longitudinal projects only). It is no longer done by clicking a button at the bottom of the data entry form, but rather it is done by clicking the red X icons now displayed in the bottom row of the status table on the Record Home Page.
- If a user clicks the “Add new record” button on the “Add/Edit Records” page, then it will automatically take them to the data entry form (rather than the Record Home Page) if the project contains only one instrument (or if longitudinal, only contains one designated instrument for the selected arm). This reduces clicks for the user and thus saves time.
- The Data Dictionary Codebook now displays the unique form name next to the name of the instrument in the gray instrument header in the table.
- When editing the choices of a multiple choice field in the Online Designer, the auto-coding behavior is now slightly different when projects are in Development status when replacing the existing choices with brand new ones that do not have explicit coding. In previous versions, if existing choices were completely replaced with non-coded choices (i.e., just the choice labels), it would auto-code the new choices beginning with one number higher than the highest-numbered of the previously existing choices, whereas now (in development only) it will auto-code the choices to begin with “1” if all the choices are replaced. Note: This change is for development status only because it could have disastrous effects on data for projects in production when performing real data collection
- When copying a project that utilizes surveys and Automated Survey Invitations, any ASIs that are copied are now set to “Not Active” by default in the new project. A note was added regarding this on the Copy Project page. The reason for this change is because so many users would copy the project with records and begin testing the new project via data entry, which would mistakenly trigger the ASIs to send emails to real participants copied from the original project. So the change was made to prevent this undesirable situation from happening. So now when copying a project, all ASIs will need to be set as Active individually after the project is copied.
- In the “Main project settings” step on the Project Setup page in a project, the position of the two choices were swapped to bring survey functionality to the forefront.
- For security purposes, the hashing algorithm used for hashing the answer to password recovery questions (for Table-based authentication only) will be updated to a stronger algorithm. This will unfortunately cause all Table-based users (non-X.500 users) to have to set their password recovery question again the next time they log in to REDCap; however, it is anticipated that this will cause very little inconvenience to users.
- For longitudinal projects containing multiple arms, the Record Status Dashboard now displays each arm separately in a tabbed interface rather than trying to fit all arms in a single table, which typically is not the best way to view multiple arms of records.
- Checkbox fields on reports are now displayed better with their field label spanning all the choices as a row above all the choices and displaying just the choice text and variable in the individual choice column headers on the second row of the header. This groups the checkbox options together much better and is much more intuitive to read and interpret.
- Normal users are now allowed to enable (or modify) repeating instruments/event in a project while the project is in production. In previous versions, they could only do this while in development.
- When deleting a project while in production, if the project contains no records, it will delete the project immediately rather than sending a request to the REDCap Administrator to delete it. In previous versions, an Administrator would have to delete production projects regardless of whether the project contained records or not.
- When creating/editing reports in projects that have repeating instruments, a new option has been added to Step 3 (filtering): “Show data for all repeating instruments for each record returned?”. This option is very similar to the “Show data for all events for each record returned” option found when editing reports in longitudinal projects in which it applies record-level filtering as opposed to row-level filtering (“row” referring to the rows in the report table displayed). This new option provides greater precision for controlling filters used on data in repeating instruments. For example, if a filter references a field from a non-repeating instrument, then it might filter out all data from repeating instruments and thus not display them in the report, which could be confusing. But with this option checked, it will return all repeating instances (as separate rows) for any record that matches that filter. In this way, it allows you to apply the filter to non-repeating fields while still including fields from repeating instruments in your report. This was not possible in previous REDCap versions.
- The generic field validation error message (“The value you provided could not be validated because it does not follow the expected format. Please try again.”) has been improved, in which it now additionally displays “Required format:” and the name of the field validation (e.g., “Datetime (D-M-Y H:M)”) in the error prompt so that there is no ambiguity about what the format should be.
- If a record has any calendar events (including scheduled events) that will occur in the next 7 days, it will display a button above the table on the Record Home Page. The button will note how many calendar events there are for the current record in the 7 days, and when clicked, it will display the next 7 days’ worth of calendar events in agenda mode view.
- If a record has any survey invitations that are scheduled to be sent in the next 7 days, it will display a button above the table on the Record Home Page. The button will note how many upcoming invites are scheduled for the current record in the 7 days, and when clicked, it will display a table of the send time and survey title for the next 7 days’ worth of scheduled invites.
- When the Data Resolution Workflow module is enabled for a project, the Resolve Issues page now has an Export button to allow users to download the data resolution dashboard as a CSV file. The page also allows users to view “all status types” using the first filter drop-down in the dashboard table.
- The text describing the Project Notes field when creating a new project was modified slightly to inform the user that the notes are displayed on the My Projects page, which was not explained in prior versions.
- When opening the Field Comment Log, it now places the user’s cursor inside the text box automatically as a convenience to the user.
- When a user is on a data entry form or survey and hovers over the choice label of a radio button field, the cursor changes to the “hand” cursor to indicate that they can click on the label to select the choice rather than thinking they have to click the radio element itself.
- Invitation reminders are now displayed by default in the Survey Invitation Log. In previous versions, the “Display invitation reminders?” checkbox would have to be checked in order to see the reminders. Not initially seeing the reminders would cause some users to mistakenly assume that nothing was scheduled.
- Action Tags are now listed alphabetically by name in the “What are Action Tags?” popup on the Online Designer.
- When viewing a report that displays data from a repeating instrument or event, it will now gray out the cell of the redcap_repeat_instrument and redcap_repeat_instance columns for the base instance row of a record (i.e., where the redcap_repeat_instance field has a blank value), thus denoting that that field is not relevant for that row of data (since the row is displaying non-repeating data only).
- The Group ID number for each Data Access Group (DAG) is now displayed in the DAG table on the Data Access Groups page in a project. The Group ID number is the number that is automatically generated by REDCap and is automatically prepended with a dash/hyphen to the record name when a user assigned to a DAG is creating a new record. The Group ID number is now displayed in the table on the page so that users are aware of what each DAG’s Group ID number is.
- Question numbers displayed on surveys are now displayed as right-aligned, whereas in previous versions they were left-aligned. This is to reduce the gap between the question number and the question text for a more readable and intuitive display.
- If an individual project has been set as “offline” on the “Edit a Project’s Settings” page in the Control Center, it will note this in red letters on the My Projects page or Browse Projects page for the project.
- A count of the number of users is now displayed at the top of the user list table on the Project Home page.
- Better protection against accidentally overwriting survey responses when opening surveys from a data entry form. When clicking the “Open survey” option at the top of a data entry form, it will display a popup on the data entry form to inform the user that it is recommended that they leave the page without saving it in order to avoid overwriting or erasing the survey responses that had been collected in another browser tab on the survey page.
- Added “language” option for users submitting an instrument to the REDCap Shared Library so that they can specify the language of their instrument’s text. Note: Instruments in the Shared Library are now searchable by language.
- The cell borders were added back to the report table, Record Home Page table, and Record Status Dashboard table for better readability of the table contents.
- Added a note in the “Compose survey invitation” popup on the data entry form to make users aware that if they manually enter an email address into the “To” field for the survey invitation, it is a one-time use only and that any other invitations sent out at other times will instead go to the email address found in the Participant List for that participant. No functionality has changed regarding this, but some users were not aware of this behavior.
- When exporting data to Stata, it now uses syntax for newer versions of Stata. This also includes declaring datetimes more properly than in previous versions of REDCap.
- For better compatibility with Shibboleth authentication, the format of the Send-It download URL has been reverted to its pre-7.0 format. Note: The current format will also work in 7.3.1 and is backward compatible in case any Send-It files had been sent out just prior to upgrading to this version.
- On the Logging page in projects that have Data Access Groups, a user that is not assigned to a DAG will be able to filter the logging results by records in a DAG. Below the “Filter by record” drop-down at the top, it will display a “Filter by records in a DAG” drop-down that is viewable only by users not currently assigned to a DAG.
- On certain rare occasions, the table displayed on the Record Home Page, on the Record Status Dashboard, on the Designate Instruments For My Events page, and on all reports might not display properly but might have its columns or rows appear misaligned in some way, thus making it difficult to view the table or navigate it well. If this occurs, users can now disable the floating table headers for that table/page in that specific project (and have it remember that choice) by clicking the “Table not displaying properly?” link that is now displayed near the top right of the table. It will also have a [?] link to click, which opens a popup with an explanation of what it means to disable that functionality.
- Added a “Cancel” button to the bottom of the Data Dictionary Upload page and Data Import Tool to more easily allow users to start over when halfway through the upload process.
- The user auto-suggest on the User Rights page no longer returns suspended users when searching for users to add to the project.
- Alt text was added to the increase/decrease font images displayed at the top of the survey page.
- The password security questions for Table-based users have now had their language abstracted, so they are now translatable like other stock text in REDCap.
- The font size of the text fields for Link Label and Link URL on the “Set up project bookmarks” page was too small.
- On the API page in a project it no longer displays a list of all users in the project who have API tokens.
- To allow text boxes to expand flexibly, an “Expand” link was added below the “Send confirmation email” message box on the Survey Settings.
- The “Review Drafted Changes” page in a production project now gives a bigger warning if a user is attempting to change the Record ID field’s variable name after data collection has begun.
- When adding a secondary or tertiary email address to a REDCap user account, the language has been modified on the email verification page for greater clarity when the current logged-in user clicks the link and they are not the requester. This can happen sometimes when one user is authorizing another user to use their email address for their REDCap account’s secondary or tertiary email.
- When designating instruments for events on a longitudinal project’s “Designate Instruments for My Events” page, normal users will no longer be able to undesignated an instrument from an event if the project is in production (REDCap administrators will still be allowed to do this though). This is to protect users from mistakenly undesignating instruments after collecting data in production, which would orphan the data.
- The Data Search feature on the “Add/Edit Records” page performs slightly better regarding the ranking of search results returned, in which it now lists exact word matches first in the list of results. Additionally, the Data Search feature now returns a maximum of 25 matching values, whereas previous versions returned a maximum of 15.
- Modified the explanation text for @NOW and @TODAY action tags for greater clarity with regard to their usage.