REDCap extensions are code customizations that exist independently of, but work in conjunction with, the official REDCap code base developed by Vanderbilt.  This allows developers (Consortium members and our internal staff) to easily make use of REDCap's core features (e.g., authentication, MySQL database access, PHP variables, constants, and functions) to provide additional features and functionality that are not available in REDCap. The extensions come in a couple of flavors, officially known in REDCap as plug-ins and hooks, and can be used in conjunction with each other.

Overview: Plug-ins & Hooks

Plug-ins & Hooks

How to add a plug-in to your project

After reviewing the supported plugin-specific information below, take the following steps to add the plug-in to your project

  1. Go to your project > Project Setup page
  2. In the 'Set up project bookmarks' section, click "Add or edit bookmarks"
  3. Enter a name for your link/feature in the Link Label column (suggested names included in plug-in description)
  4. Copy/paste the plug-in link into Link URL/Destination (link included in plug-in description)
  5. Link Type is Simple Link unless otherwise noted
  6. Select User Access as appropriate for your project
  7. Set Opens New WindowAppend record info to URL, and Append project ID to URL according to plug-in description
  8. Click the Add button under Link # (see image)

Set up Project Bookmarks9. Your Link Label will display under Project Bookmarks on the left hand side, under Applications (see image) 
10. Click on the hyperlink to engage the feature

Project Bookmark

Plug-in: Calendar Alert

Upon form submission, automatically populate the project calendar with specific events for dates entered by user via instrument

Developed & Shared by Dimitar Dimitrov (Partners HealthCare, ERIS)

Example Use Case:
You have a survey instrument with a date field on it. That date field is important in some way and once a date is chosen and the form submitted, you want the event associated with the date to appear on the project calendar. For example, a survey may ask: "When is your next appointment?", and the user fills in a date. When the survey is completed, the event entered by the user is placed in the REDCap project calendar for that date with a custom comment (if provided) by the administrator. This allows the project calendar to be automatically updated by a survey response.

Integration:
Suggested Link Label: Calendar Alert

URL: https://redcap.partners.org/redcap/plugins/calendar_trigger/index.php

Check Option(s): "Append project ID to URL"

 

Plug-in: Email Notification

Allows you to send a custom email alert based on your defined criteria. Based on REDCap DET (Data entry triggers) events

Developed & Shared by  Andy Martin (Stanford)

Example Use Case:
Suppose you want to send an email notification when a user responds to a survey question with a certain answer. With this plug-in, you can select the conditional logic for triggering the notification, the email recipient/message, and even trigger pre-post events.
 

Integration:
Suggested Link Label:  Email Notification

URL: https://redcap.partners.org/redcap/plugins/autonotify2/index.php

Check Option(s): "Append project ID to URL"

Plug-in: Print Forms to Customize Format

Displays an HTML view of project instrument in a format that can be copied/pasted into a Word document for easy reformatting

Developed & Shared by Sue Lowry (University of Minnesota)

Example Use Case:
This was created for a project where they did not want to use the built-in PDF forms because they wanted control over how it was formatted.

Integration:
Suggested Link Label: Print Forms to Customize in Word

URL: https://redcap.partners.org/redcap/plugins/print_forms.php

Check Option(s): "Append project ID to URL"

Plug-in: RPDR Data Import Assistant

A tool to allow users who have access to RPDR (Research Patient Data Registry) to more easily import that data into REDCap

Developed & Shared by Bob Gorczyca (Partners HealthCare, ERIS)

Example Use Case:
A researcher has obtained data from the Research Patient Data Registry (RPDR) and wants to more easily import that data into REDCap. currently, the following RPDR domains and their associated fields are supported:
    -Medical Record Numbers (EMPI & MRNs)
    -Contact
    -Demographics
    -Providers

Integration:
This plug-in is integrated by default, and available to all REDCap projects via the RPDR Data Import Assistant link in the Applications section of the left-side navigation. To use the plug-in, additional requirements apply.

Additional help:
Review the FAQ

Do you have RPDR or EPIC Integration Needs? We are gathering requirements for future initiatives. Please complete this survey to help guide our development.

