DEV Community: vitagroup HIP

Part 4: Searching for data

vitagroup HIP — Mon, 17 Mar 2025 10:04:22 +0000

Series by Stefan Spiska, Senior Backend Developer, PEN, vitagroup HIP

Part 4 of the series "Vendor neutral interoperability with openEHR and HL7 FHIR"

In the previous sections, it was explored how to create patients and store data in HIP. One of the most significant advantages of an open data platform with standardized formats is the ability to search for data flexibly - not just by ID but using various clinical or administrative criteria.

Example use case: Searching for systolic blood pressure in a specific Encounter

Let’s assume one wants to find all systolic blood pressure measurements in a specific Encounter, where the value is ≥ 100 mmHg.

FHIR Approach

In FHIR, one would search for Observation components with:

code = 8480-6 (Systolic Blood Pressure)
valueQuantity.value ≥ 100
encounter = Encounter/74aa52fc-6aff-46aa-9848-e37b013354

So the FHIR search request would be :

Observation/?component-code-value-quantity=8480-6$ge100&encounter=74aa52fc-6aff-46aa-9848-e37b013354

Translating FHIR Search to openEHR Query

Since the FHIR Observation components was mapped to the openEHR archetype openEHR-EHR-OBSERVATION.blood_pressure.v2, the FHIR search has to be translated into an openEHR query.

Thankfully, EHRbase, as an openEHR server, provides a powerful standardised query language called AQL (Archetype Query Language).

Think of AQL as a combination of XPath and SQL, allowing us to query structured clinical data based on openEHR's Reference Model (RM).

Basic AQL Queries

Selecting Compositions:

SELECT c FROM COMPOSITION c

would retrieve all Compositions.

Selecting Observations:

 SELECT o FROM OBSERVATION o

This retrieves all Observations wich in openEHR are part of a Composition.

Selecting specific data fields:

SELECT c/uid/value,c/context/start_time/value COMPOSITION c

As we can see from the RM-model definition EHR Information Model

c/uid/value: Navigate to uid field which is of type UID_BASED_ID and thus we can navigate the value field which contains a String containing the uid of this composition
c/context/start_time/value: Is the display of start time of the composition

For archetypes objects like openEHR-EHR-OBSERVATION.blood_pressure.v1 one has to look up the archetypes to get the parts.

SELECT 
o/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude,
o/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/units
FROM OBSERVATION o[openEHR-EHR-OBSERVATION.blood_pressure.v1]

Previously it was shown that /data[at0001]/events[at0006]/data[at0003]/items[at0004] in the archetype openEHR-EHR-OBSERVATION.blood_pressure.v2 points to the element containing the DV_QUANTITY with the systolic blood pressure and thus we add the relative parts.

value/magnitude
value/units

To get the magnitude and unit.

Note that

o[openEHR-EHR-OBSERVATION.blood_pressure.v1]

is just a shorthand for

o[archetype_node_id ='openEHR-EHR-OBSERVATION.blood_pressure.v1']

which ensures that only Blood Pressure observations are queried.

Joining data across multiple structures

We can also “join“ objects which are contained in each other using the the CONTAINS clause:

SELECT
   c/uid/value,
   c/context/start_time/value,
   o/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude
FROM EHR e 
  CONTAINS COMPOSITION c 
    contains OBSERVATION o[openEHR-EHR-OBSERVATION.blood_pressure.v1]

CONTAINS defines hierarchical relationships within an EHR, similar to a structured join in SQL. In this query, it ensures that Compositions are selected from the EHR, and only Observations within those Compositions are retrieved. This allows querying structured clinical data while maintaining the context of where it is stored.

So each row

{
  "rows": [
    [
      "635775de-84fb-4ce4-bf65-71249f28953a::cdr-core-sanity-check.hip-cdr-core-ehrbase-enterprise-cdr-core-dev1.dev3.vg-hip.dev::1",
      "2022-02-03T04:05:06",
      120.0
    ],
    [
      "7d99ae32-64e3-40a7-a11f-5c5fb1aafbc0::cdr-core-sanity-check.hip-cdr-core-ehrbase-enterprise-cdr-core-dev1.dev3.vg-hip.dev::1",
      "2022-03-03T00:00:00",
      123.0
    ]
  ]
}

