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

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. Start instance of the nule HL7 browser (nule_tools\hl7browser.bat) 2. Open HL7 sample data file 1. File->Open File->hl7_sample_data\adt_in.hl7 2. Check Use advanced HL7v2 processor 3. Start up mirth server (mirth-1.3.2\mirth.bat)

Page 2 Copyright 2007 General Biodefense

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

Page 3 Copyright 2007 General Biodefense

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

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

Page 5 Copyright 2007 General Biodefense

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

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

Page 7 Copyright 2007 General Biodefense

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

4. 5. 6. 7. 8.

9.

15. msg['OBX']['OBX.1']="1"; 16. msg['OBX']['OBX.2']="NM"; 17. msg['OBX']['OBX.3']['CE.1']="29553-5"; 18. msg['OBX']['OBX.3']['CE.2']="Calculated Patient Age"; 19. msg['OBX']['OBX.3']['CE.3']="LOINC" 20. ; 21. msg['OBX']['OBX.5']=age; 22. msg['OBX']['OBX.6']['CE.1']="a"; 23. msg['OBX']['OBX.6']['CE.2']="Years"; 24. 25. msg['OBX']['OBX.11']="F"; 26. 27. hl7_msg=msg; 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. Switch to the Nule HL7 browser 2. Click on connect icon 3. Click on Send Mode tab 4. Set host to 127.0.0.1 5. Set port to 11000 6. Click on Connect (or disconnect and the connect again if you were connected already) 7. Click on Send now Confirm that messages were sent and routed 1. HL7 browser will show data it send and received in the console log. Note that it received acknowledgment messages 2. Mirth Administrator will show that it received 18 messages and sent 18 messages 3. Directory where messages are routed to will have updated file(s)

Page 9 Copyright 2007 General Biodefense

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