REDCap Integration Overview

If you are using REDCap as your primary system to manage your study, you might benefit from the REDCap integration feature of MyDataHelps Designer. This can allow you to take advantage of various robust MyDataHelps features such as:

• Advanced scheduling
• Notifications
• Mobile friendly UI for your participants

All the survey responses still flow back into your REDCap instance, without you having to do any additional work to keep the two systems in sync.

Watch this quick video to learn how you can best leverage your existing projects and instruments in REDCap with MyDataHelps:

Entering your REDCap Credentials

The first step to connecting your MyDataHelps Designer project to your REDCap project is entering your REDCap API URL and token on your project’s REDCap Integration page. Once you've entered the URL and API Token, click "Connect" to initiate a connection from MyDataHelps Designer to your REDCap deployment.

Your REDCap API URL can be found in the REDCap API Playground page or you can ask your REDCap administrator for it.

Your REDCap API token can be copied directly from the REDCap API page.

The record ID field in your REDCap project must be called record_id or the integration will fail.

Enabling REDCap Instruments as MyDataHelps Surveys

After you’ve configured your instruments in REDCap, you may have a list similar to the below in REDCap:

Once you enter your REDCap API URL and token into your MyDataHelps Designer project’s REDCap Integration page and click “Connect”, you should see something like the below within MyDataHelps Designer:

If your REDCap instance is not publicly accessible, you may receive an error message when trying to connect. In this case, you will need to whitelist the CareEvolution IP address: 52.200.215.173. For additional information, contact your IT department to understand the process for getting connected and setting up an API. 

You can then click the toggle on the far right of each instrument row to import that instrument into MyDataHelps Designer. Doing so will automatically convert the entire REDCap instrument into a MyDataHelps Designer survey, including branching logic and multi-language settings.

When adding your instruments to MyDataHelps Designer, we look at the REDCap project definition xml, for example:
<FormDef OID="Form.sample_instrument" Name="Sample REDCap Instrument" Repeating="No" redcap:FormName="sample_redcap_instrument">
The FormName xml attribute becomes the survey's Name and the Name xml attribute becomes the survey's Display Name. REDCap doesn't allow you to change the FormName of instruments after moving your project to production; however, you can still update the Name, which will be visible to participants.

After you’ve enabled certain REDCap instruments, you can create schedules to deliver them to participants, provide links to them in notifications, or start them programmatically using the MyDataHelps SDK.

You can also click the “View” button after the “Enabled” toggle to see the surveys in the normal MyDataHelps Designer interface. Please note that this is mostly to ensure that everything looks good, that there are no validation errors, and that branching logic and multi-language settings appear correctly. You will not be able to save or publish these REDCap synced surveys, as the syncing process is completely automatic to make it easier to keep up with changes that might need to propagate from your REDCap deployment.

Branching Logic

Most types of branching logic from REDCap will convert successfully. Examples of supported branching logic include the following:

• [nachos] = '1'
• !([nachos] = '0')
• [msds_17_b(COPE_A_204)] = '1'
• [msds_10] = 'COPE_A_53' or [msds_10] = 'COPE_A_127' or [msds_10] = 'COPE_A_150'
• [basics_xx] >= 1
• [enrl_reinfacuteyn]="1" and [enrl_reinfdt] <> "" and [enrollment_fversion]>=2
• [nachos] = '1' and ([last]='2' or [last]='3')

There are some types of branching logic that MyDataHelps Designer cannot import at the moment. The main categories are branching logic that contains event names or formulas. Examples of unsupported branching logic include:

• [cons12_dt]<>"" and (datediff("10-01-2021", [cons12_dt], "d", true)<=0 or datediff([cons12_dt], "today", "d", true)<0) (contains datediff functions)
• ([visit_agree]="1" or [visit_override]<>"") and [visittype]="1" and [event-name]="baseline_arm_1" (contains event-name)
• [basics_xx] > 0 (unsupported operator >, use >= instead)

To verify that the branching logic imported correctly, we recommend clicking the “View” button next to an instrument, then going to a particular step and clicking the “Navigation” tab on the right panel to verify that what is displayed is accurate.

Multi-Language Settings

If your REDCap project has Multi-Language Management set up, enabling a REDCap instrument as a survey in MyDataHelps will import any available translations as well.

Below is what an example of a translated REDCap instrument might look like:

Enabling this instrument in MyDataHelps will appear as:

When a participant fills out a survey that has translations, MyDataHelps Designer will also populate the first field annotated with @LANGUAGE-CURRENT-SURVEY or @LANGUAGE-CURRENT-FORM when sending the results back to REDCap.

Refresh Instruments from REDCap

When you press the “Refresh from REDCap” button, the following occurs:

• REDCap is queried for your latest REDCap Project configuration, including your latest instrument definitions.
• Every REDCap instrument that is enabled in MyDataHelps Designer as part of the integration will be updated with the latest version from REDCap. Should any of these updates fail (for instance if an instrument contains unsupported branching logic), the entire operation will fail and everything will remain as the old version.
• If an enabled instrument is no longer part of the REDCap project, the corresponding survey will be deleted from MyDataHelps Designer. If the survey is currently used in a schedule, the deletion will fail and the entire refresh operation will fail as well.
• The list of instruments displayed in MyDataHelps Designer on the REDCap Integration page will be updated, showing new instruments that were added to REDCap and removing old instruments that are no longer there.

Disconnect from REDCap

When you press the “Disconnect” button, the following things occur:

• All enabled instruments will have the corresponding surveys in MyDataHelps Designer deleted. Similarly to the refresh case, if any of these surveys are used in schedules, the operation will fail.
• The REDCap API URL and token will be cleared.

Disconnecting the integration will not delete participant data out of MyDataHelps. See Excluding and Removing Participants for more information on how to delete participant data.

Data Flow

When a participant completes a REDCap linked survey in MyDataHelps, results will be stored in MyDataHelps and flow back in near instant time to your REDCap deployment and populate their REDCap record. Please make sure your REDCap production deployment is up and available to ensure that the data syncs in a timely fashion. If for some reason REDCap is down, we will attempt to sync the data at a later time, but prolonged REDCap instance unavailability could lead to missing data.

The MyDataHelps participant identifier will match the REDCap Record ID.

If your REDCap instrument is configured for multiple languages, the first field with an annotation of @LANGUAGE-CURRENT-SURVEY or @LANGUAGE-CURRENT-FORM will be populated with the language code for the participant’s survey.

If your REDCap instrument is repeating, upon completion, the persisted data will be sent to REDCap with the fields redcap_repeat_instrument and redcap_repeat_instance set to correctly identify it as repeating.

Copying a Project

When copying a project that has REDCap Integration enabled, all of the REDCap integration settings and enabled instruments and corresponding surveys will be copied as well. If you are copying your Dry Run project to your Production project in MyDataHelps Designer, you can then update your REDCap API URL and token to your production values, after which a “Refresh from REDCap” will pull in all of your configuration from your REDCap production system. At this point, your Dry Run REDCap project will be synced to your Dry Run MyDataHelps project and your Production REDCap project will be synced to your Production MyDataHelps project.