Secondary Use FHIR Server Implementation Guide
0.1.0 - ci-build

Secondary Use FHIR Server Implementation Guide - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Home

Official URL: https://secondary-use-ig.cumuluz.dev/ig/ImplementationGuide/org.cumuluz.secondaryuse.ig Version: 0.1.0
Draft as of 2026-07-15 Computable Name: CumuluzSecondaryUseIG

Secondary Use Bulk Data Adapter

This guide documents a local FHIR R4 prototype for selecting a patient cohort and exporting privacy-transformed resources through the HL7 Bulk Data asynchronous pattern.

Component Base URL Role
Mock FHIR server http://127.0.0.1:8090/fhir Synthetic source records and ordinary FHIR searches
Privacy adapter http://127.0.0.1:8080/fhir FHIR Search, Bulk Cohort Group creation, Group export, pseudonymization, and NDJSON
Query UI http://127.0.0.1:5173 Explores counts and executes the Group/manifest flow

Standards Boundary

The adapter separates exploration from extraction:

  1. Stateless exploration uses only ordinary FHIR R4 _summary=count searches: Patient _has for cohort size and Patient reference chains for per-type counts. Responses contain no resource entries.
  2. Extraction asynchronously creates Group through the experimental Bulk Cohort API and then uses standard GET [base]/Group/{id}/$export. System-level GET [base]/$export is also supported.

This distinction matters because standard _typeFilter filters resources independently; it does not define cross-resource patient-set intersection.

All adapter exports are pseudonymized. A caller requests the additional analytical field reduction with standard _elements. No request-level privacy mode exists on the FHIR API.

Implemented Flow

  1. Explore cohort and per-type counts with standard FHIR searches; no Group is created.
  2. POST a Bulk Cohort profile Group containing member-filter expressions with Prefer: respond-async.
  3. Poll the create Content-Location and obtain the persisted Group from the completed batch-response Bundle.
  4. Start Group/{id}/$export with Prefer: respond-async.
  5. Poll the export Content-Location, read manifest counts, and download NDJSON.

See Getting Started, Cohort Criteria, Bulk Export, and Privacy.