1 Records Inclusion Rule
- 1.1 Example Rules
- 1.2 Adding Filter Rules in UI
2 Forms Exclusion List
3 Fields Exclusion/Inclusion List
4 Adding More Projects
5 Data Dictionary for Fields and Events Mapping

Records Inclusion Rule

You can define rules to filter which REDCap records are synced to OpenSpecimen. For example, sync only if consent is ‘true’, or age > 18, etc.

Each rule follows the pattern:

Can contain rules on one or more data fields of the same or different instruments.
Applies a condition to those fields (for example: equals, starts with, contains)
Evaluates each incoming record independently

Example Rules

#gender == 'Female'
#protocol_id?.startsWith('UM')
#diagnosis?.contains('Cancer')
#age >= 18
#collection_date >= '2024-01-01'
#gender == 'Male' and #age > 40
#site == 'Pune' or #site == 'Mumbai'
#consentStatus != 'Withdrawn'
(#gender == 'Female' and #age >= 30) or #risk_group == 'High'

Here, ‘gender’, ‘protocol_id’, ‘diagnosis’, etc., are REDCap variable names which can be found in the data dictionary.
The criteria uses SpEL language, which treats both double quotes (" ") and single quotes (' ') as valid string literals.
- So, both #sync == “Yes” and #sync == ‘Yes’ are evaluated identically and behave the same

Adding Filter Rules in UI

Go to the CP overview page → Settings → REDCap Project Configuration → Add Project
Enter project details → Click Next
On the Fields and Events Mapping page → Add criteria in the Records Inclusion Criteria section

Forms Exclusion List

Users can define a list of REDCap forms to exclude from synchronisation. If the user provides the list to the ‘Forms Exclusion list’ text box, then all forms will be synchronized except those mentioned in the list.

Go to the CP overview page → Settings → REDCap Project Configuration → Add Project
Enter project details → Click Next
On the Fields and Events Mapping page → Add the REDCap form variable name in the 'Forms Exclusion List' section.
1. Enter multiple form names separated by commas or on separate lines

Fields Exclusion/Inclusion List

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 parameters at once and can add either the inclusion/exclusion list.
1. 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.
2. On the other hand, only specified fields will be synchronized if the user provides the list to the ‘Field Inclusion list’.

Go to the CP overview page → Settings → REDCap Project Configuration → Add Project
Enter project details → Click Next
On the Fields and Events Mapping page → Add the REDCap field variable names in the 'Fields Inclusion List/Fields Exclusion List' section.

Adding More Projects

In some cases, the data to be synced in OpenSpecimen may come from multiple REDCap projects or servers. OpenSpecimen supports adding more than one project to an existing Collection Protocol.

Go to the REDCap Configuration page for your desired Collection Protocol.
Click More → Select + Add Another.

Configure the new project as required.

Data Dictionary for Fields and Events Mapping

Field Name	Mandatory?	Supported study type	Description

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.