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

Structure Maps

Structure Maps

What These Are

These are the concrete translation rules used by the runtime.

Each map is a checked-in .map source file. The runtime loads them directly, so the IG should make them easy to inspect rather than hiding them behind prose.

Route Families

The map files are grouped by route family:

  • bgz2017-to-logical/ for BgZ STU3 source content
  • nlcore2017-to-logical/ for Dutch nl-core source-side reuse routes
  • zib2017-to-logical/ for zib source-side reuse routes
  • logical-to-nlcore/ for logical to Dutch R4 target maps
  • logical-to-eubase/ for logical to European R4 target maps
  • logical-to-eps/ for EPS maps layered on the EU Base maps
  • logical-to-r4/ for logical to plain R4 where no profile-specific target is used
  • pzp2017-to-logical/ for PZP 2017 ACP source profiles
  • logical-to-pzp/ for logical to PZP 2020 ACP target profiles
  • pzp-questionnaire/ for the currently registered PZP ACP QuestionnaireResponse normalization and extraction-entry selection
  • shared/ for datatype helper rules shared across routes
  • eafspraak2017-to-logical/ for the supported appointment source route

Concrete Map Files

Patient

  • src/main/resources/mappings/structuremaps/bgz2017-to-logical/Bgz2017PatientToLogicalPatient.map
  • src/main/resources/mappings/structuremaps/nlcore2017-to-logical/Nlcore2017PatientToLogicalPatient.map
  • src/main/resources/mappings/structuremaps/zib2017-to-logical/Zib2017PatientToLogicalPatient.map
  • src/main/resources/mappings/structuremaps/pzp2017-to-logical/Pzp2017PatientToLogicalPatient.map
  • src/main/resources/mappings/structuremaps/logical-to-nlcore/LogicalPatientToNlcorePatient.map
  • src/main/resources/mappings/structuremaps/logical-to-eubase/LogicalPatientToEubasePatient.map
  • src/main/resources/mappings/structuremaps/logical-to-pzp/LogicalPatientToPzp2020Patient.map

Problem

  • src/main/resources/mappings/structuremaps/bgz2017-to-logical/Bgz2017ProblemToLogicalProblem.map
  • src/main/resources/mappings/structuremaps/nlcore2017-to-logical/Nlcore2017ProblemToLogicalProblem.map
  • src/main/resources/mappings/structuremaps/zib2017-to-logical/Zib2017ProblemToLogicalProblem.map
  • src/main/resources/mappings/structuremaps/logical-to-nlcore/LogicalProblemToNlcoreProblem.map
  • src/main/resources/mappings/structuremaps/logical-to-eubase/LogicalProblemToEubaseCondition.map

Procedure

  • src/main/resources/mappings/structuremaps/bgz2017-to-logical/Bgz2017ProcedureToLogicalProcedure.map
  • src/main/resources/mappings/structuremaps/nlcore2017-to-logical/Nlcore2017ProcedureToLogicalProcedure.map
  • src/main/resources/mappings/structuremaps/zib2017-to-logical/Zib2017ProcedureToLogicalProcedure.map
  • src/main/resources/mappings/structuremaps/pzp2017-to-logical/Pzp2017ProcedureToLogicalProcedure.map
  • src/main/resources/mappings/structuremaps/logical-to-nlcore/LogicalProcedureToNlcoreProcedureEvent.map
  • src/main/resources/mappings/structuremaps/logical-to-eubase/LogicalProcedureToEubaseProcedure.map
  • src/main/resources/mappings/structuremaps/logical-to-pzp/LogicalProcedureToPzp2020Procedure.map

Functional Or Mental Status

  • src/main/resources/mappings/structuremaps/bgz2017-to-logical/Bgz2017FunctionalOrMentalStatusToLogicalFunctionalOrMentalStatus.map
  • src/main/resources/mappings/structuremaps/nlcore2017-to-logical/Nlcore2017FunctionalOrMentalStatusToLogicalFunctionalOrMentalStatus.map
  • src/main/resources/mappings/structuremaps/zib2017-to-logical/Zib2017FunctionalOrMentalStatusToLogicalFunctionalOrMentalStatus.map
  • src/main/resources/mappings/structuremaps/logical-to-nlcore/LogicalFunctionalOrMentalStatusToNlcoreFunctionalOrMentalStatus.map
  • src/main/resources/mappings/structuremaps/logical-to-eubase/LogicalFunctionalOrMentalStatusToEubaseMedicalTestResult.map

