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.
The REDCap variables can be obtained from the ‘data dictionary’ available under ‘Project Home and Design’.
Add REDCap Server
<what is this step, why is this needed?>
Click on the ‘Add New’, provide details on server name, host base URL, plugin path, and time zone, and click on the ‘save’ button.
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 webserver and the functioning of the plugin PHP is not compromised.
Field Name | Description |
|---|---|
Server Name | Free text to enter a name for the REDCap server |
Host URL | The base URL for the REDCap server |
Plugin Path | The relative path for the PHP plugin installed on the REDCap server. |
Time Zone | The timezone of the REDCap server. |
Add new Study
To link the REDCap Project with the OpenSpecimen Collection Protocol:
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.
Add the name of your choice, appropriate server, API token generated for the project, and default site for CP. You can save the PHI data to the OpenSpecimen by selecting the ‘Enabled’ option for ‘Save PHI Date'. Furthermore, you can also add users to notify them about the errors that occurred during synchronization.
‘Snapshot Download Page Size’ specifies the maximum number of records that will be fetched for the REDCap server 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. The default value for it is '1000’.
Mapping Participants and Visits
Mapping can be done at two levels: Participant and Visit (for Longitudinal Studies).
Participant Level Mapping
The participant matching is done based on the following attributes:
eMPI
MRN (site + MRN)
UID (SSN).
If a match is found, then that participant is used for registration and update purposes. Otherwise, a new participant is created for registration.
Please note - The REDCap connector/plugin doesn’t use last name + DOB combination for matching as this requires users’ involvement or confirmation before using the resulting matches. The user’s involvement is ruled out because the synchronization is done automatically at scheduled times.
The steps for mapping the participant fields are as follow:
Add the list of RC-OS variable pairs separated by comma, tab, or newline.
After configuring study level mapping, you can move to the ‘Fields and Events Mapping’ page by clicking on the 'Next button.
Map REDCap variables (on the right) obtained from the 'data dictionary' to OpenSpecimen (on the left) as shown below.
List of Participant Fields and Variables
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.ST2 |
Event and Visit Level Mapping
It is exclusively for longitudinal studies.
Like 'Participant Level Mapping', map visits fields for the REDCap project as shown below in the red box.
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.
List of Visit Fields and Variables
Fields Name | Variable 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 |
Advance Features
Add the list of forms/fields separated by comma, tab or newline.
Records Inclusion Rule
The user can define certain conditions (as shown below in the red box) 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 as shown above.
The example shown in the red box below will only fetch the records of female participants from REDCap who are 18 years old or older.
Forms Exclusion List
The user can define the list of forms to exclude for synchronization irrespective of being mapped to participant or visit field.
If the user provides the list to the ‘Forms Exclusion list’ text box, then all the forms will be synchronized except the forms mentioned on the list.
Fields Exclusion/Inclusion List
Like ‘Forms Exclusion List’, the user can also define the list of fields to either include or exclude for synchronization.
If the user provides the list to the ‘Field Exclusion list’ text box, then all the fields will be synchronized except the fields mentioned on the list. On the other hand, only specified fields will be synchronized if the user provides the list to the ‘Field Inclusion list’.
Integration Points
REDCap | OpenSpecimen | Description |
|---|---|---|
Project | Collection Protocol | The RC project can be synchronized with a particular CP in OS. |
Instruments/Forms | Forms | The instruments from RC can be synchronized with forms linked with a particular CP in OS. |
Records | Participant | The records from RC can be synchronized with participants linked with a particular CP in OS. |
Visits/Events | Visits/Events | The visits/events from RC can be synchronized with visits/events linked with a particular CP in OS. |
Adding more project
To add more than one REDCap project to your collection protocol in OpenSpecimen, you can follow below steps:
Go to the REDCap configuration page for your collection protocol of choice.
Click on the ‘More' option and select ‘+Add Another’.
Configure the new project as shown above.
