FHIR Module

The RareLink FHIR module implements the open-source toFHIR engine which converts all data from the RareLink-CDM into FHIR resources. This section details the commands available in the RareLink CLI to manage the FHIR module and associated pipelines.

Attention

  • Please ensure you are authorized to export (real-world) data to the configured FHIR server. This includes verifying compliance with the ethical agreement and data protection regulations of your study or registry

  • Be aware of your projects development and production mode. Read the REDCap section and discuss this with your FHIR server administrator!

Tip

FHIR Implementation Guide: https://bih-cei.github.io/rarelink/

Overview

Getting started

To use these functionalities, you need a running REDCap project with API access and the RareLink-CDM instruments. You also need the framework and all its components running. You can run the following commands to set everything up:

  • rarelink framework update to update the framework and all components.

  • rarelink setup redcap-project to set up a REDCap project with your REDCap administrator.

  • rarelink setup keys to set up the REDCap API access locally.

Docker Commands

These commands help manage Docker containers used in the RareLink framework.

  • Stop All Containers:

    docker stop $(docker ps -q)

  • Remove Stopped Containers:

    docker rm $(docker ps -aq)

  • Restart Containers with Docker Compose:

    docker-compose down
docker-compose up -d

  • Inspect a Running Container:

    docker exec -it <container_name> /bin/bash

  • View Logs:

    docker logs -f <container_name>

    For example:

    docker logs -f tofhir

    This shows real-time logs for the tofhir export process.

  • Copy Files from a Container:

    docker cp <container_name>:/path/to/file /local/destination

Importing FHIR to REDCap

Clinical Data Interoperability Services (CDIS) is a module in REDCap that lets your project pull clinical data from an external electronic health record (EHR) system. With CDIS, you can use standard FHIR APIs or custom web services to import data into your REDCap project. This guide is intended to help users understand how to implement and use the CDIS modules for RareLink and the RareLink-CDM.

Note

The CDIS modules can only be enabled by a REDCap administrator. If you need access to these modules, please contact your REDCap administrator.

Hint

For more information please read:

CDIS is divided into three modules:

  • Clinical Data Pull (CDP)

  • Clinical Data Mart (CDM)

  • Dynamic Data Pull (DDP)

Each module has its own process for mapping data from the EHR to your REDCap forms. This guide explains how to use each module and shows where to add your model-specific mapping details.

Modules Overview

Clinical Data Pull (CDP)

The CDP module is used for importing clinical data for one patient at a time. It requires you to:

  1. Create REDCap Instruments:

    Set up the Data Dictionary, i.e. the corresponding REDCap forms you want to use from the RareLink-CDM before using CDP.

  1. Field Mappings:

    After creating your forms, navigate to the CDP Mapping page. Here, you map fixed EHR source fields to the fields in your REDCap forms.

    • REDCap Field: this column lists the variables in your REDCap forms

    • External Source Field: this column lists the available source fields in the EHR

    • Date/Time: The date field which is associated with the temporal fields. It is disabled by default, and it will be enabled if you select a temporal field from External Source Field list.

    • Preselect Strategy: this column indicates how the data is fetched

Note

The mapping is mandatory for the patient identifier (e.g., Medical Record Number) which corresponds to element 1.1 in the RareLink-CDM. The rest of the fields are optional.

Hint

Check out either the RareLink-CDM Instruments or the LinkML Schema sections in our docs to find all the field variables and forms of the RareLink-CDM.

A sample mapping table with values from the RareLink-CDM might look like:

+---------------------------+----------------------+---------------------+------------------------+
| **External Source Field** | **REDCap Field**     | **Date/Time Field** | **Preselect Strategy** |
+===========================+======================+=====================+========================+
| MedicalRecordNumber       | snomedct_422549004   |                     | N/A                    |
+---------------------------+----------------------+---------------------+------------------------+
| DOB                       | snomedct_399423000   |                     | Latest Value           |
+---------------------------+----------------------+---------------------+------------------------+
| Glucose [Presence]        | ncit_c60819          | ncit_c82577         | Nearest Timestamp      |
+---------------------------+----------------------+---------------------+------------------------+

In this example, these RareLink-CDM elements in REDCap are mapped to the corresponding EHR source field names:

  • 1.1 Pseudnoym snomedct_42254900 corresponds to MedicalRecordNumber in the EHR system.

  • 1.2 Date of Birth snomedct_399423000 corresponds to DOB in the EHR system.

  • 6.3.1 Assay ncit_c60819 & 6.3.5 Time Observed ncit_c82577 correspond to Glucose [Presence] in the EHR system.

  1. Adjudication: Adjudication refers to the process in which EHR data is manually reviewed and approved by a user before it is officially saved and stored in the REDCap project. Once mapping is complete, users review and approve (adjudicate) the data fetched from the EHR before it is saved into the REDCap project. This helps ensure data accuracy.

Hint

You can find more information on the adjudication process with pictures in the 2.6 Data adjudication in CDP Methods section of the paper by Cheng A.C., et al..

Clinical Data Mart (CDM)

The CDM module enables bulk import of EHR data into REDCap. It is set up during project creation, and a REDCap administrator must be involved to enable and configure this feature.

Steps:

  1. Project Creation: Select the “Clinical Data Mart” option on the project creation page. (Note: REDCap administrator approval is required.)

  2. Automatic Instrument Creation: REDCap auto-generates instruments for each selected source field category (e.g., Demography, Labs, Condition).

  3. Optional Filters:

    • Time Range: Set a date filter to limit data (e.g., for lab results).

    • Patient ID: Optionally, specify patient identifiers (MRNs) to fetch data for specific patients.

  4. RareLink-CDM Mapping Configuration: please see the information above for the step 2. Field Mappings in the CDP module section on how to develop your specific mapping table.

After setup, use the Fetch all records button on the Clinical Data Mart page to retrieve and populate the instruments with EHR data.

Hint

You can find more information on the Clinical Data Mart in the 2.2. Defining initial use cases and operational data flow requirements Methods section of the paper by Cheng A.C., et al..

Dynamic Data Pull (DDP)

The DDP module is used when the list of source fields may change over time. Unlike CDP, which uses a fixed field list from the EHR’s FHIR API, DDP uses web services to dynamically retrieve fields and data.

  1. Metadata Web Service: Retrieves a dynamic list of available source fields.

  2. Data Web Service: Fetches the actual patient data from the external system.

Before enabling DDP, a REDCap administrator must implement and configure these web services (set the metadata and data web service URLs) as described in the official documentation. Once configured, DDP follows a similar flow to CDP: create your REDCap forms, set up field mappings, and adjudicate the fetched data.

RareLink-DDP Mapping Configuration: please see the information above for the step 2. Field Mappings in the CDP module section on how to develop your specific mapping table.

Hint

You can find more information on the Dynamic Data Pull in the paper by Campion Jr Thomas R, et al..

Modules Comparison

Below is a summary comparison of the three CDIS modules:

Feature

CDP

CDM

DDP

Data Mapping

User-defined mappings per record

Predefined instrument mappings

Custom mapping via dynamic metadata

Activation Process

REDCap admin must enable CDP

User permission required

REDCap admin must enable DDP

Data Pull Process

Fetched during record creation

Fetched in bulk upon user action

Pulled from web service during record creation

Adjudication

Manual review before saving

Manual review before saving

Manual review before saving (post web service mapping)

When to Use

When custom mapping is needed

When default mappings suffice

When standard source fields are insufficient or when dynamic mapping is required