Naming System Mapping

One challenging area when mapping between HL7 v2.x and HL7 FHIR is around the use of identifiers.

The FHIR Identifier datatype generally consists of an identifier and a system. For example, consider the following identifier for a Patient:

{
    "system": "http://example.com",
    "value": "12345"
}

In HL7 v2.x, identifiers are often represented in datatypes such as the CX (composite identifier) datatype.

The v2.x CX datatype has several key differences in functionality and common usage from the FHIR Identifier datatype:

• The concept of an identifier "system" in FHIR overlaps with several concepts in HL7 v2.x, including the "Assigning Authority" and the "Assigning Jurisdiction". For example, the FHIR system http://hl7.org/fhir/sid/us-ssn (US Social Security Number) implies an Assigning Authority of the Social Security Administration and an Assigning Jurisdiction of USA. As a result, there is no need for these two separate concepts to be represented within a FHIR identifier even though they are typically represented in an HL7 v2.x ID.

• FHIR uses URIs wherever possible to represent systems in a way that provides meaning to humans as well as to computers (e.g. http://example.com/mrn). In HL7 v2.x it is common to represent IDs as simple mnemonics (e.g. EXMPLMRN).

Default Mappings

By default, when converting a FHIR Identifier to an HL7 v2.x CX, the following mappings are applied:

Using NamingSystem for Mapping Identifiers

When using the HL7 v2.x Sending Endpoint module, the map_identifiers_using_namingsystem property may be used to enable the use of NamingSystem resources to convert FHIR Identifier.system values into HL7 v2.x identifiers.

When using this mode, for every Identifier.system value being converted, a search is performed for the NamingSystem resource where NamingSystem.uniqueId.value matches the given system.

If a match is found, the following fields are mapped:

When using the HL7 v2.x Listening Endpoint module, the map_identifiers_using_namingsystem_inbound property may be used to enable the use of NamingSystem resources to convert HL7 v2.x identifiers into FHIR Identifier.system values.

When using this mode, for every HL7 v2.x identifier value being converted, a search is performed for the NamingSystem resource where NamingSystem.uniqueId.value matches the given system.

If a match is found, the following fields are mapped:

Example

The following example shows a NamingSystem resource

{
  "resourceType": "NamingSystem",
  "type": {
    "coding": [
      {
        "system": "http://hl7.org/fhir/v2/0203",
        "code": "MR",
        "display": "Medical Record Number"
      }
    ]
  },
  "jurisdiction": [
    {
      "coding": [
        {
          "system": "urn:iso:std:iso:3166",
          "code": "US",
          "display": "United States of America (the)"
        }
      ]
    }
  ],
  "uniqueId": [
    {
      "type": "uri",
      "value": "http://example.com/mrns"
    },
    {
      "type": "other",
      "value": "EXMPL-IDS"
    }
  ]
}

This example could result is an identifier such as the following value in PID.3. PID|||12345^^^EXMPL-IDS^MR^^^^US&United States of America (the)&urn:iso:std:iso:3166

Using NamingSystem for Query Mapping

EAP

When the HL7 v2.x Listening Endpoint module is used to process queries such as QBP^Q23, the map_identifiers_using_namingsystem_inbound property enables NamingSystem mapping for Assigning Authority resolution. The query mapping differs from standard inbound message mapping in how it resolves Assigning Authorities to FHIR system URIs.

In a QBP^Q23 query, this applies to the Assigning Authority in QPD-3.4 (Identifier Assigning Authority) and each QPD-4.4 (What Domains Returned Assigning Authority) repetition.

Assigning Authority Resolution (v2.x → FHIR)

Smile CDR resolves an HL7 v2.x Assigning Authority (HD datatype) to a FHIR Identifier.system URI using NamingSystem resources.

The HD.2 (Universal ID) value is used to search for a NamingSystem resource with matching NamingSystem.uniqueId.value. If found, the first uniqueId with type uri is returned as the FHIR system URI. If no NamingSystem is found by Universal ID, Smile CDR falls back to searching by HD.1 (Namespace ID) using the same lookup logic. If no NamingSystem is found by either Universal ID or Namespace ID, an AE (Application Error) response is returned.

When map_identifiers_using_namingsystem_inbound is disabled, Smile CDR uses the Universal ID (HD.2) as the FHIR system URI. If Universal ID is not present, the Namespace ID (HD.1) is used instead.

{
  "resourceType": "NamingSystem",
  "uniqueId": [
    {
      "type": "oid",
      "value": "1.2.3.4.5",
      "preferred": true
    },
    {
      "type": "uri",
      "value": "http://example.com/mrns"
    },
    {
      "type": "other",
      "value": "MRNS"
    }
  ]
}

{
    "system": "http://example.com/mrns",
    "value": "6230"
}

Assigning Authority Population (FHIR → v2.x)

When building a response, Smile CDR converts each FHIR Identifier.system URI back to an HL7 v2.x Assigning Authority (HD datatype). In a QBP^Q23 context, this applies to the PID-3.4 Assigning Authority in the RSP^K23 response PID (Query Response) segment.

A search is performed for the NamingSystem resource where NamingSystem.uniqueId.value matches the FHIR system URI. If a FHIR identifier cannot be resolved to an Assigning Authority (no matching NamingSystem found), the identifier is excluded from the response. If a match is found, the following fields are mapped:

The following table defines the mapping from the NamingSystem.uniqueId.type to the HL7 v2.x HD.3 (Universal ID Type).

When map_identifiers_using_namingsystem_inbound is disabled, Smile CDR uses the FHIR system URI directly as HD.2 (Universal ID) with HD.3 (Universal ID Type) set to URI. HD.1 (Namespace ID) is not populated.

{
    "system": "http://example.com/pif",
    "value": "8950"
}

{
  "resourceType": "NamingSystem",
  "uniqueId": [
    {
      "type": "oid",
      "value": "9.9.9.4.5",
      "preferred": true
    },
    {
      "type": "uri",
      "value": "http://example.com/pif"
    },
    {
      "type": "other",
      "value": "PIF"
    }
  ]
}

This results in the following PID (Query Response) segment in the RSP^K23 response: PID|||8950^^^PIF&9.9.9.4.5&ISO||~^^^^^^S