HL7 Tutorial: Hands-on Lessons Jeremy Espino MD Copyright 2007 General Biodefense LLC What's on the tutorial CD: ● HL7

Version 2.5 Specification ● Tutorial Presentation ● HL7 Sample Data ● JRE1.6.0 ● Mirth 1.3.2 ● Nule Tools ● Tutorial files This series of lessons will introduce you to HL7 routing, filtering and transformation. In a system that is collecting healthcare data from many sources there is often the need to modify the messages into the format expected by the application. We will use the routing capabilities of an integration engine to route messages from multiple inbound TCP ports to a single file directory. [N.B. We will use a file directory in lieu of the RODS application to simply the tutorial. In practice RODS will listen for data on a TCP port] Sometimes hospitals will send you messages that you don't care about. We will show you how to ignore such messages. Sometimes hospitals will send confidential data that should be removed from the message. We will show how you can remove data fields from the message using an integration engine. Sometimes hospitals will not format the data the way the application expects. We will show you how to transform data in the message. This tutorial is the tip of the iceberg in terms of HL7 messaging. For the tutorial we will utilize a single message event type (A04). There are over 100 types of message events in the HL7 specification and ADT type messages are the easiest to understand and work with. For more information about HL7 visit: HL7.org

Page 1 Copyright 2007 General Biodefense

File->Open File->hl7_sample_data\adt_in.3. Open HL7 sample data file 1.Lesson 1: Setup of simulation environment Here we'll setup our simulation environment which comprises a sending application (HL7 Browser) and an integration engine (Mirth) 1.2\mirth.hl7 2. Start instance of the nule HL7 browser (nule_tools\hl7browser. Start up mirth server (mirth-1. Check “Use advanced HL7v2 processor” 3.bat) 2.bat) Page 2 Copyright 2007 General Biodefense .

Deploy the channels (Channels->Deploy All) 8. Using Internet Explorer visit http://localhost:8080/ 2. HL7 browser will show data it sent and received in the console log. Switch to the Nule HL7 browser 2. Save the channel 7. Channel Type is Router 4. Click on Connect 7.0. Click on Launch Mirth Administrator 3. Enter password: admin 2. Mirth Administrator will show that it received and sent messages. Setup a New Channel – we will set up a channel that has an inbound TCP interface on port 11000 that routes messages to a file 1. Directory where messages are routed to will have updated file(s) Page 3 Copyright 2007 General Biodefense .1 5. There should be no errors.0.Lesson 2: Route messages In this lesson we will route messages from a TCP/IP MLLP listener to a file directory. 1. Click on connect icon 3. Click on Send now 4. Click on Finish 5. 3. Click on Send Mode tab 4. Set port to 11000 6. Set up channel based on screen shots for Lesson 2 (see end of this packet) 6. Start mirth administrator 1. Select New Channel 2. Name the channel L2_Route_Message 3. Enter username: admin 4. Confirm that messages were sent and routed 1. Send data to the new channel 1. Start the Channel (L1_Route_Message->Start Channel) 3. Set host to 127. Note that it received acknowledgment messages 2.

Start Mirth Administrator if not already started 2. In the Javascript area type: 1. Click on Edit Filter 6. // return true if message is type A04 2. Click on HL7 Tree tab of Mirth Administrator 9. 7. Click on L2_Route_Message 3.0. Save the channel 11. Deploy the channels (Channels->Deploy All) 12.toString() “ can be quickly added by dragging that field to the Javascript area 4. Double click on the L3_Filter_Message channel 3. Set host to 127. Highlight a message in HL7 Browser 2. Click on Send Mode tab 4. Click on HL7 Message Template tab 7. Click on connect icon 3.0. A filter rule returns true if the destination should receive the data. Switch to the Nule HL7 browser 2. Copy the L1_Route_Message channel to a channel called L3_Filter_Message 1. Click on Destinations tab 4.2']. return true. Click back to channels 6. Click on Channels in the side bar 2. Click on Channels in the sidebar 2. Copy one of the messages from the HL7 Browser to the HL7 Message Template area 1. Edit the cloned channel so that it filters messages 1.9']['MSG. if (msg['MSH']['MSH.9']['MSG.1 Page 4 Copyright 2007 General Biodefense . 1. } else { 6. Add a new rule. } 3.2']. Press ctrl+c to copy 3. 3. Call the rule A04_only 2.Lesson 3: Filter Messages In this lesson we will route only A04 (Patient Visit) messages from the MLLP listener to a file directory. Note that the string “msg['MSH']['MSH. return false. Click on Clone Channel in the left sidebar 4. Click on the HL7 Message Template area of Mirth Administrator 4. Call the cloned channel L3_Filter_Message 5.toString() == 'A04') { 4. Click on Validate Javascript to make sure the script has not syntactic bugs 5. Save the channel 3. 1. press ctrl+v to paste 8. Start the Channel (L1_Route_Message->Start Channel) 13. Send data to the new channel 1. 5. Select Destination 1 5. You shall see a parsed version of the message 10.

Mirth Administrator will show that it sent 4 messages. HL7 browser will show data it send and received in the console log. Note that it received acknowledgment messages 2. Directory where messages are routed to will have updated file(s) Page 5 Copyright 2007 General Biodefense . Confirm that messages were sent and routed 1.5. Set port to 11000 6. 3. Click on Connect (or disconnect and the connect again if you were connected already) 4. Click on Send now 5.

