Cumuluz Translate Implementation Guide
0.1.0 - ci-build

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

Transform

Transform

Resource transform operations are organized by FHIR source and target version. The exact source profile and target profile still decide the registered route.

Direction Endpoint Route shape
STU3 to R4 POST /fhir/stu3-r4/$transform STU3 source profile -> logical model -> R4 target profile
STU3 to STU3 POST /fhir/stu3/$transform STU3 source profile -> logical model -> STU3 target profile
R4 to STU3 POST /fhir/r4-stu3/$transform R4 source profile -> logical model -> STU3 target profile
R4 to R4 POST /fhir/r4/$transform R4 source profile -> logical model -> R4 target profile

All supported resource transforms go through a logical model. The service does not perform direct resource-type conversion.

STU3 To R4 Endpoint

POST /fhir/stu3-r4/$transform

Use this operation when the input is already a supported STU3 source resource profile or a supported STU3 Bundle.

Do not use $transform for completed forms. Use QuestionnaireResponse Extraction for supported PZP ACP QuestionnaireResponses.

Supported Input And Output Families

Source family Source examples Target families
BgZ 2017 package-local profiles BgZ-Patient, BgZ-Problem, BgZ-Procedure, BgZ-FunctionalOrMentalStatus, BgZ-Metadata nl-core, eu-base, EPS, base R4 where implemented
BgZ exchange dependent Dutch STU3 profiles zib-AllergyIntolerance, zib-Encounter, nl-core-careteam, eAfspraak-Appointment, medication zibs nl-core, eu-base, EPS, base R4 where implemented
PZP 2017 ACP profiles ACP-Patient, ACP-AdvanceDirective, ACP-MedicalDevice, and other registered ACP profiles matching PZP 2020 ACP, supported generic parent targets, selected EU Base targets, selected EPS targets
PZP 2020 ACP R4 profiles ACP-Patient, ACP-AdvanceDirective, ACP-MedicalDevice, and other registered ACP profiles XIB, matching PZP 2020 ACP, supported generic parent targets, selected EU Base targets, selected EPS targets

The source and target profile pair is part of the route. The service does not infer support from resource type alone.

Request Parameters

The request body is a FHIR Parameters resource.

Name Required Type Meaning
source yes Resource STU3 source resource or STU3 Bundle
sourceProfile single resource: yes; Bundle: entry profiles preferred canonical supported STU3 source profile
targetProfile single resource: yes; Bundle: optional fallback canonical requested R4 target profile
validationMode no code enforce, report, or none; default is enforce
returnLogical no boolean include the intermediate logical model as a Binary

validationMode behavior:

Mode Behavior
enforce validate R4 output and fail the transform on error or fatal issues
report validate R4 output and return diagnostics without blocking the translated result
none skip transform-time validation

Response Parameters

On success, the response is a FHIR Parameters resource.

Name Type Meaning
result Resource translated R4 resource or Bundle
targetProfile canonical target profile route that was applied
translationReport Parameters mapped, changed, added, and deleted values
logical Binary intermediate logical model when requested
outcome OperationOutcome validation result for enforce and report

Bundle Translation

The transform endpoint accepts STU3 Bundles.

For ordinary Bundle transforms:

  • each entry carries its source profile in entry.resource.meta.profile
  • entry-level target overrides use Bundle.entry.request.extension
  • the top-level targetProfile is the fallback when an entry does not override it
  • supported BgZ exchange entries infer the expected Dutch R4 target when no target is supplied
  • PZP entries can infer the matching PZP 2020 target when no target is supplied

The target override extension is:

  • https://fhir.cumuluz.org/StructureDefinition/translation-target-profile

Use valueUri for the target profile canonical.

For EPS document Bundle output, set the top-level targetProfile to:

  • http://hl7.eu/fhir/eps/StructureDefinition/bundle-eu-eps

The service translates supported entries through EPS resource maps, then assembles the R4 document Bundle and Composition. Unsupported EPS document entries fail explicitly.

Translation Report

Every successful transform includes a FHIR-shaped translationReport.

Group Meaning
mapped source value copied or structurally mapped
changed source value translated, normalized, or recoded
added target value added by route, target profile, or mapping rule
deleted source value intentionally not represented in the target

The report is a review aid. Profile conformance still comes from validation.

R4 To STU3 Transform

Reverse translation is exposed as a separate operation:

POST /fhir/r4-stu3/$transform

