HL7 Version 2 to FHIR
1.0.0-ballot - ballot International flag

This page is part of the HL7 Version 2 to FHIR (v1.0.0-ballot: STU1 Ballot 1) based on FHIR (HL7® FHIR® Standard) R4. . For a full list of available versions, see the Directory of published versions

Mapping Guidelines

The mappings for this round of review are documented and published using a spreadsheet style format. This format allows for easy, side-by-side editing and review of from=to mappings with supporting information. At the same time, the content must be computable enabling a mapping engine to ingest the mappings to populate their base mappings for subsequent refinement.

To this end, the infrastructure is based on a number of FHIR ConceptMap profiles to capture the relevant data for message structure, segment, data type, and vocabulary mappings. Until such time that tools are available to directly edit the ConceptMaps, Google Spreadsheets are used to capture the mappings and populate the ConceptMaps in gitHub at regular intervals. Regardless of the tools used, as the displayed format will be spreadsheet style, we refer to the mappings as mapping spreadsheets.

The following provides a review for each of the types of spreadsheets the mapping and supporting information capture.

Mapping Spreadsheets

Mapping is authored using CSV files. The format of the mapping files varies depending on whether the V2 artifact being mapped is a Message, Segment, Data Type, or Table.

The spreadsheet title has a defined format to enable conversion from .csv into FHIR ConceptMap:

HL7 {Message|Segment|Data Type|Code System} - FHIR {R4|R5}: [{v2 Message Type|v2 Segment|v2 Data Type|v2 Table}]([{FHIR Resource|FHIR Data Type|FHIR Metadata Data Type|FHIR Vocabulary}-{QualifierName}]) </wbr>

Examples:

  • HL7 Message - FHIR R4: ADT_A01
  • HL7 Segment - FHIR R4: OBR[ServiceRequest]
  • HL7 Segment - FHIR R4: OBX[Observation-Component]
  • HL7 Data Type - FHIR R4: CQ[ServiceRequest.duration]

