Customizing HL7v2 to FHIR Conversion: Adding Custom Coding Systems and Extensions

[Shreeja-dev]

I'm currently working on converting an HL7v2 (Version 2.7) message to FHIR using the LinuxForHealth HL7 Converter, and I need to incorporate custom coding systems and extensions into the transformation process. Specifically, I want to:

1. Map certain HL7 segments/fields to custom coding systems instead of the default ones.
2. Add custom FHIR extensions based on specific fields from the HL7v2 message.

Could someone provide guidance or examples on how to modify or create a custom mapping configuration file that supports these customizations? Are there specific templates or best practices I should follow to ensure the custom coding systems and extensions are correctly applied during the conversion?

Thank you for any help or insights!

[Shreeja-dev]

Hi @LisaWellman ,

Could you kindly provide some guidance on this? Any assistance would be greatly appreciated.

Thanks, Shreeja

[LisaWellman]

@pbhallam could you provide some guidance please?

[pbhallam]

@Shreeja-dev -- can you please provide any examples of what you are trying to do?

[Shreeja-dev]

@pbhallam

I am currently using the hl7v2-fhir-converter dependency (version 1.0.10) as shown below:

<dependency>
    <groupId>io.github.linuxforhealth</groupId>
    <artifactId>hl7v2-fhir-converter</artifactId>
    <version>1.0.10</version>
</dependency>```

I have implemented a JUnit test that converts a simple HL7 message to FHIR JSON using the following code:

```java
String hl7Message = "MSH|^~\\&|SendTest1|Sendfac1|Receiveapp1|Receivefac1|200603081747|security|ORU^R01|MSGID000005|T|2.6\r"
    + "PID||45483|45483||SMITH^SUZIE^||20160813|M|||123 MAIN STREET^^SCHENECTADY^NY^12345||(123)456-7890|||||^^^T||||||||||||\r"
    + "OBR|1||986^IA PHIMS Stage^2.16.840.1.114222.4.3.3.5.1.2^ISO|1051-2^New Born Screening^LN|||20151009173644|||||||||||||002|||||F|||2740^Tsadok^Janetary~2913^Merrit^Darren^F~3065^Mahoney^Paul^J~4723^Loh^Robert^L~9052^Winter^Oscar^|||||\r";

HL7ToFHIRConverter ftv = new HL7ToFHIRConverter();
final String output = ftv.convert(hl7Message);

In the converted JSON, I am seeing IBM-specific extensions and value sets like the one shown below:

"meta": {
    "extension": [{
        "url": "http://ibm.com/fhir/cdm/StructureDefinition/source-event-trigger",
        "valueCodeableConcept": {
            "coding": [{
                "system": "http://terminology.hl7.org/CodeSystem/v2-0003",
                "code": "R01"
            }]
        }
    }]
}

Instead of IBM URLs, we want to replace these with our own definitions. Upon checking your code, we noticed that these mappings are defined in the file:

src/main/resources/hl7/codesystem/ExtensionUrlMapping.yml

We need to replace the default IBM URLs for extension URLs, value set URLs, and terminology URLs with our own custom definitions.

Could you please provide guidance on how to configure or update the library files (e.g., ExtensionUrlMapping.yml) to incorporate our custom URLs instead of the default IBM ones? Specifically, we are looking for detailed instructions on how to override these mappings or any configuration files that need to be adjusted.

Thank you in advance for your assistance.

[pbhallam]

One way to do this:

1. Make copy of the resources and modify the required resources (for your case modify : https://github.com/LinuxForHealth/hl7v2-fhir-converter/blob/master/src/main/resources/hl7/codesystem/ExtensionUrlMapping.yml)
2. Point the config to use new resources, use the property:base.path.resource https://github.com/LinuxForHealth/hl7v2-fhir-converter/blob/master/src/main/resources/config.properties

Another way would be use additional resource concept, take a look at this test:

  // This tests that messagetemplates are loaded the new way via configured path + alternate path
  @Test
  void testGetMessageTemplatesViaAdditionalLocation() throws IOException {
    try {
      // Set up the config file
      File configFile = new File(folder, "config.properties");
      Properties prop = new Properties();
      prop.put("base.path.resource", "src/main/resources");
      prop.put("supported.hl7.messages", "*");
      prop.put("default.zoneid", "+08:00");
      prop.put("additional.resources.location", "src/test/resources/additional_resources");
      prop.store(new FileOutputStream(configFile), null);
      System.setProperty(CONF_PROP_HOME, configFile.getParent());

      // Get the templates ORU_R01 will be found in the base path and ADT_A09 will be found in the additional path
      Map<String, HL7MessageModel> messagetemplates = ResourceReader.getInstance().getMessageTemplates();
      assertThat(messagetemplates).containsKey("ORU_R01"); // found in the base path
      assertThat(messagetemplates).containsKey("ADT_A09"); // found in the additional path
    } catch (IllegalArgumentException e) {
      throw new IllegalStateException("Failure to initialize the templates for the converter.", e);
    }
  }

[Shreeja-dev]

@pbhallam

Thank you for your prompt response. I appreciate your suggestions and will try out the options provided.

I need your guidance regarding an issue I encountered while testing using a Spring Boot endpoint where I pass an HL7 payload in the request body. Within my service, I’m utilizing the hl7v2-fhir-converter, as referenced in the above JUnit example. I have verified that the full Hl7 message is passed correctly to the converter. However, the full JSON is not created; instead, only a partial JSON is produced without any FHIR resources, such as patient, encounter, or observation:

{
  "id": "4566c0c5-2d2c-4542-88ca-332c07311390",
  "meta": {
    "lastUpdated": "2024-10-17T09:47:10.425+00:00"
  },
  "type": "collection",
  "resourceType": "Bundle"
}

I've attached the full HL7 file (hlmessage.txt) for your reference. Additionally, I noticed some logs(log.txt) from the converter that might provide insight. As this is my initial stage of using the converter, I’m finding it challenging to draw conclusions from the logs. I would appreciate any thoughts you have on this. Could you please review and let me know if I’m missing any configurations or if there are any additional steps I should take to properly convert the HL7 payload into t he expected JSON format?

Thank you for your assistance!

[Shreeja-dev]

@pbhallam ,

Appreciate any guidance or insights you have on how to trace the cause of the above mentioned issue. Could you confirm if the configurations are correct?