V2ToFHIR Custom Mapping Sample Project

Overview

The V2ToFHIR Ballerina module is a custom implementation that extends the standard HL7 V2 to FHIR R4 mapping capabilities provided by the Ballerina v2tofhirr4 library. This module demonstrates how to create custom mappings on top of existing standard mappings and can be exported as a WSO2 Micro Integrator (MI) module for use in integration flows.

Features

• Standard HL7 V2 to FHIR R4 Conversion: Leverages the official Ballerina v2tofhirr4 library for baseline conversion
• Custom Mapping: Adds custom field mappings specific to your requirements
• Resource Merging: Intelligently merges standard and custom mappings
• WSO2 MI Integration: Can be exported as an MI connector for use in integration flows
• Error Handling: Comprehensive error handling for parsing and conversion failures

Project Structure

src/main/ballerina/V2toFHIR/
├── Ballerina.toml          # Ballerina package configuration
├── Dependencies.toml       # Ballerina dependencies
├── V2toFHIR-module.bal    # Main transformation logic
└── utils.bal              # Utility functions for FHIR resource merging

Dependencies

The project uses the following key dependencies:

• ballerinax/health.fhir.r4 - FHIR R4 base types
• ballerinax/health.fhir.r4.international401 - International FHIR R4 extensions
• ballerinax/health.hl7v2 - HL7 V2 parsing utilities
• ballerinax/health.hl7v23 - HL7 V2.3 specific types
• ballerinax/health.hl7v2.utils.v2tofhirr4 - Standard V2 to FHIR conversion
• wso2/mi - WSO2 Micro Integrator connector

How It Works

1. Standard Conversion

The module first uses the standard v2tofhirr4:v2ToFhir() function to convert HL7 V2 messages to FHIR R4 bundles.

2. Custom Mapping

After standard conversion, the module applies custom mappings:

• Parses the HL7 message as an ADT_A01 type
• Extracts specific fields for custom mapping
• Creates custom FHIR resources with additional fields

3. Resource Merging

The mergeFhirResources() utility function intelligently merges:

• Standard FHIR resources from the baseline conversion
• Custom mapped resources with additional fields
• Handles nested objects, arrays, and complex data structures

4. Custom Patient Mapping Example

The module includes a custom mapPatient() function that demonstrates:

• Mapping HL7 V2 practitioner references to FHIR general practitioner fields
• Generating unique patient IDs using UUID
• Extending standard patient resources with custom fields

Usage

Basic Transformation

import wso2/mi;

@mi:Operation
public function transform(string hl7Msg) returns json {
    // Your transformation logic here
    // Returns FHIR R4 Bundle as JSON
}

Custom Mapping Function

isolated function mapPatient(hl7v23:ADT_A01 incomingMessage) returns international401:Patient {
    // Custom mapping logic
    return {
        generalPractitioner: [
            {
                reference: "Practitioner/" + incomingMessage.pv1.pv18[0].xcn1,
                display: incomingMessage.pv1.pv18[0].xcn2
            }
        ],
        id: uuid:createType1AsString()
    };
}

Building the MI Module

Prerequisites

1. Ballerina Installation: Ensure you have Ballerina 2201.12.3 or compatible version installed
2. MI Module Generator: Install the MI module generator tool

bal tool pull mi-module-gen

Build Process

1. Navigate to the Ballerina project directory:

   cd src/main/ballerina/V2toFHIR

2. Generate the MI module:

   bal mi-module-gen -i .

3. Locate the generated module: The module will be generated as a ZIP file in the same directory

Using the Generated Module in WSO2 MI

1. Add the connector to your MI project:

   • Copy the generated ZIP file to your MI project's src/main/wso2mi/artifacts/connectors/ directory
   • Or add it through the MI Studio/VS Code extension

2. Use in integration flows:

   • The module will appear in the Mediator Palette
   • Drag and drop to add to your integration flows
   • Configure the input parameters (HL7 V2 message)

How to Try Out the V2ToFHIR Module

Prerequisites

1. WSO2 Micro Integrator: Install WSO2 MI 4.4.0 or compatible version
2. Generated Module: Ensure the V2ToFHIR module is built and available as V2toFHIR-connector-1.0.0.zip
3. Sample HL7 Files: Prepare test HL7 V2 messages

Testing the Flow

1. Prepare Test Data

Create a sample HL7 V2 message file (e.g., test.hl7):

MSH|^~\&|ADT1|GOOD HEALTH HOSPITAL|GHH LAB, INC.|GOOD HEALTH HOSPITAL|198808181126|SECURITY|ADT^A01^ADT_A01|MSG00001|P|2.3||
EVN|A01|200708181123||
PID|1||PATID1234^5^M11^ADT1^MR^GOOD HEALTH HOSPITAL~123456789^^^USSSA^SS||EVERYMAN^ADAM^A^III||19610615|M||C|2222 HOME STREET^^GREENSBORO^NC^27401-1020|GL|(555) 555-2004|(555)555-2004||S||PATID12345001^2^M10^ADT1^AN^A|444333333|987654^NC|
NK1|1|NUCLEAR^NELDA^W|SPO^SPOUSE||||NK^NEXT OF KIN
PV1|1|I|2000^2012^01||||004777^ATTEND^AARON^A|||SUR||||ADM|A0|

2. Run the server and test the flow

1. Start the server
2. Place the test file in the configured input directory in the inbound endpoint.
3. Monitor the logs in WSO2 MI console for processing messages
4. Check the output:
   • Processed files will be moved to the success directory
   • Failed files will be moved to the error directory
   • FHIR conversion results will be logged

3. Expected Output

There will be logs from the module containing following information:

• Standard patient information from the HL7 V2 message
• Custom mapped fields (e.g., general practitioner references)
• Merged resources with both standard and custom data.

Debug Mode

You can start the MI server with remote debug mode and open up the ballerina code in VS Code and follow the instructions from here to debug the code.

Input/Output Format

Input: HL7 V2 message as a string Output: FHIR R4 Bundle as JSON

Error Handling

The module includes comprehensive error handling for:

• HL7 V2 Parsing Errors: Invalid message format
• Conversion Errors: Standard V2 to FHIR conversion failures
• Type Conversion Errors: JSON to FHIR resource conversion issues
• Custom Mapping Errors: Custom field mapping failures

Error responses include:

{
    "error": "Error description",
    "details": "Detailed error message"
}