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-10-17 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 Container-internal http://127.0.0.1:8090/fhir Synthetic source records and ordinary FHIR searches
Privacy adapter http://127.0.0.1:8080/fhir Focused FHIR Search, Bulk Cohort Group creation, Group export, pseudonymization, and NDJSON
Query UI http://127.0.0.1:8080/ Explores counts and executes the Group/manifest flow

For the shortest path to a working count and export, start with Getting Started.

Standards Boundary

The adapter separates exploration from extraction:

  1. Feasibility creates a criteria-based Group and reads its protected quantity after activation. The Group is the stable handle reused for export; the UI does not run independent resource-count searches.
  2. Extraction reuses the activated feasibility Group through the experimental Bulk Cohort API and uses standard GET [base]/Group/{id}/$export. System-level export is retained only in the synthetic demo API.

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. Define cohort criteria for feasibility.
  2. POST a Bulk Cohort profile Group containing member-filter expressions; follow its 201 Location and wait for actual=true.
  3. Wait for Group activation and read quantity without members. The API supports direct Group handles and the legacy asynchronous operation-result contract.
  4. Start Group/{id}/$export per primary type with Prefer: respond-async, reusing the activated Group.
  5. Poll the export Content-Location, read manifest counts, and download NDJSON.

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