will represent a systolic blood pressure measurement together with the ehr id (patient identifier ) and start time.

Searching by Encounter

In the last part ist was shown how encounters are represented as Folders in the HIP, containing Compositions. Thus encounter = encounter/74aa52fc-6aff-46aa-9848-e37b013354 can be represented as

SELECT c 
FROM FOLDER f [openEHR-EHR-FOLDER.episode_of_care.v1]
      contains COMPOSITION c 
WHERE 
  f/uid/value = '74aa52fc-6aff-46aa-9848-e37b013354'

Putting everything together

Since component-code was mapped to data[at0001]/events[at0006]/data[at0003]/items[at0004] in the Archetype openEHR-EHR-OBSERVATION.blood_pressure.v2 and the Composition was stored in an Encounter with Id = 74aa52fc-6aff-46aa-9848-e37b013354 the FHIR search

Observation/?component-code-value-quantity=8480-6$ge100&encounter=74aa52fc-6aff-46aa-9848-e37b013354

can be represented as the following AQL query:

SELECT DISTINCT c 
FROM FOLDER f [openEHR-EHR-FOLDER.episode_of_care.v1]
      contains COMPOSITION c 
              contains OBSERVATION o[openEHR-EHR-OBSERVATION.blood_pressure.v2]
WHERE 
  f/uid/value = '74aa52fc-6aff-46aa-9848-e37b013354'
AND
  o/data[at0001]/events[at0006]/data[at0003]/items[at0004]/magnitude >= 100

The HIP-Bridge will read the mappings to automatically transform FHIR search Request to AQL, and transforming the resulting data back to FHIR.

Thus through the capabilities of the HIP Bridge, users can query data in two ways: using FHIR Search or the Archetype Query Language. This ensures to meet the needs to system integrations and application developers alike with different views and access mechanisms on the data.

Conclusion

In this blog series, we have explored how HIP (Health Intelligence Platform) enables vendor neutral interoperability by integrating legacy healthcare data into openEHR and HL7 FHIR. We have seen how data can be transformed into FHIR and openEHR formats, ensuring structured, standardised, and semantically rich data storage.

By leveraging PSPL (Protocol Specific Path Language) and AQL (Archetype Query Language), we demonstrated how data can be mapped, stored, and efficiently queried, allowing healthcare providers to move beyond simple ID-based searches and perform complex, criteria-driven queries. This level of data accessibility and interoperability empowers organizations to build advanced health applications, enhance clinical decision making, and improve patient outcomes.

With a vendor neutral and standards based approach, HIP provides a future proof foundation for seamless data exchange between healthcare systems. As healthcare continues to evolve, adopting open data models and interoperability frameworks like openEHR and FHIR will be essential for achieving truly connected and patient centric healthcare ecosystems.

About the Author – Stefan Spiska

Stefan Spiska is a Senior Software Developer at vitagroup, specializing in interoperability and open platform development in the E-Health sector. With extensive experience in healthcare IT, he is a core developer for the open source openEHR platform, EHRbase (ehrbase.org).

Part 3: Storing a Blood pressure measurement

vitagroup HIP — Mon, 17 Mar 2025 10:04:12 +0000

Series by Stefan Spiska, Senior Backend Developer, PEN, vitagroup HIP

Part 3 of the series "Vendor neutral interoperability with openEHR and HL7 FHIR"

Previous examples handled the management of non medical data in HIP.

Let’s jump to the management of medical data with the example of creating and and in a later part searching a blood pressure in HIP.

Let’s assume that a hospital has developed an app on the HIP where patients in follow up care can document their blood pressure measurements. The app sends this data as an HL7 FHIR Observation to HIP:

