1 Introduction
2 Configure REDCap Server
3 Add REDCap Project
4 Mapping Participants and Visits
- 4.1 Participant Level Mapping
- 4.2 Event and Visit Level Mapping
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).
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)

Participant Level Mapping

After adding the project, 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

Fields Name	Variable Name

Fields Name	Variable Name
Visit Name	name
Event Label	eventLabel
Visit Date	visitDate
Clinical Diagnosis	clinicalDiagnoses
Visit Site	site
Clinical Status	clinicalStatus
Path. Report Number	surgicalPathologyNumber
Cohort	cohort
Comments	comments
Collection Status	status
Custom Field	extensionDetail.attrsMap.<custom_field_name> For example: if the field name is 'visit_number' in the custom form the use: extensionDetail.attrsMap.visit_number

Advance Features

Add the list of forms/fields separated by comma, tab, or newline.

Records Inclusion Rule

The user can define certain conditions to synchronize specific REDCap records to OpenSpecimen. Once applied, the system will ignore all other records that don’t satisfy the criteria irrespective of being mapped to the participant or visit field.
The expression is formed using REDCap variables obtained from the 'data dictionary'.
The example shown below will only fetch the records of female participants who are 18 years or older from REDCap.
The example show below will only fetch the records where the eligibility has value either ‘eligible, needs scheduled' or 'eligible, scheduled’.
This example show below will only fetch those records who have value in their mrn field

Forms Exclusion List

Users don’t have to specify list of forms that need to be pulled in OpenSpecimen. The forms except the ones mentioned in the exclusion list will be pulled in OpenSpecimen. If no form is added in the exclusion list, all the forms for that project will be pulled in OpenSpecimen.

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: