Channel 2: Socket to Database

A very common interface task involves sorting through incoming information and copying specific data to an external repository. This demo channel demonstrates how easy this task is to accomplish! With a simple filter and a ‘smart’ outbound script, we can sort through incoming messages for patient information that we can then copy to an external patient database.

How It Works

The 02-Socket to Database demo channel consists of the following components, each designed to perform a specific task:

Component	Type	Function
Source	‘From LLP’	Receive data from a specific port via TCP/IP: port number 5145 (local)
Filter	(script)	For each message: Parse the raw data to identify individual messages and fields. Filter out any HL7 message that is NOT an ADT message. Convert altered messages back into raw string format. Push the string data back into the queue.
Destination	‘To Translator'(script)	Pick up the raw string data from the queue. Identify specific fields and insert their values into an external database: PatientData.sqlite (Iguana/Demo/Database/)

Understanding the Code

If you are having difficulty understanding this channel’s code, don’t panic. This section explains each line of the script to help you get better oriented.

About the ‘Filter’ script

require 'node'

Our first step is to import all the shared modules that we will need. In this particular instance, we need a module named ‘node’ that will convert a node to a string (and escape any characters that need to be escaped).

function main(RawMsgIn)

The main() function is the primary function that Iguana calls when running a script. The rest of your code simply defines the tasks that main() is in charge of executing. In this script, the main() function receives the incoming raw data (in the format of a string). Any parameter name will work here, but we chose ‘RawMsgIn’.

iguana.stopOnError(false)

Although Iguana will log errors as usual, this simple Iguana runtime utility ensures that your channel will not stop running.

local MsgIn, MsgType  = hl7.parse{vmd='example/demo.vmd', data=RawMsgIn}

This function is responsible for converting the incoming data from a raw string into a node tree. This makes each HL7 message much easier to identify, alter, and map.

To correctly parse the raw data, this function relies on VMD files for guidance. VMD files act as templates that help Iguana correctly identify HL7 messages, segments, and fields from the incoming stream.

local MsgOut = hl7.message{vmd='example/demo.vmd', name=MsgType}

In this demo, we will be sorting through incoming messages and choosing specific ones to work with. It’s best practice to create new messages from this process instead of directly altering messages from the incoming data stream. As such, we need a blank slate where we can build the messages that we want to work with. This function uses a VMD file to create a new blank message, ready for data.

MsgOut:mapTree(MsgIn)

The mapTree() function is a great way to quickly move each leaf or data point from the inbound message to the new outbound message.

if MsgType == 'ADT' then
   queue.push{data=MsgOut:S()}
end

This simple conditional statement sorts through the parsed messages to identify those with ADT headers, then pushes these back into the queue (discarding the rest).

About the ‘To Translator’ script

DB = db.connect{api=db.SQLITE, name='Demo/Database/PatientData.sqlite'}

Before we can send anything to a database, we must first connect to it. You can connect to virtually any database using the appropriate commands. In this instance, our SQLite database is named ‘PatientData.sqlite’ and it is located in iNTERFACEWARE/Iguana/Demo/Database.

function main(Data)

The main() function is the primary function that Iguana calls when running a script. The rest of your code simply defines the tasks that main() is in charge of executing. In this script, the main() function receives the incoming raw data (in the format of a string) from the Filter component. Any parameter name will work here, but we chose ‘Data’.

local MsgIn = hl7.parse{vmd='example/demo.vmd', data=Data}

This function is responsible for converting the incoming data from a raw string into a node tree. This makes each HL7 message much easier to identify, alter, and map.

To correctly parse the raw data, this function relies on VMD files for guidance. VMD files act as templates that help Iguana correctly identify HL7 messages, segments, and fields from the incoming stream.

local TableOut = db.tables{vmd='tables.vmd', name='ADT'}

This line creates an empty node tree that will be used to store all of our database fields. We’ve named it ‘TableOut’.

MapPatient(TableOut.Patient[1], MsgIn.PID)

MapPatient() is a simple function that maps patient data from our HL7 message to ‘TableOut’. In order for this function to work, we need to send it some information. In this situation, we are sending the blank patient table ‘TableOut.Patient[1]’ and the corresponding parsed PID segment from the incoming HL7 message, ‘MsgIn.PID’.

function MapPatient(Patient, PID)
    Patient.Id        = PID[3][1][1]   
    Patient.FirstName = PID[5][1][2]   
    Patient.LastName  = PID[5][1][1][1]   
    Patient.Gender    = PID[8]
    return Patient
end

Here is where we define exactly how the MapPatient() function works. This code maps incoming PID fields (Id, First Name, Last Name and Gender) to our node tree (‘TableOut’).

DB:merge{data=TableOut, live=false}

DB:merge is an Iguana command that takes data from the table ‘TableOut’ and checks the database ‘PatientData.sqlite’ to see if the patient already exists. If the record doesn’t already exist, then DB:merge will insert the data. If the patient does already exist, then it will simply update the existing patient record.

You have a lot of control here and can write your own SQL statements if you like. This is just a function that we provide as a way to help make inserting into a database easier on you.

--DB:query{sql='Select * from Patient'}

This code runs a SQL query ‘Select * from Patient’ to pull all information on the patients currently in the database. To view the results, simply click on the ‘Result Set’ field in the accompanying annotations.