Hierarchy Mappings

Hierarchy mappings are the most complex type of mappings. Sometimes, the hierarchy between a FHIR and an openEHR model does not align properly. For example, elements may exist on different levels in the models, leading to complications. The hierarchy mapping is always contained in the preprocessor using the hierarchy key. There can be only one hierarchy mapping; currently, we have not encountered a case where more than one is needed.

split

The simplest hierarchy mapping is related to events in openEHR. OBSERVATION archetypes in openEHR can contain a list of events. In FHIR, these events are sometimes represented by a resource for each one. Therefore, for each event in openEHR, one resource must be created.

The with: key indicates which paths are to be accessed and iterated if they are 0..n. The split key can contain either openEHR or fhir. The create method defines the element to create. In the case of a resource or archetype, this type is inferred by the FHIRconnect mapping file it is included in. The create method is executed for each occurrence of the correlating with statement.

As an example:

  openEhrConfig:
    archetype: openEHR-EHR-OBSERVATION.laboratory_test_result.v1
    revision: 1.2.5
  fhirConfig:
    structureDefinition: http://hl7.org/fhir/StructureDefinition/DiagnosticReport

preprocessor:
  hierarchy:
    with:
      fhir: "$resource"
      openehr: "$archetype/data[at0001]/events[at0002]"
    split:
      fhir:
        create: "resource"

For each occurrence of $archetype/data[at0001]/events[at0002], the split is executed. Each occurrence of an event (if there is more than one) will create a new DiagnosticReport.

The engine’s composition fields remain the same for each of these mappings. One could imagine this process as cloning the composition with one event each, making the processing 1-to-1.

Hierarchy and unique values

Another case for hierarchy mappings is creating a new element based on a specific filter.

A good example of this is the FHIR MedicationStatement. Without delving into the details of why the models are structured differently, there are several challenges to address.

In FHIR, the timing.event contained within the dosage element (see MedicationStatement) maps to the time of the EVENT in openEHR. Therefore, if there are three dosages in FHIR with different timing.event values, three separate EVENT elements must be created in the openEHR medication_statement archetype.

Another issue is the route of administration. In openEHR, the route of administration is contained in each medication_statement EVENT. However, in FHIR, this is part of the dosage element. A single MedicationStatement in FHIR can have three different dosages, each with a different route of administration. For each unique route of administration, a new medication_statement EVENT must be created in openEHR.

The same logic applies when mapping from openEHR to FHIR. In openEHR, each EVENT can contain a different medication, whereas in FHIR, each MedicationStatement resource can only describe one medication. So for each openEHR EVENT containing a different medication, a new resource needs to be created.

MappingHierarchies

The grammar enables this with the path and unique keys. To recap, the create: key specifies the type of element to be created. The path: key indicates where this element should be created. This is left empty if the element is the archetype or resource itself, as in the example shown at fhir:. The unique: key defines the condition that triggers the creation of the new element. The path in the unique: key relates to the with: method. For example, in the example, we want to split the data transformation based on dosages, so the with: path relates to dosage. This will not automatically transform the dosage and event as a normal with: would do. It is rather used as an indicator, as explained above.

preprocessor:
  hierarchy:
    with:
      fhir: "$resource.dosage"
      openehr: "$archetype/data[at0001]/events[at0002]"
    #    type: "HIERARCHY" # Not necessary since hierarchy is a unique key for hierarchy mappings
    split:
      fhir:
        create: "resource"
        unique:
          - "data[at0003]/items[openEHR-EHR-CLUSTER.medication.v2]/items[at0132]"
      openehr:
        create: "event"
        path: "$archetype/data[at0001]/events[at0002]"
        unique:
          - "route"
          - "timing.event" # If the route value differs per dosage slice, create a new event

To summarize:

  • From FHIR-to-openEHR, for each dosage with a different route and/or timing.event, create a new EVENT in openEHR.

  • From openEHR-to-FHIR, for each event in openEHR with a different medication name ([at0132]), create a new MedicationStatement resource in FHIR.