Clinical Data Interoperability Services

REDCap can communicate with any EHR (electronic health record system) that has implemented 'SMART on FHIR' web services that allow for interoperability and data extraction from the EHR. In this way, REDCap can be embedded inside and launched within an EHR user interface (e.g., Cerner, Epic Hyperspace), which allows REDCap users to easily add patients to their projects and/or to access patient data inside a REDCap project. In addition to launching REDCap inside the EHR, REDCap can also extract data from the EHR to import clinical data into a REDCap project by using a feature called 'Clinical Data Pull' (CDP). CDP provides an adjudication process whereby REDCap users can approve all incoming data from the EHR before the data is officially saved in their REDCap project. Another feature is called 'Clinical Data Mart' and works differently than CDP in that Data Mart can pull patient information in bulk while CDP pulls patient information from the EHR just one patient at a time. To learn their differences and strengths, see the sections below for documentation.

Before 'Clinical Data Interoperability Services' can be used by REDCap users, it must first be set up and enabled on this page. To get started, download the ZIP file linked below, and follow the instructions contained therein. There may be instructions for your particular EHR, but if not, then you may use the 'Instructions - General' file. After you have followed the setup procedures, the REDCap user may begin using the Clinical Data Mart and Clinical Data Pull in REDCap. While the Data Mart can only be used on the REDCap side, CDP can optionally be used either inside the EHR user interface or from the REDCap side (without being inside the EHR).

Services To Enable:
Clinical Data Pull
The Clinical Data Pull (CDP) is a feature for importing data into REDCap from an EHR. It provides an adjudication process whereby REDCap users can approve all incoming data from the source system before it is officially saved in their REDCap project.
Once Clinical Data Pull is enabled for the system, it can then be enabled for a given project by an Administrator on the project's Project Setup page (in the 'optional modules and customizations' section). Also, users that launch REDCap from inside the EHR system will be able to access their Clinical Data Pull projects from the EHR interface.
Clinical Data Mart
Once the Clinical Data Interoperability Services have been enabled for the system via the setup below, the Clinical Data Mart feature can be enabled so that privileged users may create projects with pre-defined instruments to allow for the fetching of clinial data for many medical records at once from the EHR. When enabled, this will appear as an option on the Create New Project page and then afterward as a page on the project's left-hand menu.
NOTE: Before users can utilize the Data Mart feature, a REDCap administrator must go into their user account on the Browse Users page and enable it on their account. Additionally, a user will not be able to utilize this feature until the user has first logged into REDCap from inside the EHR user interface, which is required before using any Clinical Data Pull functionality.
Key differences between Clinical Data Pull (CDP) and Clinical Data Mart (CDM)
Clinical Data Pull
Clinical Data Mart
Most common uses
  • Real-time data collection
  • Prospective clinical studies/trials
  • Longitudinal and/or multi-arm studies
  • Registries
  • Prospective or retrospective clinical studies/trials
  • Searching for specific lab values or diagnosis codes for a cohort of patients over a set time period
Data mapping to EHR fields
  • Field mapping must be set up prior to data pull by a user with CDP Setup/Mapping privileges in the project. This is completed via the CDP mapping page (accessed via the Project Setup page).
  • Mapping can be adjusted at any time in a CDP project, and it can be complex when mapping EHR fields to REDCap fields (allows for one-to-many, many-to-one, or many-to-many mapping).
  • Temporal data (e.g., vital signs and labs) must have an accompanying date or date/time field (e.g., visit date) for determining the window of time in which to pull data (using the ± day offset). Temporal data can be mapped to fields in a classic project, to events in a longitudinal project, or to repeating instruments/events.
  • All values for Allergies, Medications, and Problem List will be merged together for each category and each saved in its own a Notes/Paragraph field (if mapped).
  • Mapping is not required since the project structure/instruments are pre-defined when the project is created. Demographics is created as a single data collection form, and the following forms are created as repeating instruments: Vital Signs, Labs, Allergies, Medications, and Problem List. Each data value on the repeating instruments are represented as a separate repeating instance of the form.
  • User defines the data pull configuration when creating the project - e.g., chooses specific MRNs, date range, and data fields from the EHR.
  • Project-level settings control whether or not users in the project can 1) fetch data just one time or as often as they wish, 2) modify the data pull configuration or not and 3) if new data is pulled automatically with a cron job once a day. These settings may be changed only by a REDCap administrator.
