Introduction

This repository contains software components for a demonstration of participant dynamic consent management for samples and data. It specifically tests communication between a Biobank Information Management System (BIMS) and the Bridgehead Blaze FHIR server, part of the BBMRI-ERIC Locator. The project was conducted within the Strengthening BBMRI initiative.

The repository contains five main components:

1. A Biobank BIMS API simulator
2. An ETL script that:
   • Extracts/reads data from a file or API
   • Transforms data first into a MIABIS-compliant structure, then into FHIR JSON bundles based on project-specific profiles
   • Loads FHIR JSON bundles into the Blaze FHIR server
3. A Blaze FHIR server (part of BBMRI-ERIC Locator)
4. A CQL query script for the Blaze FHIR server
5. A GUI frontend for the query script

Data flows from the Biobank BIMS to the ETL can occur via:

• Direct API queries to the Biobank BIMS
• CSV/Excel files following a provided template

Installation

Clone the repository. Optionally, create a virtual environment. Python 3.14 is recommended.

Download micromamba:

curl -kL https://micro.mamba.pm/api/micromamba/linux-64/latest | tar -xvj -C ./ --strip-components=1 bin/micromamba

add to shell:

eval "$(./micromamba shell hook --shell bash)"

create and activate an environment:

conda create --name myenv python=3.14
micromamba activate myenv

install the dependencies (from the main dir of the repository):

pip install -r ./requirements.txt

Running the tests

Test via API (CCE-IT Biobank)

This test uses CCEs available in tested biobanks. Data flows from the simulated BIMS API (or real BIMS with compatible interface).

Open three shells (each with activated environment):

Shell 1 - API simulator:

cd api
python simulator.py

Shell 2 - FHIR server:

cd blaze
docker compose up

Note: To clear server data "docker compose down -v"

Shell 3 - ETL:

python bims_source.py --biobank_name testbb --consent_conditions_version  v1biobank --minimal_dataset_type_of_input rest_api --simulated

The ETL retrieves data from the API, transforms it into FHIR resources (saved in output_organizations/ and output_patients/), and loads them into the FHIR server. A summary table shows input data, created resources, and server storage.

View parameters:

python bims_source.py --help

Use --cfrom and --cto for time windows.

Shell 3 - Query GUI:

python query_test_server.py

Open http//localhost:5000/query_test_ui.html. Keep set CCEs version to "CCE-IT BIOBANKS" and adjust parameters, then execute. Underneath the output/error will appear.

Test via CSV/Excel (CCE v2)

This test uses CCE version 2 (from DUC/CCE definition effort).

Open two shells (each with activated environment):

Shell 1 - FHIR server:

docker compose up

Note: To clear server data: "docker compose down -v"

Shell 2 - ETL (CSV):

python bims_source.py --consent_conditions_version v2 --minimal_dataset_type_of_input csv

for the csv file (defaults to "./input/minimal-dataset-with-consent-template.csv")

or ETL (Excel):

python bims_source.py --consent_conditions_version v2 --minimal_dataset_type_of_input excel --minimal_dataset_input_file minimal-dataset-with-consent-template.xlsx

for the excel file (defaults to "./input/minimal-dataset-with-consent-template.xlsx")

The ETL read data from the xsv/excel file, transforms it into FHIR resources (saved in output_organizations/ and output_patients/), and loads them into the FHIR server. A summary table shows input data, created resources, and server storage.

Shell 2 - Query GUI:

python query_test_server.py

Open http//localhost:5000/query_test_ui.html The interface allow to query for many parameters. Change CCEs version to v2. Adjust parameters and execute to see matching samples/participants.

Acknowledgments

This work has been partially supported by the Projects: Strengthening BBMRI.it, funded by Next Generation EU – Italian NRRP IR0000031 – CUP B53C22001820006; ToPMa (G.A. RC_CRP_077) and XDATA funded by the Sardinian Regional Authority.