AllergyIntolerance

  • src/main/resources/mappings/structuremaps/zib2017-to-logical/Zib2017AllergyIntoleranceToLogicalAllergyIntolerance.map
  • src/main/resources/mappings/structuremaps/logical-to-nlcore/LogicalAllergyIntoleranceToNlcoreAllergyIntolerance.map
  • src/main/resources/mappings/structuremaps/logical-to-eubase/LogicalAllergyIntoleranceToEubaseAllergyIntolerance.map

Encounter

  • src/main/resources/mappings/structuremaps/zib2017-to-logical/Zib2017EncounterToLogicalEncounter.map
  • src/main/resources/mappings/structuremaps/pzp2017-to-logical/Pzp2017EncounterToLogicalEncounter.map
  • src/main/resources/mappings/structuremaps/logical-to-nlcore/LogicalEncounterToNlcoreEncounter.map
  • src/main/resources/mappings/structuremaps/logical-to-pzp/LogicalEncounterToPzp2020Encounter.map

CareTeam

  • src/main/resources/mappings/structuremaps/nlcore2017-to-logical/Nlcore2017CareTeamToLogicalCareTeam.map
  • src/main/resources/mappings/structuremaps/logical-to-nlcore/LogicalCareTeamToNlcoreCareTeam.map

Appointment

  • src/main/resources/mappings/structuremaps/eafspraak2017-to-logical/Eafspraak2017AppointmentToLogicalAppointment.map
  • src/main/resources/mappings/structuremaps/logical-to-r4/LogicalAppointmentToR4Appointment.map

Medication

  • src/main/resources/mappings/structuremaps/zib2017-to-logical/Zib2017MedicationAgreementToLogicalMedicationRequest.map
  • src/main/resources/mappings/structuremaps/zib2017-to-logical/Zib2017MedicationUseToLogicalMedicationStatement.map
  • src/main/resources/mappings/structuremaps/zib2017-to-logical/Zib2017AdministrationAgreementToLogicalMedicationDispense.map
  • src/main/resources/mappings/structuremaps/logical-to-eubase/LogicalMedicationRequestToEubaseMedicationRequest.map
  • src/main/resources/mappings/structuremaps/logical-to-eubase/LogicalMedicationStatementToEubaseMedicationStatement.map
  • src/main/resources/mappings/structuremaps/logical-to-r4/LogicalMedicationDispenseToR4MedicationDispense.map

EPS

  • src/main/resources/mappings/structuremaps/logical-to-eps/LogicalPatientToEpsPatient.map
  • src/main/resources/mappings/structuremaps/logical-to-eps/LogicalProblemToEpsCondition.map
  • src/main/resources/mappings/structuremaps/logical-to-eps/LogicalProcedureToEpsProcedure.map
  • src/main/resources/mappings/structuremaps/logical-to-eps/LogicalAllergyIntoleranceToEpsAllergyIntolerance.map
  • src/main/resources/mappings/structuremaps/logical-to-eps/LogicalMedicationRequestToEpsMedicationRequest.map
  • src/main/resources/mappings/structuremaps/logical-to-eps/LogicalMedicationStatementToEpsMedicationStatement.map
  • src/main/resources/mappings/structuremaps/logical-to-eps/LogicalConsentToEpsConsent.map
  • src/main/resources/mappings/structuremaps/logical-to-eps/LogicalPractitionerToEpsPractitioner.map
  • src/main/resources/mappings/structuremaps/logical-to-eps/LogicalPractitionerRoleToEpsPractitionerRole.map
  • src/main/resources/mappings/structuremaps/logical-to-eps/LogicalDeviceToEpsDevice.map
  • src/main/resources/mappings/structuremaps/logical-to-eps/LogicalDeviceUseStatementToEpsDeviceUseStatement.map

The EPS maps reuse logical-to-eubase maps or neutral shared logical-to-R4 copy groups. They do not import PZP target maps.

Metadata

  • src/main/resources/mappings/structuremaps/bgz2017-to-logical/Bgz2017MetaDataToLogicalMetadata.map
  • src/main/resources/mappings/structuremaps/logical-to-r4/LogicalMetadataToR4Provenance.map

