1 Steps to map participant/visit fields:
- 1.1 List of Participant Fields and Variables
- 1.2 List of Visit Fields and Variables
2 Event Mapping
3 Mapping and auto-generating Labels
4 Mapping PVs from REDCap to corresponding PVs of OpenSpecimen
- 4.1 One-to-One Mapping
  - 4.1.1 Mapping Specific CP
  - 4.1.2 Mapping for all CPs under a single site
  - 4.1.3 Mapping all REDCap projects irrespective of sites or CP
- 4.2 Many-to-One Mapping

Steps to map participant/visit fields:

Users can map the REDCap fields like gender, date of birth, visit date, etc, to the default/custom fields of OpenSpecimen. This can be achieved by the steps below:

Navigate to the required CP overview page → Click on the 'Settings' → Select ‘REDCap Project Configuration' -> click on the 'Add Project’ button.
Add the project details → Next
In the 'Fields and Events Mapping' page, add the respective mapping in the sections below:

Syntax to map participants/visit fields

redcap_variable=openspecimen_variable
When you are adding a mapping for participant or visit fields, make sure there is no space between OS and RC field. For example:
1. Correct mapping: rcRecordId=ppid
2. Incorrect mapping: rcRecordId = ppid

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
Email Address (v10.3)	participant.`emailAddress`
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

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
Visit 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

Event Mapping

In longitudinal projects, REDCap events can be mapped to OpenSpecimen events so that visits are automatically pulled during the sync process.

While configuring the REDCap project, navigate to the Fields and Mapping page. In the Events Mapping section, you can map REDCap events to the corresponding OpenSpecimen events.

Ignore Unmapped Events: REDCap events that are not mapped can create unwanted or unplanned events in OpenSpecimen. To prevent this, select the Ignore Unmapped Events checkbox, as highlighted in the image above.

Mapping and auto-generating Labels

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

When the label format is not configured on the OS:

Users need to provide the mapping for the visit/participant. For example, rcRecordId=ppid.

When the format is configured in OS:

Since the label is being generated by the OS, users do not need to add the mapping for it.
However, for participants, OpenSpecimen needs a one-to-one link for the participant record. In such a scenario, you need to add mapping for at least 1 participant identifier such as eMPI or MRN or External ID.

Mapping PVs from REDCap to corresponding PVs of OpenSpecimen

It is a very common problem faced in 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:

One-to-One Mapping

Let's say you want to map the gender value "Other" received from the REDCap project to the corresponding OpenSpecimen PV "Non-Binary". To do so, you can follow the given steps:

Navigate to Extras -> Dropdown Manager → Gender attribute -> Click on 'Non-Binary' dropdown value → 'Edit.'
Under properties, enter the name of the PV Mapping Key and its corresponding value for your REDCap study.

Mapping Specific CP

The property name is the same as the "PV Mapping Key" displayed on the OS-RC configuration page.

Name: Add the detail from 'PV Mapping Key' from the REDCap configuration CP setting.

Value: Value of REDCap

Mapping for all CPs under a single site

The property name is RC_<site_id>. The site ID can be obtained from the site list view in the following steps:

Go to the 'site' page -> select the sites you are interested in.
Click on the 'Export' button to download the .csv file.
Open the file, and you can see the 'site id' as 'identifier'.

Mapping all REDCap projects irrespective of sites or CP

The property name is RC, as illustrated in the image below.

Many-to-One Mapping

It is possible to map multiple PVs from REDCap to one PV on OpenSpecimen using caret (^) as the delimiter. For example, you want to map multiple gender values received
from the REDCap (M, Male, and Ma) to one corresponding OpenSpecimen PV "Male".