Plug-in: Values-only PDF

Creates a PDF for the selected data collection instrument, using ONLY fields for which data exists

Developed & Shared by Adam Russell (Partners HealthCare, ERIS)

Example Use Case:
Only fields with data entered are included on the PDF; fields without data are not included. This is very helpful when there may be many blank fields in the report.

Integration:
Suggested Link Label: Values Only PDF

URL: https://redcap.partners.org/redcap/plugins/values_only_pdf/values_only_pdf.php

Check Option(s): "Append project ID to URL" and "Append record info to URL"

Plug-in: Longitudinal Report Builder

Create reports where data from different longitudinal events can be arranged to appear in one row per subject

Developed & Shared by ** Sue Lowry (University of Minnesota)

Example Use Case:

You are interested in building a report for a longitudinal REDCap project that generates one row per participant, rather than the standard multiple rows (events) for a single participant. Using this feature, you can select specific variables for a report from various events and arms. Additional functionality includes identifying dates from the event schedule. This module will assist with project management, but it is NOT intended to replace the Data Export module for these projects. You will still need to use that feature to download CSV files for use in statistical packages (SAS, STATA, R, SPSS, etc). Please note: the plugin will run slower on projects with numerous fields (>1000).

Integration:

Suggested Link Label: Longitudinal Report Builder

URL: https://redcap.partners.org/redcap/plugins/longitudinal_reports/index.php

Check Option(s): "Append project ID to URL"

Hook: Custom Action Tag - Hide Submit Button

Selectively hide the default "Submit button" on survey pages

Overview

One of REDCap's most useful features is its ability to distribute online surveys. The survey may consist of a single page or multiple pages. In order to navigate from one page to another, or at the end of a survey, REDCap embeds a "submit button" at the bottom of the survey. Depending on the survey's Question Display Format, this may include the "Next page" button, which both submits data and takes the user to the next page. For the purposes of this document, "submit" will refer to "next page" as well.

In some cases, the default submit button functionality is not what is desired, and the survey owner may want the user to take an action other than clicking the submit button. In such a case, there is currently no way to easily hide the submit button, and so its presence can be confusing to the end-user. This feature is designed to enable the survey owner to hide the submit button on specified survey pages.

This global hook utility presents the @HIDESUBMITBUTTON custom action tag, useful for surveys which display a Submit button. It can be added to an instrument's Field Annotation field for one or more REDCap instrument fields. If a field containing this action tag is visible on the survey page currently being displayed to the user in their browser, the "submit button", which is usually displayed by default, will be hidden. In particular, if the "submit button" is the only button in the HTML row, then the whole row containing the submit button will be hidden, so the user does not see an extraneous row at the bottom of the survey. Otherwise, only the button itself is hidden.

Note that the field containing the action tag MUST BE VISIBLE on the page in order for the functionality to be invoked. This is intentional, and is useful when the survey contains branching logic. For example, if you want the submit button to be hidden only when the survey is displaying a certain "branched" field, you would add the custom action tag to that branched field. If you want the submit button to always be hidden, then you would add it to a field that is always visible.

By default, when REDCap displays a survey page, it will display the submit button.  If you want the survey to hide the submit button by default, you can add an optional parameter to this action tag to do so - it needs to be present on ANY field on the displayed page, and is invoked ONLY when the page first loads. In particular, the @HIDESUBMITBUTTON action tag also takes an optional parameter of "default" (@HIDESUBMITBUTTON=default). If this parameter is present, then when the survey page is initially displayed, the "submit button" will be hidden whether or not the field containing the tag is visible.

There are several aspects to consider when creating the field containing the option list:

  • Create the REDCap's instrument field as you normally would. The instrument/form for which you want the submit button hidden must contain at least one field that has a Annotation Field.  
  • In the Field Annotation add the custom Action Tag "@HIDESUBMITBUTTON" (note the UPPERCASE) or "@HIDESUBMITBUTTON=default".  The action tag can be added to multiple fields in the same form, depending on the functionality desired.

Action Tag 

Contained in the Field Annotation field. A value of 'default', which hides the submit button on page load, is optional.
@HIDESUBMITBUTTON

