| Table of Contents |
|---|
Introduction
Unlike OS, RC doesn’t have fixed instruments for participants and visits. Therefore, you need to maps RC project instruments with OS OpenSpecimen participants and visits fields.
The RC variables for their respective RC fields (as shown below in red boxes) can be obtained from the ‘data dictionary’ available under ‘Project Home and Design’ in RC. Later you can use these variables to map RC fields with OS fieldsfields between two servers.
...
Example of Data Dictionary
...
Mapping
As discussed in the the REDCap (RC) Integration homepage, mapping can be done at three levels.
...
If the participant is not already present in the OSOpenSpecimen, create an OS participantit will create a new participant with their respective Participant level RC forms are linked to OS participants.
If the RC visit is not already present in OSOpenSpecimen, it will create a new OS new visit with their respective Visit level RC forms should get linked to their corresponding OS visits.
Study Level Mapping
To link the RC project from RC with OpenSpecimen collection protocol (CP) from OS , you need to proceed as follows:
Go to the CP Overview Page of choice 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 OS 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 OS server fetch for that will be fetched for the RC server at each timeinterval. This is repeated ‘N' number numbers of times until all records are pulled to the OS server. It helps to minimize the overload to the OS OpenSpecimen server. The default value for it is '1000’.
If you want, you can also add a new server of your choice. To do so, click on the ‘Add New’, provide details on server name, host base URL, plugin path and time zone, and click on the ‘save’ button.
...
| Info |
|---|
Please note that the PHP plugin can be placed anywhere on the REDCap RC 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 | Description |
|---|---|
Server Name | Free text to enter a name for the REDCap server |
Host URL | The base URL of for the REDCap server |
Plugin Path | The relative path for the PHP plugin installed on the REDCap server. |
Time Zone | The timezone of the RC REDCap server. |
Participant Level Mapping
The participant matching is done based on the following attributes
...
The steps for mapping the participants fields between RC and OS OpenSpecimen 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 RC variables (on the right) obtained from the 'data dictionary' with OS to OpenSpecimen (on the left) as shown below.
List of OS 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
| Info |
|---|
It is exclusively for longitudinal studies. |
Like 'Participant Level Mapping', map visits fields between for the RC project and OS CP as shown below in the red box.
Additionally, you can map events from RC with events from OS, for RC project as shown below.
Those events from RC which are not mapped to OS can create unwanted, unplanned events in OSOpenSpecimen. To avoid this, click on the 'Ignore Unmapped Events’ checkbox.
List of OS 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 RC records to OSOpenSpecimen. Once applied, the OS system will ignore all other records that don’t satisfy the criteria irrespective of being mapped to the participant or visit field.
The example shown in the red box below will only fetch the records of female participants from RC 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’, 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’, 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’.
Intergration 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. |
Participant fields | Participant fields | The participant fields from RC can be synchronized with participant fields linked with a particular CP in OS. |
Visit fields | Visit fields | The visit fields from RC can be synchronized with visit fields linked with a particular CP in OS. |
Events | Events | The events from RC can be synchronized with planned events linked with a particular CP in OS. |
...