{
  "resourceType" : "Observation",
  "id" : "blood-pressure",
  "meta" : {
    "profile" : ["http://hl7.org/fhir/StructureDefinition/vitalsigns"]
  },
  "identifier" : [{
    "system" : "urn:ietf:rfc:3986",
    "value" : "urn:uuid:187e0c12-8dd2-67e2-99b2-bf273c878281"
  }],
  "status" : "final",
  "category" : [{
    "coding" : [{
      "system" : "http://terminology.hl7.org/CodeSystem/observation-category",
      "code" : "vital-signs",
      "display" : "Vital Signs"
    }]
  },
  {
    "coding" : [{
      "system" : "http://loinc.org",
      "code" : "85354-9",
      "display" : "Blood pressure panel with all children optional"
    }]
  }],
  "code" : {
    "coding" : [{
      "system" : "http://loinc.org",
      "code" : "85354-9",
      "display" : "Blood pressure panel with all children optional"
    }],
    "text" : "Blood pressure systolic & diastolic"
  },
 "subject" : {
    "reference" : "https://hip.org/Patient/patient-example-01"
  },


  "effectiveDateTime" : "2012-09-17"

  "component" : [{
    "code" : {
      "coding" : [{
        "system" : "http://loinc.org",
        "code" : "8480-6",
        "display" : "Systolic blood pressure"
      }
    },
    "valueQuantity" : {
      "value" : 107,
      "unit" : "mmHg",
      "system" : "http://unitsofmeasure.org",
      "code" : "mm[Hg]"
    }
  },
  {
    "code" : {
      "coding" : [{
        "system" : "http://loinc.org",
        "code" : "8462-4",
        "display" : "Diastolic blood pressure"
      }]
    },
    "valueQuantity" : {
      "value" : 60,
      "unit" : "mmHg",
      "system" : "http://unitsofmeasure.org",
      "code" : "mm[Hg]"
    },

}

openEHR, FHIR – Semantic binding

HIP uses EHRbase for data storage which implements the openEHR standard. The biggest difference between openEHR and FHIR is how the semantic bindings are done.

If one looks at the FHIR definition we get a syntactic structure in the form of an OBSERVATION which contains a list of components which in this case contains a Quantity. But only when we look at the coding and see a LOINC code of 8462-4 then we know from a semantic standpoint that value Quantity represent the diastolic blood pressure.

In openEHR on the other side we have archetypes which represent a specific medical domain object like a
blood pressure:

The important part here is that this is a maximal data set created by medical professionals, ensuring consistency and completeness of clinical data across systems and use-cases.

Creating an openEHR Template

To integrate FHIR Observation data into HIP, one can use the openEHR Archetype Designer to create a Template (demo-mapping.ehrbase.org.v0).

The template acts as a structured clinical model, combining multiple openEHR Archetypes.
One can disable elements based on what data are needed (e.g., just systolic and diastolic values).
Since a template is a collection of constraints on archetypes, interoperability between different templates is ensured.

Mapping FHIR to openEHR Using PSPL

Similar to the HL7 v2 example in the previous part, one can use PSPL to define mappings between FHIR and openEHR.

For example now on can easily define the mappings for the component with code 8480-6 to the path /data[at0001]/events[at0006]/data[at0003]/items[at0004]/value in the archetype openEHR-EHR-OBSERVATION.blood_pressure.v2 which will contain a Dv_Quantity which represents the systolic blood pressure.

{
  "storageClass": "DvQuantity",
  "storagePath": "/content[openEHR-EHR-OBSERVATION.blood_pressure.v2]/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value",
  "attributes": {
    "magnitude": {
      "type": "rw",
      "dataType": "Double",
      "sourcePath": "component[isList: true, where: 'code.coding[isList: true].code=\"8480-6\"'].valueQuantity.value"
    },
    "units": {
      "type": "rw",
      "dataType": "String",
      "sourcePath": "component[isList: true, where: 'code.coding[isList: true].code=\"8480-6\"'].valueQuantity.code"
    },
    "unitsSystem": {
      "type": "rw",
      "dataType": "String",
      "sourcePath": "component[isList: true, where: 'code.coding[isList: true].code=\"8480-6\"'].valueQuantity.system"
    },
    "unitsDisplayName": {
      "type": "rw",
      "dataType": "String",
      "sourcePath": "component[isList: true, where: 'code.coding[isList: true].code=\"8480-6\"'].valueQuantity.unit"
    }
  }
}

By applying similar mappings for all components, the FHIR OBSERVATION can be transformed into an openEHR COMPOSITION (the root class of each document) based on the template.

{
  "_type": "COMPOSITION",
  "name": {
    "_type": "DV_TEXT",
    "value": "demo-mapping.ehrbase.org.v0"
  },
  "archetype_details": {
    "archetype_id": {
      "value": "openEHR-EHR-COMPOSITION.report.v1"
    },
    "template_id": {
      "value": "demo-mapping.ehrbase.org.v0"
    },
    "rm_version": "1.0.4"
  },
  "language": {
    "_type": "CODE_PHRASE",
    "terminology_id": {
      "_type": "TERMINOLOGY_ID",
      "value": "ISO_639-1"
    },
    "code_string": "en"
  },
  "territory": {
    "_type": "CODE_PHRASE",
    "terminology_id": {
      "_type": "TERMINOLOGY_ID",
      "value": "ISO_3166-1"
    },
    "code_string": "DE"
  },
  "category": {
    "_type": "DV_CODED_TEXT",
    "value": "event",
    "defining_code": {
      "_type": "CODE_PHRASE",
      "terminology_id": {
        "_type": "TERMINOLOGY_ID",
        "value": "openehr"
      },
      "code_string": "433"
    }
  },
  "composer": {
    "_type": "PARTY_IDENTIFIED",
    "name": "Max Mustermann"
  },
  "context": {
    "_type": "EVENT_CONTEXT",
    "start_time": {
      "_type": "DV_DATE_TIME",
      "value": "2012-09-17T00:00:00"
    },
    "setting": {
      "_type": "DV_CODED_TEXT",
      "value": "home",
      "defining_code": {
        "_type": "CODE_PHRASE",
        "terminology_id": {
          "_type": "TERMINOLOGY_ID",
          "value": "openehr"
        },
        "code_string": "225"
      }
    }
  },
  "content": [
    {
      "_type": "OBSERVATION",
      "name": {
        "_type": "DV_CODED_TEXT",
        "value": "Blood pressure panel with all children optional",
        "defining_code": {
          "_type": "CODE_PHRASE",
          "terminology_id": {
            "_type": "TERMINOLOGY_ID",
            "value": "http://loinc.org"
          },
          "code_string": "8480-6"
        }
      },
      "archetype_details": {
        "archetype_id": {
          "value": "openEHR-EHR-OBSERVATION.blood_pressure.v2"
        },
        "rm_version": "1.0.4"
      },
      "language": {
        "_type": "CODE_PHRASE",
        "terminology_id": {
          "_type": "TERMINOLOGY_ID",
          "value": "ISO_639-1"
        },
        "code_string": "en"
      },
      "encoding": {
        "_type": "CODE_PHRASE",
        "terminology_id": {
          "_type": "TERMINOLOGY_ID",
          "value": "IANA_character-sets"
        },
        "code_string": "ISO-10646-UTF-1"
      },
      "subject": {
        "_type": "PARTY_SELF"
      },
      "data": {
        "name": {
          "_type": "DV_TEXT",
          "value": "History"
        },
        "origin": {
          "_type": "DV_DATE_TIME",
          "value": "2012-09-17T00:00:00"
        },
        "events": [
          {
            "_type": "POINT_EVENT",
            "name": {
              "_type": "DV_TEXT",
              "value": "Any event"
            },
            "time": {
              "_type": "DV_DATE_TIME",
              "value": "2012-09-17T00:00:00"
            },
            "data": {
              "_type": "ITEM_TREE",
              "name": {
                "_type": "DV_TEXT",
                "value": "blood pressure"
              },
              "items": [
                {
                  "_type": "ELEMENT",
                  "name": {
                    "_type": "DV_TEXT",
                    "value": "Systolic"
                  },
                  "value": {
                    "_type": "DV_QUANTITY",
                    "units": "mm[Hg]",
                    "magnitude": 107
                  },
                  "archetype_node_id": "at0004"
                },
                {
                  "_type": "ELEMENT",
                  "name": {
                    "_type": "DV_TEXT",
                    "value": "Diastolic"
                  },
                  "value": {
                    "_type": "DV_QUANTITY",
                    "units": "mm[Hg]",
                    "magnitude": 60.0
                  },
                  "archetype_node_id": "at0005"
                }
              ],
              "archetype_node_id": "at0003"
            },
            "archetype_node_id": "at0006"
          }
        ],
        "archetype_node_id": "at0001"
      },
      "archetype_node_id": "openEHR-EHR-OBSERVATION.blood_pressure.v2"
    }
  ],
  "archetype_node_id": "openEHR-EHR-COMPOSITION.report.v1"
}

Thus similar to the case of the ADT message in the previous part whenever a FHIR Observation is sent from the App, a Composition with template demo-mapping.ehrbase.org.v0 is created in EHRbase for the patient which is using the app.

Dealing with encounter

There is a small thing which remains. In FHIR the encounter for an observation is represented by a reference

{
...
"encounter":{
    "reference" : "https://hip.org//74aa52fc-6aff-46aa-9848-e37b01335411"
    }
}

In openEhr, Compositions can be put into a virtual directory to represent logical ordering of things:

So the HIP-Bridge will for each encounter create a Folder and put the Composition in the folder representing the Encounter. We will see in the next part how to use this to quickly query for all Compositions in an Encounter.

Part 1: Architecture of the HIP-Bridge

vitagroup HIP — Mon, 17 Mar 2025 10:03:48 +0000

Series by Stefan Spiska, Senior Backend Developer, PEN, vitagroup HIP

Part 1 of the series "Vendor neutral interoperability with openEHR and HL7 FHIR"

To ensure interoperability, data must be extracted from 3rd party applications like HIS (Hospital Information System) or LIS (Laboratory information systems), transformed into open, vendor-neutral formats, and stored within the Platform via the HIP-Bridge:

In HIP, non medical data is stored separately from medical data in a HL7 FHIR server. This separation enables fine grained access control, enhancing privacy and security.

Structured medical data is primarily stored in HIP EHRbase, following the openEHR standard. This ensures that all data is standardised using clinical information models, known as Archetypes and Templates.

The HIP-Bridge serves as the central integration point for reading and writing data, facilitating data transformation between different formats. Through connectors, it supports data exchange using multiple standard and legacy data formats, ensuring seamless integration with existing healthcare systems.

Note: HIP Bridge is backed by a powerful mapping framework, where the storage system of the data can be flexible defined. Therefore, medical data could also be stored in the FHIR Server, as well as non medical data can be stored in EHRbase.

Vendor neutral interoperability with openEHR and HL7 FHIR

vitagroup HIP — Mon, 17 Mar 2025 10:03:38 +0000

Series by Stefan Spiska, Senior Backend Developer, PEN, vitagroup HIP

In today's healthcare landscape, providers often find their data scattered across multiple applications, many of which offer only a limited and fragmented view of patient information due to reliance on legacy data formats. This lack of interoperability is a considerable challenge to achieve efficient and safe patient treatment.

Open health data platforms, such as the Health Intelligence Platform (HIP), aim to bridge this gap by integrating and transforming medical data. By providing a vendor neutral, standardised, and semantically rich representation of patient data, these platforms enable seamless data integration and the development of health applications based on a standardized view of the data.

In this series of articles, we will explore the integration component of HIP - the HIP-Bridge. This component acts as a configurable facade, enabling integration with legacy systems while storing data in open, standardised formats such as openEHR and HL7 FHIR.

What to expect in this series

Part 1: An overview of the general architecture of the HIP-Bridge.
Part 2: How to integrate with a hospital information system (HIS) to to create patient and encounter data in HIP.
Part 3: The process of storing clinical data within the system.
Part 4: How to efficiently search for and retrieve medical data.

Part 2: Creating a Patient and Encounter from the HIS via HL7v2

vitagroup HIP — Thu, 13 Mar 2025 10:55:46 +0000

Series by Stefan Spiska, Senior Backend Developer, PEN, vitagroup HIP

Part 2 of the series "Vendor neutral interoperability with openEHR and HL7 FHIR"

The first step in integration is typically patient onboarding. In most hospital settings, when a patient is created in the Hospital Information System (HIS), other systems within the hospital are notified by sending an HL7 v2 ADT message, such as the following:

MSH|^~\&|MIRTH|MIRTH_CONNECT|HIS001|MIRTH_CONNECT|20231010121200||ADT^A01|MSG0000001|P|2.3|||NE|NE|CO|8859/1|ES-CO
PID|||6537077^^^^CC||Smith^John||19860705|M
PV1||I|||||||||||||||||22cce64c-8ea1-4ac9-8974-163087171c85

HL7 v2 defines a set of structured messages, each consisting of different segments separated by line breaks. Each segment is made up of fields separated by a pipe (|), which can be further divided into components (^) and subcomponents (&).

Common HL7 v2 Segments

MSH (Message Header): Contains metadata about the message.
PID (Patient Identification): Holds patient demographic details.
PV1 (Patient Visit): Captures information about the patient's hospital encounter.

Example Breakdown

MSH-9 (ADT^A01): Message type ADT (Admission, Discharge, Transfer) Admit/Visit Notification.
PID-5 (Smith^John): Patient Name.
** - PID-5.1 (Smith): Family Name.
** - PID-5.2 (John): Given Name.

When a patient is admitted, an HL7 ADT (Admission, Discharge, Transfer) message is generated by the Hospital Information System (HIS), to inform 3rd party systems in the hospital. The HIP HL7v2 Connector receives the HL7v2 mesages and forwards them towards HIP.

Convert HL7v2 to a FHIR Patient and a FHIR Encounter

PSLP - Protocol Specific Path Language

To facilitate data mapping between different formats, vitagroup developed PSPL (Protocol Specific Path Language) - a path based navigation and extraction language.

With PSPL, integration experts can define mappings between various data formats. Elements are identified using expressions similar to XPath or FHIRPath. The language supports operations such as traversal, selection, and filtering of hierarchical data models.

Using PSPL, we can define mappings:

The Patient Identification (PID) segment to a FHIR Patient resource
The Patient Visit (PV1) segment to a FHIR Encounter resource

Defining a Trigger Condition

Before applying mappings, we must define when they should be triggered. The following condition ensures that the mapping applies to any incoming message of type "ADT^A01" (Admit/Visit notification), as specified in the message header:

"createConditions": [
      {
        "condition" : "MSH.9",
        "anyExpectedValue" : [
          "ADT^A01"
        ]
      }
    ]

Mapping an HL7 v2 PID segment to a FHIR Patient resource

Next, we define a mapping between an HL7 v2.3 PID segment and an HL7 FHIR R4 Patient resource:

"sourceProtocol": "HL7v2",
    "sourceProtocolVersions": [
      "2.3"
    ],
    "sourceType": "PID",
    "storageProtocol": "FHIR",
    "storageProtocolVersion": "R4",
    "storageType": "Patient",

A series of mappings between segments and elements is then applied. The snippet below maps PID.5.1 (Family Name) to FHIR Patient’s name.family:

      {
        "storageClass": "String",
        "storagePath": "name[isList: true].family",
        "attributes": {
          "value": {
            "type": "rw",
            "sourcePath": "PID.5.1",
            "dataType": "String"
          }
        }
      }

The function isList: true ensures that the name element is represented as a JSON array instead of a single JSON object.

Resulting FHIR Patient Resource

Thus for the incoming Hl7 v2 message we create a Patient resource as follows:

{
  "resourceType": "Patient",
  "name": [
    {
      "family": "Smith",
      "given": [
        "John"
      ]
    }
  ]
...  
}

Mapping an HL7 v2 PV1 segment to a FHIR Encounter resource

Some transformations require additional logic. For instance, when creating an Encounter from the PV1 (Patient Visit) segment, PV1-2 contains Patient Class (Inpatient, Emergency, etc.). Since PV1-2 uses a HL7 v2 value set, it must be translated into the corresponding FHIR value set (FHIR Encounter Class ValueSet).

See the following Transformation definition:

{
...
  "definition": {
    "sourceProtocol": "HL7v2",
    "sourceProtocolVersions": [
      "2.3"
    ],
    "sourceType": "PV1",
    "storageProtocol": "FHIR",
    "storageProtocolVersion": "R4",
    "storageType": "Encounter",
    "transformations": [
      {
        "storageClass": "String",
        "storagePath": "class.code",
        "attributes": {
          "value": {
            "type": "rw",
            "sourcePath": "PV1.2[convert: '\"E\" -> \"EMER\"; \"I\" -> \"IMP\"; \"O\" -> \"AMB\"; \"P\" -> \"PRENC\";']",
            "dataType": "String"
          }
        }
      },
      {
        "storageClass": "String",
        "storagePath": "class.system",
        "attributes": {
          "value": {
            "type": "static",
            "sourcePath": "",
            "staticValue": "http://terminology.hl7.org/CodeSystem/v3-ActCode"
          }
        },
        "conditions": [
          {
            "sourcePath": "PV1.2",
            "anyExpectedValue": [
             "E","I","O","P"
           ]  
          }
        ]
      }
   ...   
    ],
...
    "createConditions": [
      {
        "condition" : "MSH.9",
        "anyExpectedValue" : [
          "ADT^A01"
        ]
      }
    ]
  }
}

Explanation of transformations

convert function:

Maps HL7 v2 PV1-2 codes (E, I, O, P) to the FHIR equivalent values (EMER, IMP, AMB, PRENC).

Static mapping for terminology system:

If a value from PV1-2 is found, a terminology system URL is added (http://terminology.hl7.org/CodeSystem/v3-ActCode).

As a Result we get a correct FHIR FHIR coding:

"class" : [{
    "coding" : [{
      "system" : "http://terminology.hl7.org/CodeSystem/v3-ActCode",
      "code" : "IMP"
    }]
  }]

For more complex scenarios a FHIR terminology service and concept maps can be used.

Linking the FHIR Encounter to the FHIR Patient

All that left is to connect the Patient and Encounter resource. With the following mapping we ensure that the created Encounter references the create Patient as subject.

{
...
  "definition": {
    "sourceProtocol": "HL7v2",
    "sourceProtocolVersions": [
      "2.3"
    ],
    "sourceType": "PV1",
    "storageProtocol": "FHIR",
    "storageProtocolVersion": "R4",
    "storageType": "Encounter",
    "transformations": [
      {
        "storageClass": "String",
        "storagePath": "subject.reference",
        "attributes": {
          "value": {
            "type": "rw",
            "sourcePath": "PID.3.1[isIdValue: 'Patient']",
            "dataType": "String"
          }
        }
      }      
   ...   
    ],
...
    "createConditions": [
      {
        "condition" : "MSH.9",
        "anyExpectedValue" : [
          "ADT^A01"
        ]
      }
    ]
  }
}

Final Workflow

Now, whenever an HL7 ADT message arrives at HIP, the defined mappings are triggered, and the HIP-Bridge executes the following actions:

Create a FHIR Patient Resource and a FHIR Encounter from the HL7 ADT message
Links the Encounter to the Patient
Stores Encounter and Patient in the FHIR-Store.
Should storing fail because the validation does not pass or any other error, a transaction rollback is conducted across all services to ensure data integrity.