Example

In this example, a single instrument has two fields; the first field is a multiple choice (Yes, No) field. The second field contains branching logic, and appears only if the user selects "Yes".

The desired functionality is that the Submit button only be displayed if the user selects "No".

To do this, you would simply add the following custom "action tag" into the Field Annotation field for the second field:

@HIDESUBMITBUTTON=default

Note that in this case, since the HIDESUBMITBUTTON action tag had the value of 'default' appended to it, the Submit button is hidden when the survey loads.

Survey when initially loaded (page viewed by end-user). Note the Submit button is hidden by default:

Survey Screen

Survey when "Yes" selected. The Submit button remains hidden, and a custom link is presented:

Survey Screen

 

Survey when "No" selected. The default Submit button is displayed:

Survey Screen

 

Other Notes

For survey's in which a "Next page" button also submits data, the action tag's functionality applies to the "Next page" button as well.

As always, test your survey thoroughly to ensure it has the desired behavior. In particular, if the Submit button is required to navigate to a page, or to submit results to the survey, ensure it IS visible at the appropriate times.

If you need additional functionality, contact edcsupport@partners.org.

Hook: Custom Action Tag - Image (Body) Map

Enable form input using an image map. Currently, only the human male and female body form image maps are supported

Overview

REDCap instruments are composed of "fields", which are composed of different types of data, such as section separators, check boxes, data entry fields, option lists, etc.  Sometimes a picture is worth a thousand words, however, and there is currently no capability in REDCap for a user to enter data by clicking on an image map.  

A common request is to enable such an option, particularly an image of a human body.  For example, a question might be, "Show on the body map all of the places where you feel pain" and clicking the appropriate areas on the body map can be a simple and effective means of communicating the information.

This hook utility is specifically designed to provide both human male and female (front/back) body maps, based on those used by CHOIR.  To support other images or for additional functionality, contact edcsupport@partners.org.

There are several aspects to consider when creating a field containing an image map: 

  • For each imagemap of interest, create a REDCap's instrument field as you normally would, selecting a field type of "Checkboxes (Multiple Answers)".
  • For each selectable section of the image map, create a checkbox "choice" and associated value, e.g., f36, Foot (top left)
  • In the image map's HTML code, for each above checkbox value, add a "data-key" to the associated <area> tag, and optional title tag. For example:

<area data-key="f36" title="Foot (top-left)" href="" shape="poly" coords="149,530,149,539,151,544,151,551,148,558,150,562,156,563,159,561,172,562,174,559,178,559" />

  • In the Field Annotation add the custom Action Tag "@IMAGEMAP=xx" (note the UPPERCASE) where "xx" is a tag that can uniquely identify the image map.

Note: At this time, the action tags and checkbox choices for this hook utility are pre-defined for use with only the BODY MAP.  Therefore, to use this hook utility, one should download the body map instrument zip file, and then upload it into their REDCap project.

Action Tag 

Contained in the Field Annotation field.  An alphanumeric value for xx, associated with a single image map, is required.
@IMAGEMAP=xx

Example

Depicted below is the bodymap after a user has selected various parts (in red). By selecting a part, the checkbox variable associated with the part is marked as "checked".

Body map

Other Notes

 This hook utility supports both data entry of records within REDCap as well as online surveys.

 If you need additional functionality, contact edcsupport@partners.org.

 

Hook: Custom Action Tag - Input Matrix

Configure a REDCap form so that data can be entered for multiple fields all in the same row, increasing organization and reducing scrolling

Overview

REDCap instruments are composed of "fields", which are composed of different types of data, such as section separators, check boxes, data entry fields, etc.  By default, when REDCap displays these fields in the browser, each field is displayed in its own row. If there are a lot of fields, the column which is displayed can get very long.

When displaying a lot of closely-related fields, it can be useful to display the fields in a table, or matrix, format. REDCap supports a "Matrix of Fields" type of field, which when viewed in the browser, displays the fields in a table format. However, this currently supports as "table cells" only check boxes and radio buttons.

