First Steps: Building a Simple Interface

Parse the Message

Note: We are now at a point in the tutorial when we start talking about actual code. You might be wondering, “How should I follow along?” We recommend that you manually enter the code, following step-by-step, to help cement what you are learning. That said, we also provide a completed sample of the code at the bottom of each page. If you run into problems, or if you aren’t confident that you’ve followed the steps correctly, you can simply copy/paste this sample code directly into your script.

Let’s kick off our script by grabbing the incoming HL7 messages and turning them into a format our code can work with:

Step 1: Pass the data

Before we can start manipulating incoming messages with our script, our code needs to “load” them up. Each incoming HL7 message is passed into the main() function using the string parameter Data. The Translator automatically includes the Data parameter in the skeleton code for the main() function.

Screen Shot 2014-06-11 at 10.25.09

In production (when we’ve finished developing the code and have activated the channel), this data will be a stream of HL7 messages coming from an external LLP source. In the Translator (our test/development environment), this data consists of sample messages that we can use to test how our code works.

Step 2: Parse each message

So, how do we work with HL7 messages once we’ve passed them in? Because incoming messages are in raw string format, we need to reformat them so that our code can better identify each message’s segments and fields. This is called parsing.

Add the following line of code to your script:

Screen Shot 2014-06-11 at 10.31.43

Tip: There is also a third return that contains table of parse warnings, this can be useful to track problems with parsing messages. See Using the Warnings returned from hl7.parse{}.

What is happening here? In this line of code, we are using the hl7.parse{} function to decipher each incoming message and parse its contents into a hierarchical structure known as a node tree. This particular function requires that we define two parameters:

  • vmd = which VMD file to use
  • data = what data to parse (in this case, the ‘Data’ parameter being passed through the main() function).

What is a VMD file? VMD files define message structures. Several important functions (including hl7.parse{}) rely on these templates to read, parse, and construct messages correctly. To reference a VMD file in your code, you first need to import it into your project. In this tutorial, we’ve already done this by including ‘demo.vmd’ in the project zip file.

Why are we defining more than one variable? You might be wondering why we’ve assigned the results of the hl7.parse{} function to two new variables (Msg and Name). The hl7.parse{} function includes a neat little feature: it can support two variables! Reading from left to right:

  • The first variable is assigned the parsed message’s new node tree
  • The second variable is assigned the message’s type. For example, if the message was created when a patient was admitted to hospital, hl7.parse{} would assign the second variable the value ‘ADT’.

Because we will need to know the message type to successfully complete the next section, we’ve included a second variable (‘Name’) to our line of code.

Tip: Why does why the hl7.parse{} function use curly braces instead of brackets? This is actually Lua shorthand for a function that takes a single table as a parameter. Still curious? Check out this article: Why some functions are called with {}.

Step 3: Examine the results

Let’s examine the node tree that we’ve just created. Notice that an annotation window has appeared with an entry that corresponds to the line of code that we’ve just added:

Screen Shot 2014-06-11 at 10.34.15

Annotation windows provide real-time, interactive feedback by displaying the data that our code is using as we develop it. As you can see in highlighted line above, the hl7.parse{} function is parsing a specific sample message.

To see how our code has parsed this message into a node tree, click on the first ADT entry. This represents the results assigned to the ‘Msg’ variable (the other two values represent the ‘Name’ variable and any errors returned, respectively).

The following results appear, displaying the sample message’s new node tree (broken down by segment and field):

Want to see how this works with other messages? In the Translator toolbar, use the navigation controls to scroll through the remaining sample messages:

Screen Shot 2014-06-11 at 10.39.54

Notice how the annotation results change to reflect the new data? Pretty cool!

Tip: Still need some clarification about node trees? A node tree is basically data converted into a simple tree format following a specific hierarchy. Node trees organize information like tables do, but they include additional functionality. Their purpose is to make it easier for us to locate, map, and manipulate message data. Still curious? Check out this article: Node Types for Iguana Node Trees.

Sample Code

Here is a copy-and-paste version of the code we’ve just created:

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

   -- (2) Map the incoming message to the outgoing message

   -- (3) Alter the MSH segment data

   -- (4) Modify the PID data

   -- (5) Push the outgoing message into the Iguana queue
end

Now all our data preparation is done! We can move on to the important stuff: transforming the data. The first step? We need to map the incoming message data.

Leave A Comment?