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

Mapping and Artifacts

Mapping and Artifacts

Runtime Shape

Resource translation follows this general path:

source profile -> logical model -> target profile

The implemented directions are:

STU3 source profile -> logical model -> R4 target profile

STU3 source profile -> logical model -> STU3 target profile

R4 source profile -> logical model -> STU3 target profile

R4 source profile -> logical model -> R4 target profile

QuestionnaireResponse extraction follows this path:

QuestionnaireResponse -> LogicalQuestionnaireForm -> LogicalExtractionBundle -> logical clinical resources -> R4 target resources

Both paths keep mapping behavior in version-controlled FSH, StructureMap, and ConceptMap files.

Where The Mapping Assets Live

Asset type Location
logical models logical-models/input/fsh
XIB profiles logical-models/input/fsh/XibProfiles.fsh, copied into ig/input/fsh/xib for IG generation
source-to-logical maps src/main/resources/mappings/structuremaps/*-to-logical
logical-to-target maps src/main/resources/mappings/structuremaps/logical-to-*
shared map groups src/main/resources/mappings/structuremaps/shared
QuestionnaireResponse extraction maps src/main/resources/mappings/structuremaps/pzp-questionnaire
ConceptMaps src/main/resources/mappings/conceptmaps
local terminology fragments src/main/resources/terminology

The generated IG artifact list is available at Artifacts. XIB profile intent, parent selection, and source-support boundaries are documented on XIB Profiles.

Source Map Layers

The source maps are grouped by input family:

Directory Role
zib2017-to-logical reusable Dutch STU3 zib source mappings
nlcore2017-to-logical reusable Dutch STU3 nl-core source mappings
bgz2017-to-logical BgZ package-local source mappings
pzp2017-to-logical PZP ACP source mappings
eafspraak2017-to-logical Appointment source mapping
nlcore-to-logical Dutch R4 source mappings for reverse and R4-to-R4 routes
eps-to-logical EPS Patient Summary R4 source wrappers for exact reverse and R4-to-R4 routes
r4-to-logical Base/EU R4 source mappings for reverse and R4-to-R4 routes
pzp2020-to-logical PZP 2020 ACP R4 source mappings

These layers are reuse groups, not a runtime inheritance model.

Target Map Families

Directory Target family
logical-to-nlcore Dutch nl-core R4 targets
logical-to-eubase European base/core R4 targets
logical-to-eps European Patient Summary targets
logical-to-pzp PZP 2020 ACP targets
logical-to-xib local draft XIB R4 targets
logical-to-r4 explicit base R4 targets
logical-to-bgz2017 Dutch STU3 targets for R4-to-STU3 and selected STU3-to-STU3 routes

Runtime Responsibilities

Layer Responsibility
HTTP routes parse requests, select operation, return FHIR responses and errors
registry resolve exact source profile and target profile route
StructureMap runtime execute source-to-logical and logical-to-target maps
ConceptMap support translate or normalize coded values where maps request it
validation service validate produced R4 resources against requested target profiles
report builder produce the FHIR translationReport

The HTTP layer should not contain hidden semantic workarounds for unmapped fields or target profile requirements.

Single Resource Transform Steps

  1. Parse request as FHIR Parameters.
  2. Parse source with the parser for the selected endpoint direction.
  3. Resolve sourceProfile + targetProfile in the registry for that direction.
  4. Run the source-to-logical StructureMap.
  5. Run the logical-to-target StructureMap.
  6. Materialize the target resource and set the requested target profile.
  7. Apply configured ConceptMap translations, including ICPC-to-SNOMED where available.
  8. Build the translationReport for R4 target transforms.
  9. Apply validationMode for R4 target transforms.
  10. Return FHIR Parameters.

Bundle And EPS Steps

For ordinary Bundle transforms, each entry follows the same route resolution and mapping chain.

For EPS document output, the top-level target is:

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

The service translates supported entries to EPS resource profiles, then assembles the R4 document Bundle, Composition, section references, and stable fullUrls.

Validation Boundary

Validation is target-side R4 validation only. STU3 targets are translated and returned without R4 validation.

Known offline terminology or package-expansion issues may be relaxed narrowly and counted in the validation summary. Structural errors, max-cardinality errors, unknown profiles, and missing mapped target requirements remain blocking in validationMode=enforce.

Generated Artifact Pages

The IG publishes generated pages for:

  • OperationDefinitions
  • CapabilityStatements
  • local extensions used by reports and bundle target overrides
  • logical model StructureDefinitions
  • examples

For most readers, Transform, QuestionnaireResponse Extraction, Target Profiles, and Translation Matrix are enough. Use Artifacts when you need the generated FHIR artifact detail.