A common request is to support displaying a table of input, or data entry, fields in a similar manner. This hook utility is designed to allow such a table to be created, using an arbitrary number of rows and columns (as REDCap is not yet "responsive" in its design, consider the width of the browser window when determining the number of columns to display.)  This hook utility does NOT use the "Matrix of Fields" infrastructure, but rather makes use of an instrument's "Descriptive Text" field and a custom "Action tag".

There are several aspects to consider when creating the instrument containing the table:

  • A Descriptive Text field is used to determine the layout of the table.  The Field Label is used to contain the HTML which encodes the layout of the table, headers, rows, and columns using basic HTML tags.  

Note: The HTML table tag MUST include a class attribute of "inputmatrix", e.g., <table class="input matrix">  

When the browser displays this instrument, this hook utility uses Javascript to read Descriptive Text field and display the actual data entry fields in the desired layout.

  • The cells within the table that are to be populated with data must contain text that is the same as the associated instrument field's variable value.  For example, if a table cell is to be associated with a data entry variable value of "color", then the table's <td> tag would be <td>color</td>
  • Lastly, the Field Annotation field must contain the custom Action Tag "@INPUTMATRIX" (note the UPPERCASE).

Action Tag 

Contained in the Field Annotation field.
@INPUTMATRIX

Example

For example, suppose you want your data entry form to have a table such as:

Data entry form

Sample HTML:

<table class='inputmatrix'>
<tr>
<th></th>
<th>Column1</th>
<th>Column2</th>
<th>Column3</th>
<th>Column4</th>
</tr>
<tr>
<th>Row1</th>
<td>row1_column1</td>
<td>row1_column2</td>
<td>row1_column3</td>
<td>row1_column4</td>
</tr>
</table>

To do this, you would first create a field in your data collection instrument in which the Field Annotation contains "@INPUTMATRIX" (no quotes).

The Field Label contains the HTML as shown in the sample HTML. Note that the table tag contains the required class attribute (shown in red).

Then for each associated table cell, you would add a data entry field (e.g., with a field type of "text box") with a variable name that matches the cell text (shown in green). The variable names shown are for clarity of example; you would choose whatever variable names are useful to your data collection.

There is, of course, no need for data entry fields which correspond to row and column headers. The headers are simply visuals helpers.

You may download a REDCap instrument containing a simple example or a complex example and upload into a project.

Other Notes

This hook utility supports both editing of records within REDCap as well as online surveys.

It is recommended that you keep this layout simple.

Only single-entry per field inputs are supported, specifically field types of "Text box", "Notes Box", "Drop-down List", and a single choice "Check Box". Although it may be possible to include certain other types of fields. these have not been tested.

If you need additional functionality, contact edcsupport@partners.org.

Hook: Custom Action Tag - None Of The Above

Enable a multi-select option in a data entry field to contain a mutually exclusive option, such as "None of the above"

Overview

REDCap instruments are composed of "fields", which are composed of different types of data, such as section separators, check boxes, data entry fields, option lists, etc.  One of the option lists is the Checkboxes field type, which supports multiple selections.  By default, when REDCap displays a checkbox list, any/all the options may be checked concurrently.  A common request is to enable one option, such as "None of the above", to prevent the concurrent selection of all other options.

This hook utility is designed to allow such a mutually exclusive option to be defined for checkboxes which have multiple choices.

There are several aspects to consider when creating the field containing the option list:

  • Create the REDCap's instrument field as you normally would, selecting a field type of "Checkboxes (Multiple Answers)".
  • In the Field Annotation add the custom Action Tag "@NONEOFTHEABOVE=xx" (note the UPPERCASE) where "xx" is the numerical value of the choice which you want to always remain mutually exclusive.

Action Tag 

Contained in the Field Annotation field. A numerical value for xx, associated with a single checkbox choice, is required.
@NONEOFTHEABOVE=xx

Example

Suppose in your data entry form you have configured multi-select checkbox choices:

1, Onion
2, Anchovy
3, Banana
4, Strawberry
98, None of the above

You want the user to be prevented from concurrently selecting both "None of the above" and any other field.

To do this, you would simply add the following custom "action tag" into the Field Annotation field:
@NONEOFTHEABOVE=98

