How REDCap Project Configuration Impacts OpenSpecimen Sync

Initial Considerations

REDCap → OpenSpecimen sync must be performed by the BMIC OpenSpecimen team.

The purpose of this article is to provide users with an understanding of how the REDCap architectural design will impact what can / cannot be easily or automatically sync’d to OpenSpecimen.

The Process

🔁 1. How a REDCap Longitudinal Project Syncs to OpenSpecimen

Longitudinal projects in REDCap are designed around defined events (e.g., baseline visit, follow-up visits) and often represent structured, scheduled study visits. OpenSpecimen’s REDCap integration can pull these longitudinal structures into OpenSpecimen as visits that map to the OpenSpecimen Collection Protocol’s events.

📌 What Happens in Sync

• Configure the REDCap project in OpenSpecimen by mapping:

  • The REDCap project to an OpenSpecimen Collection Protocol.

  • REDCap participant fields to OpenSpecimen participant attributes.

  • REDCap events/visit fields to OpenSpecimen visit fields.

• OpenSpecimen then uses the REDCap API to pull:

  • Participant records.

  • Event or visit data created in REDCap.
    These become participants and visits in OpenSpecimen.

• Instrument data at each event (e.g., forms for a specific visit) can also be pulled as OpenSpecimen forms tied to those visits or participants.

✔ Why This Works Well

• The longitudinal model has a defined structure (events with a name and expected timing), which maps directly to visits in OpenSpecimen.

• OpenSpecimen expects a one-to-one alignment between a REDCap event and an OpenSpecimen visit (or visit type), so data sync is consistent and traceable.

🔄 2. REDCap Repeating Visit Instruments — Why Sync May Be Different

In REDCap, repeating instruments and repeating events are features that allow a form or an entire event to be filled multiple times without predefined event names for each instance. They are more open-ended than standard longitudinal visits.

📌 Difference Between Repeating and Longitudinal

• Longitudinal Events: Defined time points (e.g., Visit 1, Visit 2) that are stable and named — great for mapping.

• Repeating Instruments/Events:

  • Repeating Instruments let you repeat a single instrument independently of events (e.g., multiple medications, adverse events, visits).

  • Repeating Events let you repeat an entire event (all instruments in that event) but without preassigned labeled events like Visit A, Visit B.

⚠ Why This Can Be Challenging to Sync

Here’s where it matters:

1. Lack of Predefined Visit Labels
   Repeating instruments/events usually generate additional rows in REDCap’s dataset with instance identifiers, but there aren’t fixed event names or structured visit definitions like in a standard longitudinal project. This means there isn’t a consistent event label that OpenSpecimen can map to a defined visit type.

2. No Explicit Event Structure for Each Instance
   In REDCap’s database/API, repeating instruments are essentially a series of repeated forms with instance numbers but no inherent visit structure to map to OpenSpecimen visits. The lack of a distinct event name or event instance makes automated mapping harder or sometimes unsupported, depending on the OpenSpecimen integration logic.

3. Possible Implementation Limits in OpenSpecimen
   The open documentation talks about mapping instruments and events for longitudinal studies — but it does not explicitly describe how repeating instrument instances map to OpenSpecimen’s visit constructs. That gap suggests:

   • Static longitudinal events (e.g., Visit 1, Visit 2) sync fine.

Repeating events/instruments may either sync only once (first instance), or may require custom handling — and might not sync automatically as separate visits unless supported by the plugin configuration

🧠 Summary: Sync Behavior

📌 Practical Considerations

• If you want every repeated instance to create a visit in OpenSpecimen, it’s best to use defined longitudinal events in REDCap rather than open-ended repeating instruments.

• If repeating forms are essential and you want data reflected in OpenSpecimen, consider:

  • Manual data entry into OpenSpecimen

  • Export data from REDCap → import into OpenSpecimen

  • Add explicit fields (instance number / visit label / visit date) on repeating instrument in REDCap

    • User must manually copy/paste visit label field from OpenSpecimen visit into this explicit field to align visit information.