Activation process
  • The local institution may have a formal process to evaluate the users/project prior to approval (recommended) - e.g., check IRB status, check users' EHR access.
  • REDCap administrator must enable CDP for the project on the project's Project Setup page.
  • The local institution may have a formal process to evaluate the users/project prior to approval (recommended) - e.g., check IRB status, check users' EHR access.
  • Project is first created by a user, but each revision of the data pull configuration will go through an audit process and approved by a REDCap administrator via the To-Do List (if the project-level setting has been enabled to allow configuration changes).
User privileges
  • Project users can set up field mapping and adjudicate data from the EHR if they have project-level rights to do so. In order to adjudicate data from the EHR, users must have access to the EHR and must have launched at least one patient in the REDCap window inside the EHR user interface.
  • REDCap administrator and team can optionally create a User Access Web Service to further control user access during adjudication (info documented on this page).
  • A user's REDCap account must be given Data Mart privileges by a REDCap administrator on the Browse Users page in the Control Center, after which the user will be able to create a Data Mart project and pull EHR data. (Note: This is not a project-level user right but a REDCap user account privilege.) Also, there is no optional User Access Web Service as there is with CDP to further control user access for pulling data.
  • In order to pull data from the EHR, users must have access to the EHR and must have launched at least one patient in the REDCap window inside the EHR user interface.
  • Users with Project Setup/Design rights in a Data Mart project will be able to request changes to the data pull configuration (if needed and if the project-level setting has been enabled).
Usage
  • Users must launch a patient in the REDCap window inside the EHR user interface, and will be able to add the patient to any CDP-enabled REDCap project to which they have access. Once the patient is in a project, the user can manually pull data from the EHR for the patient.
  • Data pulled from the EHR is not saved immediately in the project but is stored temporarily in a cache, in which users must first review/adjudicate all data values before being saved in the project.
  • Once a patient has been added to a project, CDP will automatically (via a cron job) continue to look for any new data added to the EHR for up to X days, in which X is the value of the setting "Time of inactivity after which REDCap will stop checking for new data" (info documented on this page).
  • Data Mart will pull data from the EHR when a user with appropriate privileges clicks the "Fetch clinical data" button. Also a cron job may be set from the Project-level settings control to pull any new data once a day automatically.
  • To pull new data values in the EHR, a user must manually click the Fetch button again (assuming the project-level setting is enabled to allow more than one data pull).
  • Extra instruments or events may be added to the Data Mart Project, but if any of the pre-defined fields or instruments are modified, it may prevent the data pull from working successfully thereafter.
Custom name for the EHR system
This will be the name of the EHR system as it is displayed for the user. If left blank, it will simply say 'EHR' in its place.