Note that in this case, since the NONEOFTHEABOVE action tag had the value of '98' appended to it, the choice "None of the above" becomes mutually exclusive.

If a user attempts to select the mutually exclusive option and another option, then an "Incompatible Checkbox Selection" dialog will appear as shown, giving them the choice to either keep only the mutually exclusive option, or to uncheck it:

Incompatible Checkbox Selection

You may download the example REDCap instrument and upload it into a project.

Other Notes

This hook utility supports both editing of records within REDCap as well as online surveys.

If this custom action tag is added to a field AFTER records exist, it has no effect on those records.  If a pre-existing record is edited, the action tag will have no affect until it is invoked.

If you need additional functionality, contact edcsupport@partners.org.

Hook: Custom Action Tag - Random Option Order

Provide response options in a random order, so as to, for example not unduly influence user selections

Overview

REDCap instruments are composed of "fields", which are composed of different types of data, such as section separators, check boxes, data entry fields, option lists, etc.  By default, when REDCap displays an option list, the options are always displayed in a given oder - the order in which they were initially configured within REDCap.  Although in many cases maintaining this order is beneficial, in some instances it can cause a responder, e.g., a patient, to consider the order in weighing their decision.  To prevent the order from impacting a survey, it is a common request is that the order be randomized upon display.

In addition, although randomization of options may be required, there are often options, such as "Other", that make sense only when they are the last in the list.  Therefore there should be a way of enabling randomization while maintaining n option as the last in the list.

This hook utility is designed to allow such randomization to occur when displaying multi-choice radio buttons, checkboxes, and drop-downs that do not have the auto-complete feature enabled.

There are several aspects to consider when creating the field containing the option list:

  • Create the REDCap's instrument field as you normally would, selecting a field type of either "Multiple Choice - Radio Buttons" or "Checkboxes" or "Multiple Choice - Radio Buttons". To use this feature with Radio Buttons, this "Enable auto-complete for this drop-down" feature must NOT be enabled.
  • In the Field Annotation add the custom Action Tag "@RANDOMORDER" (note the UPPERCASE) or "@RANDOMORDER=xx" where "xx" is the numerical value of the choice which you want to always remain as the last in the displayed list.

Action Tag 

Contained in the Field Annotation field. A numerical value for xx, associated with the value to display last, is optional.
@RANDOMORDER=xx

Example

Suppose in your data entry form you have configured radio button choices:

1, Apples
2, Bananas
3, Cherries
4, Durian
5, Eggfruit
6, Fig
99, Other

You want this to appear to the user, when displayed in the browser, in some random way, such as:

Ο Durian

Ο Bananas

Ο Eggfruit

Ο Apples

Ο Cherries

Ο Fig

Ο Other

 

To do this, you would simply add the following custom "action tag" into the Field Annotation field:
@RANDOMORDER=99

Each time the page is visited, the order of the options is displayed randomly.

Note that in this case, since the RANDOMORDER action tag had the value of '99' appended to it, the choice "Other" always occurs as the last option in the list.

You may download the example instrument and upload it into a project.

Other Notes

This hook utility supports both editing of records within REDCap as well as online surveys.

If you need additional functionality, contact edcsupport@partners.org.

Hook: Custom Action Tag - Date Calculation

Automatically calculates a specific date or range of dates

Overview

Users may need to record a date that will occur at a specific point in the future. For example, a group may need to document a specific date will occur 20 days after the enrollment date. Or a user may need to record a range of dates that occured between 8 and 10 months before a subject's date of birth. This hook is designed to calculate a specific date or a range of dates, depending on a specific date already inputed by the user. 

