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

Implementation Notes

Implementation

This page describes the default synthetic demo. External-source configuration and its persistent, bounded export pipeline are documented in the repository's docs/HOSPITAL.md.

Synthetic Search API

1. Parse the Patient search, including supported _has reverse chains.
2. Execute direct Patient criteria and each reverse search against the source.
3. For a resource-type count, parse its standard Patient reference chains and resolve the same Patient criteria internally.
4. Intersect matching Patient ids internally, restrict the selected resource type, and return a _summary=count searchset Bundle with no entries.

Without _summary=count, the adapter returns matching source resources without privacy transformation. This path is intended only for the synthetic source fixture; pseudonymization is an export-stage control.

Source searches require HTTP 200 searchset Bundles, retain match entries of the requested type, and follow relative or query-only next links only within the configured FHIR base. Redirects, malformed responses, paging loops, and off-base next links fail the upstream request. A synchronous adapter search returns HTTP 502; async Group creation records the failure in its completed response Bundle.

Async Bulk Cohort Creation

1. Parse the submitted Group; POST creates a stable id and PUT refreshes that id.
2. Validate the Bulk Cohort profile shape and every member-filter expression.
3. Return POST/201 or PUT/200 with the draft Group and Location, then resolve in background. Explicit Prefer: respond-async retains the legacy 202 operation-result contract.
4. Resolve and intersect Patient sets through resource ids, subject, patient, or Provenance targets.
5. Store the evaluated Group with actual=true and members-refreshed. Demo Groups live in memory; external Groups persist on disk, omit members in reads and suppress small quantities. The UI uses this Group quantity for feasibility.

Group Export

1. Validate asynchronous headers and standard Bulk Data parameters.
2. Read the Group and its source Patient references.
3. In external mode, accept 202 before fetching one primary resource type in a bounded worker. Include configured companion Provenance for actual output targets.
4. Apply _typeFilter to its declared output type. Criteria within one expression are ANDed; repeated expressions for that type are ORed.
5. Apply _since and _until bounds on source timestamps; external mode permits these only when date shifting is disabled.
6. Pseudonymize ids, recursively discovered source Patient references, direct identifiers, and dates.
7. Apply _elements after pseudonymization and add SUBSETTED when requested.
8. For a Group export, restrict a shared Provenance resource to member targets and add SUBSETTED when targets were removed.
9. Persist the manifest and NDJSON output.
10. Publish the completed manifest and NDJSON atomically; the status URL comes from the kickoff Content-Location.

The demo search API above is separate from UI feasibility. External mode exposes no untransformed search API.

System export is available only in the synthetic demo and follows the same validation/privacy pipeline but starts from all supported source resources instead of Group members.

Component Boundaries

Component	Responsibility
FhirSearchQuery	resource-aware FHIR search parsing and validation
CohortRequest	Bulk Cohort Group and member-filter validation
CohortStore	async status, stable Group lifecycle and optional disk persistence
BulkExportRequest	strict standard Bulk Data inputs
FhirSearchBackend	source search, system selection, and Group selection
PrivacyTransformer	mandatory pseudonymization
ElementFilter	standard root-element reduction and SUBSETTED tagging
BulkStore	job manifest and NDJSON persistence

The adapter deliberately does not assign cohort semantics to _typeFilter.

Guide Dependencies

Package hl7.fhir.uv.extensions.r4#5.3.0 This IG defines the global extensions - the ones defined for everyone. These extensions are always in scope wherever FHIR is being used (built Sat, May 16, 2026 18:32+1000+10:00)

Package hl7.fhir.uv.extensions.r4#5.2.0 This IG defines the global extensions - the ones defined for everyone. These extensions are always in scope wherever FHIR is being used (built Mon, Feb 10, 2025 21:45+1100+11:00)

Package hl7.fhir.uv.bulkdata#3.0.0 FHIR based approach for exporting large data sets from a FHIR server to a client application (built Thu, Dec 11, 2025 13:43+0800+08:00)

Package hl7.fhir.uv.tools.r4#1.1.2 This IG defines the extensions that the tools use internally. Some of these extensions are content that are being evaluated for elevation into the main spec, and others are tooling concerns (built Tue, Mar 24, 2026 11:13+1100+11:00)

Cross-Version Analysis

This is an R4 IG. None of the features it uses are changed in R4B, so it can be used as is with R4B systems. Packages for both R4 (org.cumuluz.secondaryuse.ig.r4) and R4B (org.cumuluz.secondaryuse.ig.r4b) are available.

Global Profiles

There are no Global profiles defined

Intellectual Property Statements

Geen gebruik van extern Intellectueel Eigendom (anders dan de FHIR-specificatie)