Transforming Messages: HL7 to JSON

In this tutorial you will learn how to transform message data. We will copy an incoming HL7 message, correct a misspelled code, capitalize patient names, and then forward the message as JSON.

You can use the same transformation method when copying data between any of the different types of node trees.

These are the steps:

  1. Preparation: Parse the message into a source HL7 node tree structure
  2. Preparation: Create an JSON tree for the target message
  3. Map and transform the message:
    • Map data from the source node tree to the target node tree
    • During mapping the message we will also modify the data in some way, e.g., capitalize names etc.

This tutorial only addresses the last step, the preparatory steps have already been completed for you.

We recommend that you type in the code for each step, but we also include complete Sample Code if you prefer to paste it in and follow along.

Create the Channel [top]

  1. Create a Channel with the the following settings:
    • Source = LLP Listener
    • Destination = To Translator
    • Channel name = Transformation HL7 to JSON
  2. Click the Add Channel button to create the channel.
    Ignore the red warning messages, see resolving the milestone configuration error.
  3. Open the Translator by clicking the Edit Script link at the bottom of the Filter tab.
  4. Download and import the the Transformation_HL7_to_JSON_Filter.zip project file.
    This file contains a skeleton project and six sample HL7 messages.
  5. Iguana will load the project and data into the Translator, your screen should look like this:

Tutorial Instructions [top]

  1. Pass the message data to the script.
    • Iguana automatically passes the message data to the main() function
    • The message can be accessed using the Data parameter
    • No action is needed
  2. Parse the message, create the outgoing message, and map the message.
    • The code for this is included from the imported project zip file
    • No action is needed
  3. An incorrect code of “Mix” is used for mixed race, we will use an “if” statement to change this to “Mixed” when it occurs.
    Replace line 26 with this if statement code, auto-completion will help you to find the fields and methods:
  4. Navigate through the sample messages to see the spelling correction in action.
    1. First add a trace() statement on the next line, and click on the Msg (ADT) and Out (table) annotations to view them:
    2. Click through the sample messages, here you can see how the “MIX” race code is corrected:
  5. Capitalize the patient Given Name and Surname.
    1. First we need to use the stringutil module, so add this line of code at the top of your script:
    2. Update the code on lines 24 and 25 to look like this:
  6. Navigate through the sample messages to see how patient names are capitalized.
    1. First add a trace() statement on the next line, and click on the Msg (ADT) and Out (table) annotations to view them:
    2. Then click through the sample data, here you can see that the patient surname has been corrected:

Complete Sample Code [top]

Here is the completed mapping code that you can cut and paste into your script:

require 'stringutil'

local JSON_TEMPLATE = [[
{
   'patients':
   {
      'patient-id':'',
      'first-name':'',
      'last-name':'',
      'race-code':'',
      'social-security-no':''
   }
}]]

function main(Data)
   -- Parse the HL7 message
   local Msg = hl7.parse{vmd = 'example/demo.vmd', data = Data}

   -- Parse the JSON template
   local Out = json.parse(JSON_TEMPLATE)
   
   -- (1) Modify the patient mappings to transform the data
   Out.patients["patient-id"] = Msg.PID[3][1][1]

   -- Capitalize patient Given Name and Surname
   Out.patients["first-name"] = Msg.PID[5][1][1][1]:nodeValue():capitalize()
   Out.patients["last-name"]  = Msg.PID[5][1][2]:nodeValue():capitalize()
      
   -- Correct misspelling of the Race Code
   if Msg.PID[10][1][1]:nodeValue():lower() == 'mix'then
      Out.patients["race-code"] = 'Mixed'
   else
      Out.patients["race-code"] = Msg.PID[10][1][1]
   end
   Out.patients["social-security-no"] = Msg.PID[19]
      
   -- Push the outgoing message into the Iguana queue
   queue.push(tostring(Out))
end

More Information [top]