Secondary Use FHIR Server Implementation Guide
0.1.0 - ci-build

Publish Box goes here

Home

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

Secondary Use FHIR Server

What This Guide Specifies

This guide describes the FHIR-facing contract of secondary-use-server: a small local prototype for secondary-use experiments with synthetic IBD data.

The project contains two services:

  • a mock FHIR R4 source server that serves generated patient-centered clinical data
  • a Bulk-shaped privacy adapter that resolves cohorts through ordinary backend FHIR searches, applies privacy transforms, and exposes NDJSON output through Bulk Data-style polling

The guide is intentionally about this project only. It does not describe the CumuluZ translation service, does not define national production profiles, and does not claim certified de-identification.

Prototype warning

This server is a local experiment. It has no authentication, authorization, consent, audit store, production scheduling, or certified de-identification process.

All generated data is fake and must not be used as clinical evidence.

Contract At A Glance

Services

Role Default base URL Purpose
Mock FHIR server http://127.0.0.1:8090/fhir Source server with generated R4 resources, search, read, and a minimal $export
Bulk privacy adapter http://127.0.0.1:8080/fhir Fronting adapter with cohort criteria, privacy modes, count preview, and Bulk-style NDJSON output

Main Calls

Need Endpoint Response
Discover service capability GET /fhir/metadata FHIR CapabilityStatement
Search source resources GET /fhir/{resourceType} FHIR searchset Bundle
Read a source resource GET /fhir/{resourceType}/{id} FHIR resource or OperationOutcome
Start export GET /fhir/$export 202 Accepted with Content-Location
Poll export GET /fhir/bulk-status/{jobId} Bulk status JSON with NDJSON file URLs and bulk:// storage locations
Delete export DELETE /fhir/bulk-status/{jobId} Removes a completed prototype job
Download NDJSON GET /fhir/bulk-files/{jobId}/{type}.ndjson application/fhir+ndjson
Preview counts GET /fhir/$export?_summary=count FHIR Parameters

Main Concepts

FHIR R4 Runtime

The server uses HAPI FHIR R4 as its FHIR model and serialization surface. The resources are R4 resources, and the runtime capability statement reports FHIR version 4.0.1.

Profile validation is not wired yet. Some generated resources carry BgZ/zib-like meta.profile canonicals to make the examples recognizable, but this prototype should be read as an R4-shaped functional experiment rather than a complete profile-conformant package.

Bulk Data Shape

The export flow follows the visible parts of the FHIR Bulk Data pattern:

  1. client starts GET /fhir/$export
  2. server returns 202 Accepted
  3. client polls Content-Location
  4. status response lists output files by resource type
  5. client downloads one NDJSON file per resource type

Jobs complete synchronously in the prototype. Named dataset runs can persist job JSON and NDJSON backing data below <data-dir>/bulk-jobs/. The adapter can also post a best-effort completion notification when notification-url is supplied.

Cohort First, Resources Second

The adapter turns front-end cohort criteria into backend FHIR searches. It first resolves a patient set, then fetches the requested output resource types for those patients.

Within one parameter family, values are ORed. Across families, patient sets are intersected. For example, condition-code=34000006,64766004&medication-code=386872004 selects patients with either listed condition and the medication code.

Privacy As A Transform

The adapter is not just a proxy. It transforms the fetched resources before writing output:

  • pseudonymized rewrites Patient IDs and references, removes direct Patient fields, and shifts dates
  • minimized runs the pseudonymization step and then keeps only a compact analytical field set

The privacy behavior is deterministic for a configured salt so local demos and tests can be repeated.

Reader Paths

Reader Useful path
Client implementer Getting Started -> Bulk Export -> Cohort Criteria
Privacy reviewer Privacy Modes -> FHIR Resources -> Prototype Limits
Dataset user Synthetic Dataset -> FHIR Resources
Maintainer Implementation Notes -> Prototype Limits