e.g., Epic, Cerner, EMR, EDW
Redirect URL (to add to your FHIR app/client for REDCap)
Copy and paste the Redirect URL below and provide it to your EHR technical team to be added to your FHIR app/client.
Redirect URL (read-only):
Clinical Data Pull "Instant Adjudication" option
This option allows users to enable the Instant Adjudication feature for all CDP-enabled projects. Once enabled here for the whole system, this setting can be enabled on the CDP project's field mapping page, after which it will allow users to bypass the normal data adjudication process and will let them import and save all data into the project that has already been cached from the EHR system. This can save a great deal of time when importing lots of patient records. After Instant Adjudication is enabled in a CDP project, users with CDP-adjudication privileges will see the button to initiate this process on the Record Status Dashboard. After the button is clicked, it will begin adjudicating the EHR data for all records in real time.
Enable Instant Adjudication for all CDP projects?
EHR-specific and FHIR-specific settings
Client ID and Client Secret for the FHIR app/client created for REDCap in the EHR
These are essentially a username and API key that REDCap will use to communicate with your EHR using the SMART on FHIR services. These client values will likely need to be generated for you by your EHR's technical team.
Client ID:
Client Secret:   Show secret
(Make sure that the Client Secret is the secret value itself and not the stored hashed value of the secret.)
Authorization type for obtaining FHIR access tokens
By default, REDCap users can establish a REDCap connection to the EHR using an 'EHR Launch' via the embedded REDCap page inside the EHR interface. Additionally, other options can be enabled to allow REDCap users to log in to the EHR from inside REDCap to establish connection to the EHR. Once the connection has been established to the EHR, users may begin to import clinical data into REDCap.
The Client Credentials Authorization flow uses system-level access credentials to interface with the EHR when peforming authorization and fetching FHIR tokens. However, the Standard Authorization Flow requires a user-level EHR login to establish connection to the EHR. If using Epic or Cerner, the Standard Authorization Flow is recommended.
FHIR web service URLs
The base URL endpoint should have been provided to you by your EHR's technical team.
NOTE: The URL will not end with /metadata but typically similar to /FHIR/DSTU2/.
FHIR Base URL:
The token and authorize URLs can often be found using the base URL you have provided above and then by clicking the 'Auto-find' button below. If the Auto-find method is not successful, then the Token URL and Authorize URL below will need to be provided to you by your EHR's technical team.  
FHIR Token URL:
FHIR Authorize URL:
Identity provider (optional)
The identity provider is used in the OAuth2 authorization process to identify the server that will exchange the FHIR access token with REDCap.
Set this parameter only if the real FHIR base URL of your EHR system is different from the one specified in this page (e.g., your EHR system is behind a proxy). More information about the launch sequence can be found here.
EHR's patient identifier string for medical record numbers (optional)
Most EHRs will not use medical record number as the back-end naming convention of patients, so in that case, you must provide a system identifier that REDCap will use to retrieve each patient's MRN from a FHIR data bundle.

e.g., urn:oid:1.2.840.114350.1.13.478.3.7.5.737384.14
e.g., urn:oid:1.1.1.1.1.1
Note for Epic customers: This is the HL7 Root item in the Epic ID Type Record (IIT) specified in the Patient ID Type field of the Integration Configuration Record (FDI).
"Break-the-Glass" feature (for Epic only)
Break-the-Glass (which draws its name from breaking the glass to pull a fire alarm) refers to a quick means for a person who does not have access privileges to certain information to gain access when necessary.

In Epic, the Break-the-Glass procedure is used to control and monitor access to sensitive data.
Break-the-Glass
Once Break-the-Glass is enabled for the system, the user will not be required to login into Hyperspace to break the glass for a patient. All Break-the-Glass requests are logged both in REDCap and in Epic.
Access token: Break-the-Glass will use an authentication mechanism based on OAuth2 access tokens and the standard FHIR endpoints base URL
Username token: Break-the-Glass will use a Non-OAuth2 authentication mechanism and REST endpoints (non FHIR)
EHR User type
The type of the EHR user that REDCap has mapped to the current user in the EHR launch process
The type of user used in Epic - typically "SystemLogin"
Patient ID type
The type of patient ID sent in the "accept" request
Typically "MRN"
Department ID type
The type of department ID sent in the "accept" request
Defaults to Internal
Username Token Base URL
Base URL that will be used when the username token authorization flow is selected (non-OAUth2)

User type for username token
Epic supports username tokens for three different types of users:
EMP: This is a user record created within Epic's database. You would work with an organization's Epic user security team to have a username and password provided to you.
Local: This is a username and password that is local to the web server. You would work with an organization's Client Systems team to have this username and password provided to you.
Windows: This is a username and password associated with an Active Directory account. You would work with an organization's Windows team to have this username and password provided to you.
Token credentials
Username tokens are used for authenticating server-to-server web service requests. This authentication works by provisioning a username and password that your application will provide to the web server to authenticate every request
Username:
Password: Show password
Other settings
URL for User Access Web Service (optional)
A valid web address (URL) that is reachable by the REDCap web server. NOTE: This is *not* a FHIR web service but an independent web service created by your institution for the purpose of validating if REDCap users have access to your EHR system.

