Introduction
...
| Expand |
|---|
Go to the CP Overview Page and click on the 'Settings' tab on the left sidebar.  Image Removed Image AddedSelect ‘REDCap Project Configuration' and click on the 'Add Project’ button.  Image Removed Image AddedProvide information on the project name, server name, API token, site, PHI data, snapshot download page size, and users, and then click on 'Next'.  Image Removed Image Added
Data Dictionary for Project details 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). | Info |
|---|
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 can be done at two levels: Participant (Both classical and longitudinal studies) and Visit (Longitudinal study)
| Note |
|---|
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
| Expand |
|---|
After adding the project details, you can move to the ‘Fields and Events Mapping’ page by clicking the Next button.  Image AddedMap REDCap variables (on the left) obtained from the 'data dictionary' to OpenSpecimen (on the right) as shown below.
|
...
 Image Added Image Added
|
List of Participant Fields and Variables
| Expand |
|---|
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 |
|
Event and Visit Level Mapping
| Expand |
|---|
Like 'Participant Level Mapping', map visits fields for the REDCap project as shown below.
|
...
 Image AddedAdditionally, you can map events for the REDCap project, as shown below.
|
...
 Image AddedThose 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
| Expand |
|---|
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 |
|
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.
| Expand |
|---|
When the label format is not configured on OS: When the format is configured in OS: Since the label is being generated by OS, users do need not 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.
|
Advance Features
Add the list of forms/fields separated by comma, tab, or newline.
Records Inclusion Rule
| Expand |
|---|
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.
|
...
 Image AddedThe example show below will only fetch the records where the eligibility has value either ‘eligible, needs scheduled' or 'eligible, scheduled’.
|
...
 Image Added
This example show below will only fetch those records who have value in their
|
...
...
 Image Added Image Added |
Forms Exclusion List
| Expand |
|---|
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.
|
...
 Image Added
|
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
| Expand |
|---|
Like ‘Forms Exclusion List’, the user can also define the list of fields to either include or exclude for synchronization. The user can’t define both the parameters at once. 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’.
|
...
 Image Added
|
To include or exclude a form/field use the variable name of the form/field from REDCap.
Data Dictionary for Fields and Events Mapping
| Expand |
|---|
| Info |
|---|
Add the list of fields/forms separated by a comma, tab, or newline. During participant and visit fields mapping, REDCap variables should be on the left side, whereas OpenSpecimen variables should be on the right side. For Field Exclusion List and Field Inclusion List, the user can define only one of the parameters at a time.
|
Field Name | Mandatory? | Supported study type | Description |
|---|
Participant Fields Mapping | No | Classical/Longitudinal | Specifies the list of OpenSpecimen participant fields that are mapped to their respective REDCap fields. For example, rcRecordId=ppid,dob=participant.birthDate | Visit Fields Mapping | No | Classical/Longitudinal | Specifies the list of OpenSpecimen visit fields which are mapped to their respective REDCap fields. For example, visit_label=eventLable,visit_site=site,visit_date=visitDate | Records Inclusion Rule | No | Classical/Longitudinal | Defines condition/s to synchronize specific REDCap records to OpenSpecimen. The expression is formed using REDCap variables obtained from the 'data dictionary'. For example, to fetch the records of female participants who are 18 years old or older we can use following expression: #sex == 'Female' and #yearBetween(#dob, #regDate) >= 18 | Form Exclusion List | No | Classical/Longitudinal | Defines the list of forms to be excluded for synchronization irrespective of being mapped to participant or visit field. For examples, Follow_up_year_1,Follow_up_year_2 | Fields Inclusion List | No | Classical/Longitudinal | Defines the list of fields to be included for synchronization. For examples, enrollment_date, consent_date | Fields Exclusion List | No | Classical/Longitudinal | Defines the list of fields to be excluded for synchronization irrespective of being mapped to participant or visit field. | Events Mapping | No | Longitudinal | Specifies the list of OpenSpecimen events which are mapped to their respective REDCap events. | Ignore Unmapped Events | No | Longitudinal | Checkbox fields that can be ‘ticked’ to ignore the unmapped events of the REDCap. This prevents the creation of unwanted, unplanned events in OpenSpecimen. |
|
Integration Points
| Expand |
|---|
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
| Expand |
|---|
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.
|
...
 Image Added
|
Mapping PVs from REDCap to corresponding PVs of OpenSpecimen
...