1 Introduction
2 Configure REDCap Server
3 Add REDCap Project
4 Mapping Participants and Visits
5 Advance Features
- 5.1 Records Inclusion Rule
- 5.2 Forms Exclusion List
- 5.3 Fields Exclusion/Inclusion List
6 Data Dictionary for Fields and Events Mapping
7 Integration Points
8 Adding more project
9 Mapping PVs from REDCap to corresponding PVs of OpenSpecimen
- 9.1 One-to-One Mapping
- 9.2 Many-to-One Mapping

Introduction

REDCap does not have fixed instruments for participants and visits. Therefore, you need to map the REDCap Instruments with OpenSpecimen Participant and Visit fields.

For mapping, the REDCap variables can be obtained from the ‘data dictionary’ available under ‘Project Home and Design’.

Configure REDCap Server

Before configuring the REDCap project to a specific Collection Protocol in OpenSpecimen, you must establish a link between your desired REDCap and OpenSpecimen servers. This will helps the OpenSpecimen to pull the data from the REDCap projects associated with the REDCap server using API tokens. Furthermore, once the server is configured, you can reuse the saved configuration multiple times for adding the projects. You can add the REDCap Server in the following steps:

Navigate to the required CP overview page.
On CP Overview Page and click on the 'Settings' tab on the left sidebar.
Select ‘REDCap Project Configuration' and click on the 'Add Project’ button.
Click on the ‘Add New’, provide details on server name, host base URL, plugin path, and time zone, and click on the ‘save’ button.

Data Dictionary for Server Configuration

Please note that the PHP plugin can be placed anywhere on the REDCap server as long as the PHP file is executable by the web server and the functioning of the plugin PHP is not compromised.

Field Name	Mandatory?	Description

Field Name	Mandatory?	Description
Server Name	Yes	Free text to enter a name for the REDCap server. For example, OpenSpecimen REDCap QA server
Host URL	Yes	The base URL for the REDCap server. For example, https://www.project-redcap.org
Plugin Path	No	The relative path for the PHP plugin installed on the REDCap server. To check all the plugins installed on the REDCap server, add ‘/plugins’ at the end of your REDCap base URL. For example, https://www.project-redcap.org /plugins
Time Zone	No	The timezone of the REDCap server.

Add REDCap Project

To add a new REDCap project to your desired collection protocol, you can follow the below steps:

Go to the CP Overview Page and click on the 'Settings' tab on the left sidebar.
Select ‘REDCap Project Configuration' and click on the 'Add Project’ button.
Provide information on the project name, server name, API token, site, PHI data, snapshot download page size, and users, and then click on 'Next'.

Data Dictionary for Project details

Field Name	Mandatory?	Description

Field Name	Mandatory?	Description
Name	Yes	Free text to enter a name for the REDCap Project. For example, Testing_RC
Server Name	Yes	Name for the REDCap server where your REDCap server is configured. For example, OpenSpecimen REDCap QA server
API Token	Yes	User-specific API token generated for the project. For example, A411D356AXYRC0C8A2742EBC366778HD
Site	No	The site linked with your collection protocol.
Save PHI Data	Yes	'Enable' or 'Disable' option to allow or prevent the collection of the participant's Personal Health Information (PHI). When you use the ''Save PHI data" option as Disabled, OS will not pull any RC field marked as 'Identifier' in the RC instrument/form set-up. Usually, these fields are 'First Name', 'Last Name', 'MRN', 'DOB', etc.
Snapshot Download Page Size	No	Specifies the maximum number of records that will be pulled from the REDCap at each interval. This is repeated ‘N' numbers of times until all records are pulled. It helps to minimize the overload to the OpenSpecimen server. For example, if there are 10,000 records in the REDCap project, and you have set the 'Snapshot Download Page Size' value to 5000, then OpenSpecimen will take two turns to pull all 10,000 records from the REDCap. The default value is '1000’.
Notify Users on Errors	No	Specify the users' names who will be notified of any error during the REDCap synchronization process.

Mapping Participants and Visits

Mapping can be done at two levels: Participant (Both classical and longitudinal studies) and Visit (Longitudinal study)

When you are adding a mapping for participant or visit fields, make sure there is no space between OS and RC field. If you introduce a space, the mapping will not be saved.

For example:

Correct mapping: rcRecordId=ppid

Incorrect mapping: rcRecordId = ppid

Participant Level Mapping

After adding the project details, you can move to the ‘Fields and Events Mapping’ page by clicking the Next button.
Map REDCap variables (on the left) obtained from the 'data dictionary' to OpenSpecimen (on the right) as shown below.

List of Participant Fields and Variables

Field Name	Variable Name

Field Name	Variable Name
PPID	ppid
Registration Date	registrationDate
External Subject ID	externalSubjectId
Registration Site	site
First Name	participant.firstName
Last Name	participant.lastName
Middle Name	participant.middleName
Birth Date	participant.birthDate
Death Date	participant.deathDate
Gender	participant.gender
Races	participant.races
Vital Status	participant.vitalStatus
Ethnicity	participant.ethnicities
eMPI	participant.empi
National ID / SSN	participant.uid
MRN Site	participant.pmis.siteName
MRN	participant.pmis.mrn
Custom field	participant.extensionDetail.attrsMap.<custom_field_name> For example: if the field name is 'redcap_age' in the custom form the use: participant.extensionDetail.attrsMap.redcap_age

Event and Visit Level Mapping

Like 'Participant Level Mapping', map visits fields for the REDCap project as shown below.
Additionally, you can map events for the REDCap project, as shown below.
Those events from REDCap which are not mapped can create unwanted, unplanned events in OpenSpecimen. To avoid this, click on the 'Ignore Unmapped Events’ checkbox as shown above in the red box.

List of Visit Fields and Variables

Mapping and auto-generating Labels

OpenSpecimen provides option to auto-generate labels. However, the PPID and visit name can also be synced from REDCap by mapping it in the configuration.

Advance Features

Records Inclusion Rule

Forms Exclusion List

Fields Exclusion/Inclusion List

Data Dictionary for Fields and Events Mapping

Integration Points

Adding more project

Mapping PVs from REDCap to corresponding PVs of OpenSpecimen

Ans: It is a very common problem faced by the integration of any two disparate systems. Let's say you want to map the gender value "M" received from the REDCap project to the corresponding OpenSpecimen PV "Male". In OpenSpecimen, you can do this by adding the property value to the dropdown of your choice, as shown below:

REDCap Configuration in OpenSpecimen