HL7 to HL7 Map

Create a Component

You’ll notice the Translator contains a simple script and sample HL7 data that demonstrates the workflow for converting HL7 v2.4 ADT A01 messages to v2.7 ADT A01 messages:

1. Parsing an inbound HL7 message with the inbound VMD (ex. VMD/ADT_2_4.vmd)

2. Filtering the inbound message using the HL7MAP library

3. Building the outbound message and mapping data from the inbound message using the HL7MAP library

4. Pushing the message to the queue for further processing or downstream delivery

You can cycle through the provided sample messages to see how the component handles different message types. This component also demonstrates https://interfaceware.atlassian.net/wiki/x/g4Cxog by ensuring any additional sample messages will not be stored in the commit history. The sample .gitignore file can be viewed in the component’s Bitbucket repository.

Since this is a feeder component, you’ll need a source component (ex. https://interfaceware.atlassian.net/wiki/x/FwBTog) to send messages to it and a destination component (ex. https://interfaceware.atlassian.net/wiki/x/V4CVog) that it can pass messages on for further processing or sending to a downstream system.

You can start the components and send a stream of sample messages from a https://interfaceware.atlassian.net/wiki/x/NgCUog component to see how the mapping and filtering is handled.

Sets up the HL7MAP object framework, adding the method modules to a metatable and storing the provided mapping and filter directories. If no custom directories are provided, it defaults to the provided directories HL7MAP/mappings ('HL7MAP.mappings') and HL7MAP/filters ('HL7MAP.filters’).

HL7MAPbuild takes the provided out_message_type (ex. ADTA01) and calls the matching mapping module in HL7MAP/mappings (ex. HL7MAP/mappings/ADTA01.lua). It passes the provided outbound VMD file (out_vmd) and inbound message (in_message) to the mapping module, which will build and map the outbound message.

HL7MAPfilter takes the provided in_message_type (ex. ADTA01) and calls the matching filtering module in HL7MAP/filters (ex. HL7MAP/filters/ADTA01.lua). If a matching filtering module is not found and a default filter (ex. HL7MAP/filters/default.lua) is available, it calls the default filtering module instead. By default, only Catchall messages are filtered.

The default filtering module checks for messages with an in_message_type of “Catchall” and returns true to filter these messages out. It returns false for all other messages.

The ADTA01 filtering module provides an example of a filtering module that checks filter conditions for ADT A01 messages.

The ADTA01 mapping module contains a main BuildMessage function that takes the provided out_message_type (ex. ADTA01) and the outbound VMD file (out_vmd) to build the outbound message. This function also handles the mapping for each segment.

Simple mappings are handled by using the node.mapTree function at the segment level while complex mappings are handled by local mapping functions that may perform additional transformations or mappings.

HL7MAPcodemaps contains the codemap for mapping the inbound HL7 version codes to the outbound HL7 version codes. In the example script, codemaps for Organ Donor, Administrative Sex, Segment Action, and Marital Status codesets from v2.4 to v2.7 are provided.

The HL7MAP library comes packaged with sample filter and mapping modules, so to use it in a custom HL7 integration, you’ll need to create an internal copy of the repository. You can do so by changing the upstream repository via the library’s Repository Management Screen:

Drag and drop the HL7MAP/mappings and HL7MAP/filters folders outside of the HL7MAP library into the component’s Project Tree. This will allow you to customize filtering and mapping logic for a specific integration.

When initializing the HL7MAP object with custom mappings and filters directories, use the following syntax:

local H = HL7MAPclient{filter_dir="NEW_FILTER_LOCATION",mapping_dir="NEW_MAPPING_LOCATION""}

Update mappings/HL7MAPcodemaps to the specific codesets and HL7 versions your messages will be using.

Update or add message-specific filter modules in the filters folder. The modules should be named [HL7_Type].lua.

Messages with an inbound HL7 message type (ex. ADTA01) that matches the name of a filtering module (ex. ADTA01.lua) will be filtered by that module. All other messages will be filtered by the default filter conditions in filters/default.lua, which can also be further customized.

Update or add mapping modules in the mappings folder. The modules should be named [HL7_Type].lua.

By default, only messages with an outbound HL7 message type (ex. ADTA01) that matches the name of a mapping module (ex. ADTA01.lua) will be mapped. All other messages will be pushed downstream in their original form.