Use this operation only for exact R4 source profile and Dutch STU3 target profile pairs listed in Translation Matrix. Reverse support is not automatic inversion of the forward maps; the route must have an explicit R4-to-logical source map and logical-to-BgZ/STU3 target map.

The request body is a FHIR Parameters resource.

Name Required Type Meaning
source yes Resource R4 source resource
sourceProfile no canonical supported R4 source profile; defaults to source.meta.profile when omitted
targetProfile yes canonical requested STU3 target profile
returnLogical no boolean include the intermediate logical model as a STU3 Binary

On success, the response is a STU3 FHIR Parameters resource.

Name Type Meaning
result Resource translated STU3 resource
targetProfile uri STU3 target profile route that was applied
logical Binary intermediate logical model when requested

Reverse transforms do not perform R4 target validation because the result is STU3. Unsupported reverse profile pairs fail with an OperationOutcome.

STU3 To STU3 Transform

Same-version Dutch STU3 translation is exposed as:

POST /fhir/stu3/$transform

Use this operation only for exact Dutch STU3 source profile and Dutch STU3 target profile pairs listed in Translation Matrix or in GET /fhir/stu3/translation-index. Routes are exposed only where that exact pair is registered with an implemented source-to-logical map and logical-to-STU3 target map.

The request body is a FHIR STU3 Parameters resource.

Name Required Type Meaning
source yes Resource STU3 source resource
sourceProfile no uri supported STU3 source profile; defaults to source.meta.profile when omitted
targetProfile yes uri requested STU3 target profile
returnLogical no boolean include the intermediate logical model as a STU3 Binary

On success, the response is a STU3 FHIR Parameters resource with result, targetProfile, and optional logical. STU3-to-STU3 transforms do not perform R4 target validation because the result is STU3.

R4 To R4 Transform

Same-version R4 translation is exposed as:

POST /fhir/r4/$transform

Use this operation only for exact R4 source profile and R4 target profile pairs listed in Translation Matrix or in GET /fhir/r4/translation-index. R4-to-R4 support requires an explicit profile-specific R4-to-logical source map and a registered logical-to-R4 target map for that exact pair.

The request body is a FHIR R4 Parameters resource.

Name Required Type Meaning
source yes Resource R4 source resource
sourceProfile no canonical supported R4 source profile; defaults to source.meta.profile when omitted
targetProfile yes canonical requested R4 target profile
validationMode no code enforce, report, or none; default is enforce
returnLogical no boolean include the intermediate logical model as a Binary

On success, the response is an R4 FHIR Parameters resource with result, targetProfile, translationReport, optional logical, and optional validation outcome.

Coded Value Translation

Concept translation happens in the mapping runtime when a registered ConceptMap applies.

Current examples include:

  • ICPC-1-NL clinical codings to SNOMED CT, using the Nictiz ICPC-to-SNOMED ConceptMap and local fragments where available
  • Dutch/PZP questionnaire answer normalization for booleans, treatment choices, contact-point use, UZI specialty, and default codings
  • profile-specific display and code normalization needed by target validation

See Concept Translation for the terminology behavior.

Failure Behavior

Malformed requests and unsupported routes return a FHIR OperationOutcome with HTTP 400.

Common causes:

  • missing source
  • missing single-resource sourceProfile or targetProfile
  • source profile not in the registry
  • target profile not registered for that source profile
  • Bundle entry without a supported route
  • invalid source JSON for the selected parser/version

Examples

Example File
BgZ Patient transform request ig/input/examples/patient-transform-request.json
BgZ Patient transform response ig/input/examples/patient-transform-response.json
Bundle transform request ig/input/examples/bundle-transform-request.json

Discovery

Need Endpoint
Transform operation definition GET /fhir/stu3-r4/OperationDefinition/bgz-transform
Translation surface metadata GET /fhir/stu3-r4/metadata
Machine-readable route list GET /fhir/stu3-r4/translation-index
STU3 transform operation definition GET /fhir/stu3/OperationDefinition/stu3-transform
STU3 translation surface metadata GET /fhir/stu3/metadata
STU3 machine-readable route list GET /fhir/stu3/translation-index
Reverse transform operation definition GET /fhir/r4-stu3/OperationDefinition/r4-stu3-transform
Reverse translation surface metadata GET /fhir/r4-stu3/metadata
Reverse machine-readable route list GET /fhir/r4-stu3/translation-index
R4 transform operation definition GET /fhir/r4/OperationDefinition/r4-transform
R4 translation and validation metadata GET /fhir/r4/metadata
R4 machine-readable route list GET /fhir/r4/translation-index