Transforming Messages: HL7 to Database

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 save the message to a database.

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 a database table node 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.

Preparation: Create the “test” database [top]

If you do not already have a SQLite database called “test” in the Iguana install directory, then you can create it by following the instructions in the Create a SQLite DB to match your VMD tutorial.

Create the Channel [top]

  1. Create a Channel with the the following settings:
    • Source = LLP Listener
    • Destination = To Translator
    • Channel name = Transformation HL7 to DB
  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 Destination tab.
  4. Download and import the the Transformation_HL7_to_DB_To_Translator.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 12 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 and Out (ADT) 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 12 and 13 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 and Out (ADT) 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'

function main(Data)
   -- Parse the HL7 message
   local Msg, Name = hl7.parse{vmd = 'example/demo.vmd', data = Data}
   
   -- Create the database tables target node tree
   local Out       = db.tables{vmd = 'example/demo.vmd', name = Name}
   
   -- (1) Modify the patient mappings to transform the data
   Out.patient[1].Id        = Msg.PID[3][1][1]

   -- Capitalize patient Given Name and Surname
   Out.patient[1].LastName  = Msg.PID[5][1][1][1]:nodeValue():capitalize()
   Out.patient[1].GivenName = Msg.PID[5][1][2]:nodeValue():capitalize()
 
   -- Correct misspelling of the Race Code
   if Msg.PID[10][1][1]:nodeValue():lower() == 'mix'then
      Out.patient[1].Race = 'Mixed'
   else
      Out.patient[1].Race = Msg.PID[10][1][1]
   end
   Out.patient[1].Ssn       = Msg.PID[19]
      
   -- Save data to database
   
   -- connect to the database
   if not Conn or not Conn:check() then
      Conn = db.connect{
         api=db.SQLITE,
         name='test',
         user='',
         password='',
         live=true
      }
   end
   
   -- merge the data into the database
   Conn:merge{data=Out, live = true}
end

More Information [top]