General Format/Approach

  • Regardless of the mapping spreadsheet, the spreadsheet is organized into three sections:
    • HL7 v2
      • The v2 elements being mapped.

    • Conditions
      • The condition(s), if any, that determine whether the v2 element is mapped
        • If there is no condition, the mapping must always be applied
    • HL7 FHIR
      • The FHIR element that the v2 element is mapped to.

  • Rows are listed in sequence of how they appear in the v2 standard.
    • The first column, Sort Order, provides a sort order that can re-create the original v2 standard sequence in case one opts to re-sort/filter the rows.
    • In general, the content in the spreadsheet is declarative, not procedural but when implementing a tool to perform transformations, implementers must consider that in some cases relationships do exist between constructed FHIR resources
      • For example, for messages, there may be dependencies between segments
        • For example, the PID segment will create a Patient resource which is then added to with the content of the PD1 segment and referenced by the Encounter resource
  • One v2 element will have one or more rows as multiple or different FHIR elements need to be populated.
    • Each row is executable on its own, whether it involves a different or the same v2 element.
    • When a single v2 element has multiple rows, the order of execution of the rows for that element should not be important
    • The sort order number will repeat when the v2 component is repeated to this end. For example, if ORC-2 Placer Order Number maps to two different FHIR elements, then both rows would have the same sort order number “2”.
  • A condition includes the following statements:
    • If computable, both a condition using:

      • the following easy to read syntax (referenced as Computable ANTLR - further documented here: ANTLR Condition Syntax)

        • IF X EQUALS “A”
        • IF X NOT EQUALS
        • IF X VALUED
        • IF X NOT VALUED
        • IF X NOT VALUED ERROR *** The mapper is to stop mapping of the Message and raise an error.
        • IF IN (“A”,”B”, “C”)
        • IF NOT IN (“A”,”B”, “C”)
        • IF X expression OR Y expression
        • IF NOT (X expression OR Y expression)
        • IF NOT (X expression AND Y expression)
        • IF X expression AND Y expression
        • IF ((X expression AND Y expression) OR C expression)
        • IF X LST.COUNT EQUALS ***LST.COUNT is the count of entries in the list at hand
        • IF X LST.COUNT NOT EQUALS
        • IF X LST.COUNT GREATER THAN
        • IF X LST.COUNT LESS THAN
        • IF X LST.COUNT GREATER THAN OR EQUALS
        • IF X LST.COUNT LESS THAN OR EQUALS
        • IF X LENGTH ***LENGTH is the physical length of the value
        • IF X LENGTH NOT EQUALS
        • IF X LENGTH GREATER THAN
        • IF X LENGTH LESS THAN
        • IF X LENGTH GREATER THAN OR EQUALS
        • IF X LENGTH LESS THAN OR EQUALS

      • The FHIRpath syntax (referenced as Computable FHIRpath)

    • If not computable or in addition to the computable condition further non-computable conditions must be considered as well (referenced as Narrative).
  • [n] Notation
    • Multiple v2 components within the same mapping spreadsheet may need to update the same instance of a FHIR element, or should yield a new instance of the same FHIR element. To distinguish whether the mappings are to the same or different FHIR element instance each FHIR element at the appropriate place in the path will use the [n] notation. Those FHIR elements with the same value in the same place in the path should apply the mapping to the same instance of that element as an addition to existing content.
      • Example: PID-13 Phone Number - Home and PID-14 Phone Number - Business are both mapped to Patient.telecom. However, they need to yield different instances. Thus, PID-13 maps to Patient.telecom[1] and PID-14 to Patient.telecom[2].
      • Exmample: If both PID and PD1 need to populate the same Patient resource instance, the Patient would be referenced as Patient[1] and Patient[1] so that the data from both segments appear in the same resource instance.
    • Note that this does not mean that there is a first and second slot where one is kept empty if not available in v2. Rather it just means they are to be different if both present.
    • If the mapping needs to yield multiple instances and the v2 value needs to be applied to multiple FHIR element instances, [each] is used.
      • Example: OBX-2 Observation Identifier needs to be mapped to all Observation.component.code instances if OBX-5 Value contains multiple values. The FHIR attribute being mapped to then states Observation.component[each].code.
    • If a mapping needs to use a specific numbe of instance the notation [n-m] is used.
      • Example: The XAD.1 Street Address component is mapped to Address.line one through three, which is represented as line[1-3] in the FHIR attribute column, that would then be followed by XAD.2 Other Designation referencing line[4]
    • While typically these notations are a suffix on the FHIR element it applies to, in Data Type mappings you may see these as seemingly a prefix. This would effectively apply to the FHIR element (typically an attribute) where that FHIR data type is actually referenced.
      • Example: [1].Contactpoint.value and [2].ContactPoint.value mapped to from the v2 XTN data type would reflect the first instance of the attribute repetition is actually used, e.g., Patient.telecom that can repeat and is mapped to from PID-13 and PID-14 which have the v2 XTN data type.
  • Other than as described in the [n] Notation above, a repeat of a segment in the message should yield a new instance of the FHIR resource it maps to, and each instance of a field within a segment a new instance of an attribute.
    • There are situations where the HL7 v2 message may include field repeats that the corresponding FHIR attribute does not accommodate. We have not yet consistently resolved with FHIR whether it should have the core standard extend its cardinality or use an extension. In the absence of clear guidance the implementer should determine whether a local extension is appropriate to be utilized.
  • Each mapping row includes comments to document any considerations for the mapping that can aid in further refining the mappings for local use.
  • Note that a FHIR attribute may be mapped to by both a segment field or a field component from another field in that segment, e.g., ROL-1 Role Instance ID and ROL-4 Role Person. That involves two separate spreadsheets for different compoents (segment spreadsheet and data type component) and therefore should be mapped to different instance of a FHIR attribute. In this example RelatedPerson.identifier.

Message Spreadsheet

  • HL7 v2
    • Sort Order
    • Identifier
      • Contains an xml/json like path using the HL7 v2 XML approach of [MessageStructure].[GroupName or CHOICE].[SegmentName] where there may be multiple Group Names in play.
      • When there is a segment in multiple places in the message structure where this path would yield the same string even though it involves different uses of the same segment, thus potentially different mappings, the main segment preceding the segment at hand will be included in front of that segment using a “:follow:” tag.
        • For example, the ARV segment is used after the PID and the PV1 in the ADT_A01 structure. There may be in either case other segments between the PID (or PV1) and the ARV. The identifier in both cases would be ADT_A01.ARV. To distinguish the two uses and likely mappings of ARV, the identifier will be ADT_A01:follow:PID.ARV for the ARV effectively related to the PID and ADT_A01:follow:PV1.ARV for the ARV effectively related to the PV1.
        • The primary segment it is related to will be used rather than any segments that may still be listed be between them (e.g., PD1) as they may not be present.
    • Syntax
      • Contains the first column of the Message Structure Table in the base standard.
      • This is included as it is a familiar format to understand the message structure using the { [ ] } brackets.
    • Name
      • The formal name of the segment or group
    • Cardinality (Min and Max)
      • The cardinality expressed numerically.
      • Note that “-1” is used for the max cardinality where v2 indicates it to be “*”.
    • Condition
  • HL7 FHIR
    • Primary Target
      • The FHIR resource that is the main resource that the v2 segment will map to.
    • Segment Map
      • The URL to the Segment Map that is to be used for the segment in this message structure in this location.
      • There may be multiple flavors of the segment maps to support different mappings. The flavor is appended to the end of the segment name using [] brackets, e.g., MSH[Provenance - Originator].
    • References
      • An assignment that indicates for the FHIR resource being mapped to the attribute that needs to reference a particular other resource. For example, a PV1 segement being mapped to an Encounter resource must reference the Patient resource that the PID earlier in the message was mapped to.