PZP ACP Resource Profiles

  • src/main/resources/mappings/structuremaps/pzp2017-to-logical/Pzp2017ConsentToLogicalConsent.map
  • src/main/resources/mappings/structuremaps/pzp2017-to-logical/Pzp2017RelatedPersonToLogicalRelatedPerson.map
  • src/main/resources/mappings/structuremaps/pzp2017-to-logical/Pzp2017PractitionerToLogicalPractitioner.map
  • src/main/resources/mappings/structuremaps/pzp2017-to-logical/Pzp2017PractitionerRoleToLogicalPractitionerRole.map
  • src/main/resources/mappings/structuremaps/pzp2017-to-logical/Pzp2017CommunicationRequestToLogicalCommunicationRequest.map
  • src/main/resources/mappings/structuremaps/pzp2017-to-logical/Pzp2017DeviceToLogicalDevice.map
  • src/main/resources/mappings/structuremaps/pzp2017-to-logical/Pzp2017DeviceUseStatementToLogicalDeviceUseStatement.map
  • src/main/resources/mappings/structuremaps/pzp2017-to-logical/Pzp2017GoalToLogicalGoal.map
  • src/main/resources/mappings/structuremaps/pzp2017-to-logical/Pzp2017ObservationToLogicalObservation.map
  • src/main/resources/mappings/structuremaps/logical-to-pzp/LogicalConsentToPzp2020Consent.map
  • src/main/resources/mappings/structuremaps/logical-to-pzp/LogicalConsentToPzp2020AdvanceDirective.map
  • src/main/resources/mappings/structuremaps/logical-to-pzp/LogicalConsentToPzp2020TreatmentDirective.map
  • src/main/resources/mappings/structuremaps/logical-to-pzp/LogicalRelatedPersonToPzp2020RelatedPerson.map
  • src/main/resources/mappings/structuremaps/logical-to-pzp/LogicalPractitionerToPzp2020Practitioner.map
  • src/main/resources/mappings/structuremaps/logical-to-pzp/LogicalPractitionerRoleToPzp2020PractitionerRole.map
  • src/main/resources/mappings/structuremaps/logical-to-pzp/LogicalCommunicationRequestToPzp2020CommunicationRequest.map
  • src/main/resources/mappings/structuremaps/logical-to-pzp/LogicalDeviceToPzp2020Device.map
  • src/main/resources/mappings/structuremaps/logical-to-pzp/LogicalDeviceUseStatementToPzp2020DeviceUseStatement.map
  • src/main/resources/mappings/structuremaps/logical-to-pzp/LogicalGoalToPzp2020Goal.map
  • src/main/resources/mappings/structuremaps/logical-to-pzp/LogicalObservationToPzp2020Observation.map

QuestionnaireResponse Extraction

  • src/main/resources/mappings/structuremaps/pzp-questionnaire/Pzp2017QuestionnaireResponseToLogicalQuestionnaireForm.map
  • src/main/resources/mappings/structuremaps/pzp-questionnaire/Pzp2020QuestionnaireResponseToLogicalQuestionnaireForm.map
  • src/main/resources/mappings/structuremaps/pzp-questionnaire/PzpQuestionnaireAnswerCopies.map
  • src/main/resources/mappings/structuremaps/pzp-questionnaire/LogicalQuestionnaireFormToExtractionBundle.map

These maps do not directly produce final PZP 2020 resources. They normalize a completed PZP form and create extraction entries with logical clinical resource bodies. The generic manifest-driven assembler runs those logical resources through the existing logical-to-PZP 2020 maps.

Supporting Maps

Supporting maps are also part of the concrete runtime:

  • src/main/resources/mappings/structuremaps/shared/FhirDatatypeCopies.map

QuestionnaireResponse extraction also uses local ConceptMaps under src/main/resources/mappings/conceptmaps for answer-to-boolean conversion, code display normalization, default codings, UZI specialty normalization, treatment directive mapping, contact-point use, and observation method mapping.

How To Read A Map

The maps typically follow the same shape:

  1. identify the source profile family
  2. normalize source semantics into the logical model
  3. select the target family
  4. map the logical fields into the profile-specific R4 resource

That pattern is deliberate. It keeps source semantics, intermediate semantics, and target semantics visible as separate steps.

Runtime Portability

The .map files use FHIR StructureMap syntax and HAPI parses them as StructureMap resources. Execution is local to this translator: CumuluzStructureMapEngine walks the parsed maps and implements the subset needed for deterministic writes into typed R4 targets, local logical models, ConceptMap-backed translate(...), and direct target-child bindings.

Do not assume these maps are drop-in portable to another StructureMap engine. Another engine may parse most files, but it would need equivalent runtime support for the local logical StructureDefinitions, the STU3-shaped ingest context, local ConceptMaps, and the target-write behavior used by the local executor.