hl7_msg = msg. Click on L3_Route_Message 3. delete msg['PID']['PID. 5.Lesson 4: Delete message fields In this lesson. Select Destination 1 5. Click on Clone Channel in the left sidebar 4. You shall see a parsed version of the message 4. Click on connect icon 3. // copy transformed message to output 5. Set host to 127. press ctrl+v to paste 5. Click on Channels in the sidebar 2.0. // remove the dob 2. 4. Add a new step 1. Start the Channel (L4_Delete_Fields) 9. Send data to the new channel 1. Switch to the Nule HL7 browser 2. Click on Add New Step 2. Click on Channels in the side bar 2. Click on the HL7 Message Template area of Mirth Administrator 4. Click on Destinations tab 4. Call the cloned channel L4_delete_message_fields 5. Call the step delete_dob 4. we will delete data from individual message fields 1. Click on HL7 Message Template tab 7. Highlight a message in HL7 Browser 2. Press ctrl+c to copy 3. Save the channel 7. Save the channel 3. Make the step a Javascript type of step 3. Double click on the L4_delete_message_fields channel 3. Click on Validate javascript to make sure the script has not syntactic bugs 5. Copy one of the messages (choose one that is an A04 event) from the HL7 Browser to the HL7 Message Template area 1. Copy the L3_Filter_Message to a channel called L4_delete_message_fields 1. Click on Send Mode tab 4. Click on Edit Transformer 6. Click on HL7 Tree tab of Mirth Administrator 8. Click back to channels 6.0. Start Mirth Administrator if not already started 2.1 Page 6 Copyright 2007 General Biodefense . Deploy the channels (Channels->Deploy All) 8.7']. In the Javascript area type: 1. Edit the cloned channel so that it deletes specific fields 1. 3.

5. Click on Connect (or disconnect and the connect again if you were connected already) 7. Set port to 11000 6. HL7 browser will show data it send and received in the console log. Click on Send now 10. Directory where messages are routed to will have updated file(s) Page 7 Copyright 2007 General Biodefense . Mirth Administrator will show that it sent 4 messages 3. Confirm that messages were sent and routed 1. Note that it received acknowledgment messages 2.

Select Destination 1 5. Call the cloned channel L4_delete_message_fields 5. // calculate age 11. Make the step a Javascript type of step 3. press ctrl+v to paste 8.Lesson 5: Transform message fields In this lesson you will see how you can utilize any Javascript function to transform fields into other fields.4). 14. // greate obx segment to store age. Click on Channels in the sidebar 2. Click on Add New Step 2. Click on Destinations tab 4. In the javascript area type: 1. 4. Copy one of the messages (choose one that is an A04 event) from the HL7 Browser to the HL7 Message Template area 1. Edit the cloned channel so that it deletes specific fields 1. Save the channel 3. Highlight a message in HL7 Browser 2. var dobObj = new Date( dob.substr(4.1']. 13. Click on L3_Route_Message 3.7']['TS. Start Mirth Administrator if not already started 2. Copy the L3_Filter_Message to a channel called L4_delete_message_fields 1. Page 8 Copyright 2007 General Biodefense . Call the step “convert dob to age” 4. 1 ).dobObj. Click on Clone Channel in the left sidebar 4.round(ageInMillis/31536000000). 3. var ageInMillis = currentDate. 12. Click on the HL7 Message Template area of Mirth Administrator 4. 8. 1. var dob = msg['PID']['PID. Press ctrl+c to copy 3. dob. Click on HL7 Message Template tab 7. Double click on the L4_delete_message_fields channel 3. // convert to date objects 6. 9. Click on HL7 Tree tab of Mirth Administrator 9. // extract dob "YEARMONTH" 2. var currentDate = new Date(). 7. 5.getTime() .substr(0.getTime().toString(). Click on Edit Transformer 6.2). Click on Channels in the side bar 2. var age = Math. We'll convert the date of birth to age and add in an OBX segment. Add a new step 1. You shall see a parsed version of the message 10. 10.

HL7 browser will show data it send and received in the console log. msg['OBX']['OBX.2']="NM". 26. msg['OBX']['OBX. 27.6']['CE. Click on connect icon 3. .5']=age.3']['CE.0. 9.1']="a". Directory where messages are routed to will have updated file(s) Page 9 Copyright 2007 General Biodefense . 17. msg['OBX']['OBX. 16.3']['CE.0. Switch to the Nule HL7 browser 2. msg['OBX']['OBX.4. 5. Set port to 11000 6.1']="1". 18. 21. msg['OBX']['OBX. Click on Send now Confirm that messages were sent and routed 1. hl7_msg=msg.2']="Calculated Patient Age". msg['OBX']['OBX. Mirth Administrator will show that it received 18 messages and sent 18 messages 3. 5. 6. 8.1 5. Click on Validate javascript to make sure the script has not syntactic bugs Click back to channels Save the channel Deploy the channels (Channels->Deploy All) Start the Channel (L4_Delete_Fields) Send data to the new channel 1. 19. 22. 7. Click on Send Mode tab 4. 24.2']="Years". 25. msg['OBX']['OBX.11']="F". Click on Connect (or disconnect and the connect again if you were connected already) 7. Set host to 127. msg['OBX']['OBX. Note that it received acknowledgment messages 2.6']['CE. 15.1']="29553-5".3']="LOINC" 20. 23. msg['OBX']['OBX.3']['CE.

Lesson 1 – Running the Mirth Server and Nule HL7 browser Page 10 Copyright 2007 General Biodefense .

Lesson 2 – L2_Route_Message settings Page 11 Copyright 2007 General Biodefense .

Lesson 2 – L2_Route_Message settings Page 12 Copyright 2007 General Biodefense .

Lesson 2 – L2_Route_Message settings Page 13 Copyright 2007 General Biodefense .

Lesson 3 – L3_Filter_Message settings Page 14 Copyright 2007 General Biodefense .

Lesson 4 – L4_Delete_Fields settings Page 15 Copyright 2007 General Biodefense .

Lesson 5 – L5_Transform_Fields settings Page 16 Copyright 2007 General Biodefense .