REDCap will make requests to this web address when validating if the current user has proper authorization for adjudicating data and/or accessing data from the source system. This web service will only be called once per project per session. If the user is determined by the service not to have access, then they will be given an error message if they attempt to adjudicate any data from the source system. Note: This service is only optional for extra security.
* See the technical documentation PDF for details on this web service
Custom text specific to your institution to display to users
This text will be displayed at the top of CDP's informational popup window. Your text should describe your institution's process and/or procedures that are required in order for CDP to be enabled for a project or user. It may include a link to a survey or request form for collecting requests from users who wish to use CDP.
Expand 
HTML may be used in order to adjust the style of the text or to display links, images, etc.
If left blank, then it will display the following text to the user:
"To utilize the Clinical Data Pull (CDP) for a REDCap project, please contact your REDCap administrator regarding the process entailed and procedures required in order to have the CDP enabled for the project and also for an individual to be given authorization to use the CDP."
Display information about CDP on Project Setup page in a project?
If 'No' is selected, then CDP will not be advertised to users on the Project Setup page, and all information about CDP will never be displayed anywhere in a project. Setting it to 'No' is preferable if you wish to make CDP known to only a limited number of users without advertising it to all users.
Allow normal users to grant CDP user privileges to other users in a project?
NOTE: If the 'User Access Web Service' is not defined above, then it is HIGHLY recommended that this option be set to 'No' for security purposes if the data from the source system is considered sensitive or confidential in nature.
Setting it to 'No' will allow only Administrators to grant users CDP privileges on the User Rights page in a project. Typically, 'Yes' will be selected if you are utilizing the User Access Web Service, which will automatically restrict users from accessing data from the external source system from within REDCap if the web service notes that they should not have access.
Time interval that REDCap will check the source system for new data for individual records Every hours (min: 1, max: 999)
Records in CDP-enabled projects will be checked for new data from the external source system at this regular interval of time, in which the exact time of the data fetch is determined from the time of the last data fetch for a given record. This automatic data fetching will be performed by a cron job running in the background.
Time of inactivity after which REDCap will stop checking for new data from the source system
(for projects and individual records)
days (min: 1, max: 100)
If a CDP-enabled project has not had any logged activity in this amount of time, then no records in the project will be automatically checked in the source system at the regular interval above. Also, if a specific record within an active CDP-enabled project has not had its data modified in this amount of time, then it will not be automatically checked in the source system at the regular interval above.
Convert source system timestamps from GMT to local server time?
If the source system has temporal data with dates/datetimes of service that are being output in Greenwich Mean Time (GMT), setting this to 'Yes' will automatically correct all associated timestamps so that they appear in local time in the adjudication popup.
Note: You should only set this to 'Yes' if you can absolutely verify that the timestamps associated with incoming data values are in GMT time instead of in local time. Also, if this is turned on after some data is pulled into a project from the external system, it will not retroactively fix any of their timestamps but will instead only have an effect on new data imported after the fact.
Allow the patient's email address to be imported from the EHR?
For privacy reasons, you might wish to exclude the 'email address' field so that REDCap users cannot import a patient's email address from the EHR. If 'No' is selected, the email option will not appear in the EHR source field list when choosing which clinical data fields to import. Enabling this setting will make the email option visible to all CDIS services (Clinical Data Pull, Clinical Data Mart). This setting must also be enabled at project level on the 'Edit project settings' page.
CA certificates
To interact with FHIR resources, REDCap must be able to verify the identity of the EHR system using a bundle of CA (certificate authority) certificates. A digital certificate certifies the ownership of a public key by the named subject of the certificate. You can choose wheter to use the bundle of CA certificates included in REDCap or use the system provided by your webserver.