Segment Spreadsheet

  • HL7 v2
    • Sort Order
      • See the General Guidelines
      • If a FHIR attribute is required but there is no v2 element to map from, the sort order is “0”.
    • Identifier
      • Contains the formal Segment Name and Field Sequence according to the base standard using “-“ as the delimiter.
      • If the Sort Order is “0” this cell will be set to “Implied”.
    • Name
      • The formal name of the field in the most current published version
    • Data Type
      • The data type of the field in the most current published version if not deprecated
      • Otherwise it is the data type at the time it was deprecated and removed.
    • Cardinality (Min and Max)
      • The cardinality in the most current published version expressed numerically if not deprecated
      • Otherwise it reflects the cardinality at the time it was deprecated and removed.
  • Condition
  • HL7 FHIR
    • FHIR Attribute
      • The first column reflects an existing FHIR attribute in the target FHIR version.
      • When there is not a single attribute to point to, rather a v2 field needs to be mapped to multiple FHIR attribute, e.g., ORC-27 Quantity/Timing where the TQ data type components need to be mapped to multiple ServiceRequest attributes, then the label “$this” is used. Further mapping guidance is then provided in the Data Type mapping column.
      • The second column reflects a proposed extension. It will be expressed with extension-[name] (when suggested as a full extension) or extension??-[name] (when it is open whether to include it in core and pre-adopt, or a full extension). Once approved, the full extension paths will be put in the first column.
      • This approach will enable tooling to already process existing FHIR attributes and not have to create special handling for elements still being proposed.
    • Data Type
      • The FHIR attribute’s data type in the target FHIR version.
    • Cardinality (Min and Max)
      • The FHIR attribute’s minimum and maximum cardinality in the target FHIR version.
    • Data Type Mapping
      • The URL to the Data Type Map that is to be used for the attribute in this segment.
      • There may be multiple flavors of the data type maps to support different mappings. The flavor is appended to the end of the data type name using [] brackets, e.g., CWE[Coding].
    • Vocabulary Mapping
      • The URL to the Vocabulary Map that is to be used for the coded element for this attribute.
      • If the applicable HL7 v2 table is empty, e.g., user defined tables without examples, this cell will be blank.
      • This is used where the HL7 v2 data type is either CWE, CNE, CF, CE, ID, or IS while the HL7 FHIR data type is code, coding, Codeable Concept, of boolean.
    • Assignment
      • The value that is to be assigned to the FHIR Attribute referenced.
        • If it is to be set to a particular string, it is uses “string”.
        • If it is to be set to a value in a v2 element or FHIR attribute, the identifier for that element/attribute is stated, e.g., PID-3.1 or Patient.identifier.value.
        • If there is no specific string or variable that is to be used, then the instructions are included between // bars, e.g., /instructions/.
      • Note these can be combined if multiple values need to be concatenated together.

There are situations where the field/attribute cardinalities between v2 and FHIR do not match. These are highlighted in the mapping spreadsheet. Specifically, the following are causing potential challenges:

v2 Cardinality FHIR Cardinality Guidance
0..1 1..n When the v2 message can empty and FHIR requires an attribute to be valued, a nullFlavor is preferred to indicate why it is absent. The mapping will specify what the nullFavlor should be. However, it there is nullFlavor, then the local implementation of the mapping needs to determine what value should be used.
n..* n..1 When the v2 messages allows for multiple values in a field and FHIR only allows for one (after also considering the cardinalities within the FHIR data type that may apply), then the local implementation needs to decide which value is included in the first level field and which should go into an extension.
1..1 1..1 with conditions When there is conditional mapping, there may be a situation that occurs where the condition(s) would yield that nothing is to be mapped, but FHIR requires a value. If that is the result of a valid set of conditions, and there is no nullFlavor that is applicable, then the local implementation of the mapping needs to determine what value should be used.

Note generally that extensions will be pursued for those situations where we know that actual implementations would run into this challenge, but will not pursue those until somebody indicates they need that. Where an upcoming FHIR version includes the attribute of interest we will use that as an extension using the format http://hl7.org/fhir/[version]/StructureDefinition/extension-[Path] according to the guidance provided here: http://hl7.org/fhir/versions.html#extensions.