This plugin is dependent on a date already entered by a user. It can be on the same form or on a previously entered form. 

  • Create the REDCap's instrument field 'Text Box (Short Text, Number, Date/Time...)
  • In the Field Annotation add the custom Action Tag "@DATECALC = {[user_date_previously_identified],XX,YY}" where XX is a numerical value and YY is the units (e.g., DAYS, WEEKS, MONTHS, YEARS; caps not needed). 
  • Examples
    • @DATECALC={[date_enrollment],60,DAYS} will calculate a specific date 60 days after the date of enrollment
    • @DATECALC={[date_of_birth],-9,MONTHS} will calculate a specific date 9 months before date of birth
    • @DATECALC={[diagnosis_date],8,DAYS,30,DAYS} will calculate a range of days after the diagnosis date Dec 01, 2012 - Dec 23, 2012
    • Validation can be Date, Datetime, or Datetime w/seconds but the format must align with that of the reference date (i.e., if date_of_birth is in m/d/y format, then the format of the calculation must also be in m/d/y).
    • When using this feature to calculate a range of dates, validation will not work. In this case, select none for validation. 

Action Tag 

Contained in the Field Annotation field. A numerical value for xx, associated with the value to display last, is optional.
@DATECALC={[date_field_already_inputed],xx,yy} where xx is a numerical value for amount of time and yy is the units (DAYS, WEEKS, MONTHS, YEARS), caps not needed

Other Notes

If you need additional functionality, contact edcsupport@partners.org.

Hook: Custom Action Tag – Must Equal

Specify an amount that a calculated field must equal to submit a survey

Overview

One REDCap field type is the calculated field. A common request is that surveys cannot be continued or submitted unless the calculated field is a specific value. This hook utility is designed to specify a number that the calculated field must equal in order to continue or submit a survey.

Create the calculated field as you normally would. In the Field Annotation add the custom Action Tag "@MUSTEQUAL=xx" (note the UPPERCASE) where "xx" is the numerical value of the result that the calculated field must equal before continuing.

Example:

  • A group only wants to recruit participants who are 25 years old
  • In the field [dob], a participant would enter his/her date of birth
  • The age calculation for the participant for today would be:
  • round(datediff([dob],"today","y","mdy",true),0)
  • In the calculated field, the action tag can be written as @MUSTEQUAL = 25
  • Only participants whose age calculation results in 25 would be able to continue to the next page or submit their survey

ACTION TAG 

Contained in the Field Annotation field. A numerical value for xx, would be required.

@MUSTEQUAL=xx

Please send a request to edcsupport@partners.org to enable the module on your project

Hook: Custom Action Tag – Randomize

Display a specific group of fields to be presented in a random order.

OVERVIEW

A common request is that a group of survey fields are to be presented in a random order. This hook utility is designed to specify a group of fields to be presented in a random order.

Create REDCap fields as you normally would. In the Field Annotation add the custom Action Tag "@RANDOMIZE=xxx” (note the UPPERCASE) where "xx" is a user defined name for the group of fields that the study team wants to randomize. If there is a second group of fields to be randomized, the group names would have to be distinct from the first group.

Example:

  • There are two groups of fields that a group will present to survey participants in random order
  • The first group will include action tags @RANDOMIZE = group1
  • The second group will include action tags @RANDOMIZE = group2
  • The result will show the two groups of fields presented in a random order each time a survey is accessed

ACTION TAG 

  • Contained in the Field Annotation field. A name for the groups (xx) should be specified.
    @RANDOMIZE = xx

Please send a request to edcsupport@partners.org to enable the module on your project

Hook: Custom Action Tag – Slidermax

Specify a maximum bound number for a slider field

OVERVIEW

One field in REDCap is the ‘slider/visual analog scale’ and the upper bound is defaulted to 100. A hook has been designed to customize the upper bound to a specific number.

Create a REDCap slider/visual analog scale’ as you normally would. In the Field Annotation add the custom Action Tag "@SLIDERMAX=xxx” (note the UPPERCASE) where "xx" is a positive number set for the upper bound of the input. For example, if @SLIDERMAX=25, then the maximum number that can be specified will be 25. The number can also exceed 100.

Example:

  • Create a slider scale and toggle ‘Display number value (0-100)?’
  • In the field annotation, include @SLIDERMAX = 60
  • During data entry, the upper limit will be 60

ACTION TAG 

  • Contained in the Field Annotation field. A numeric value for the upper bound of the slider should be specified for xx.

@SLIDERMAX = xx

Not supported on repeated instances.

Please send a request to edcsupport@partners.org to enable the module on your project