Data Type mapping spreadsheets are only provided for complex v2 data types, not primitive v2 data types. In the case of v2 date and time data types (DTM, TM, ) the mapping is more complex as the format in v2 is not the same as in FHIR. One must use ISO 8601 (https://www.iso.org/iso-8601-date-and-time-format.html) to understand the variances and may use platform specific reformatting utilities/services to reformat the values. This would cover DTM=>dateTime, DTM=>date, DTM=>instant, DT=>dateTime, DT=>date, DT=>instant, TS=>dateTime, and TM=>time.

Data Type Spreadsheet

  • HL7 v2
    • Sort Order
    • Identifier
      • Contains the formal Data Type Name and Component Sequence according to the base standard using “.” as the delimiter.
      • In a couple of places, e.g., DTM data type, mapping is based on the physical position in the component. This will be noted using (pn)(x-y), e.g., DTM.(p1)(3-4)
        • (pn) - the part of the data type, e.g., (p1) for part 1.
        • (x-y) - the position within the part, e.g., (3-4). This may just be a single position, e.g., (5).
        • Note the use of parts is relatively arbitrary. In the case of DTM this is used for the year/month/date/time aspect vs. the time offset aspect. However, if one wants to use the absolute position of across parts, add the position start/end (x and y) to the last position of the prior part.
    • Name
      • The formal name of the data type in the most current published version
    • Data Type
      • The data type of the component in the most current published version if not deprecated
      • Otherwise it is the data type at the time it was deprecated and removed.
    • Cardinality (Min and Max)
      • The cardinality in the most current published version expressed numerically if not deprecated
      • Otherwise it reflects the cardinality at the time it was deprecated and removed.
  • Condition
  • HL7 FHIR
    • FHIR Attribute
      • The first column reflects an existing FHIR attribute in the target FHIR version.
      • When there is not a single attribute to point to, rather a v2 field needs to be mapped to multiple FHIR attribute, e.g., ORC-27 Quantity/Timing where the TQ data type components need to be mapped to multiple ServiceRequest attributes, then the label “$this” is used. Further mapping guidance is then provided in the Data Type mapping column.
      • When a multi-component data type maps to a primitive data type, e.g., CWE to string, then $value will indicate that it is acutally mapped to the single compomnet of the primitive data type as leaving it blank would indicate it is not being mapped.
      • The second column reflects a proposed extension. It will be expressed with extension-[name] (when suggested as a full extension) or extension??-[name] (when it is open whether to include it in core and pre-adopt, or a full extension). Once approved, the full extension paths will be put in the first column.
      • This approach will enable tooling to already process existing FHIR attributes and not have to create special handling for elements still being proposed.
    • Data Type
      • The FHIR attribute’s data type in the target FHIR version.
      • Like the v2 data type, a physical position may be used, e.g., with DataTime. See above for interpretation.
    • Cardinality (Min and Max)
      • The FHIR attribute’s minimum and maximum cardinality in the target FHIR version.
    • Data Type Mapping
      • The URL to the Data Type Map that is to be used for the component in this segment.
      • There may be multiple flavors of the data type maps to support different mappings. The flavor is appended to the end of the data type name using [] brackets, e.g., CWE[Coding].
    • Vocabulary Mapping
      • The URL to the Vocabulary Map that is to be used for the coded element for this attribute.
      • If the applicable HL7 v2 table is empty, e.g., user defined tables without examples, this cell will be blank.
      • This is used where the HL7 v2 data type is either CWE, CNE, CF, CE, ID, or IS while the HL7 FHIR data type is code, coding, Codeable Concept, of boolean.
    • Assignment
      • The value that is to be assigned to the FHIR Attribute referenced.
        • If it is to be set to a particular string, it is uses “string”.
        • If it is to be set to a value in a v2 element or FHIR attribute, the identifier for that element/attribute is stated, e.g., CWE.4 or Patient.identifier.value.
        • If there is no specific string or variable that is to be used, then the instructions are included between // bars, e.g., /instructions/.
      • Note these can be combined if multiple values need to be concatenated together.

Code System Spreadsheet

  • HL7 v2
    • Code
      • The code as used in v2 for the concept
    • Text
      • The text as used in v2 for the concept
    • Code System
      • The code system/value set that the concept is part of.
  • HL7 FHIR
    • Code
      • The code as used in FHIR for the concept in .coding.code
      • Note that when the mapping table is used for a boolean data type this reflects the value while there is no code system.
    • Display
      • The display value used in FHIR for the concept
      • Note that for the code and boolean data typese there is no display name.
    • Code System
      • The code system to be used when populating .coding.system
      • Note that for the code and boolean data types there is no declared coding system in the attribute.