HL7 Tutorial Lessons

HL7 Tutorial: Hands-on LessonsJeremy 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

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.hl72. Check “Use advanced HL7v2 processor”

3. Start up mirth server (mirth-1.3.2\mirth.bat)


Lesson 2: Route messages

In this lesson we will route messages from a TCP/IP MLLP listener to a file directory.

1. Start mirth administrator1. Using Internet Explorer visit http://localhost:8080/2. Click on Launch Mirth Administrator3. Enter username: admin4. 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 file1. Select New Channel2. Name the channel L2_Route_Message3. Channel Type is Router4. Click on Finish5. Set up channel based on screen shots for Lesson 2 (see end of this packet)6. Save the channel7. Deploy the channels (Channels->Deploy All)8. Start the Channel (L1_Route_Message->Start Channel)

3. Send data to the new channel1. Switch to the Nule HL7 browser2. Click on connect icon3. Click on Send Mode tab4. Set host to 127.0.0.15. Set port to 110006. Click on Connect7. Click on Send now

4. Confirm that messages were sent and routed1. HL7 browser will show data it sent and received in the console log. Note that it received

acknowledgment messages2. 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)


http://localhost:8080/

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 started2. Copy the L1_Route_Message channel to a channel called L3_Filter_Message

1. Click on Channels in the sidebar2. Click on L2_Route_Message3. Click on Clone Channel in the left sidebar4. Call the cloned channel L3_Filter_Message5. Save the channel

3. Edit the cloned channel so that it filters messages1. Click on Channels in the side bar2. Double click on the L3_Filter_Message channel3. Click on Destinations tab4. Select Destination 15. Click on Edit Filter6. Click on HL7 Message Template tab7. Copy one of the messages from the HL7 Browser to the HL7 Message Template area

1. Highlight a message in HL7 Browser2. Press ctrl+c to copy3. Click on the HL7 Message Template area of Mirth Administrator4. press ctrl+v to paste

8. Click on HL7 Tree tab of Mirth Administrator9. You shall see a parsed version of the message10. Add a new rule. A filter rule returns true if the destination should receive the data.

1. Call the rule A04_only2. In the Javascript area type:

1. // return true if message is type A042.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 bugs5. Click back to channels6. 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 browser2. Click on connect icon3. Click on Send Mode tab4. Set host to 127.0.0.1


5. Set port to 110006. Click on Connect (or disconnect and the connect again if you were connected already)

4. Click on Send now5. 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)


Lesson 4: Delete message fields

In this lesson, we will delete data from individual message fields

1. Start Mirth Administrator if not already started2. Copy the L3_Filter_Message to a channel called L4_delete_message_fields

1. Click on Channels in the sidebar2. Click on L3_Route_Message3. Click on Clone Channel in the left sidebar4. Call the cloned channel L4_delete_message_fields5. Save the channel

3. Edit the cloned channel so that it deletes specific fields1. Click on Channels in the side bar2. Double click on the L4_delete_message_fields channel3. Click on Destinations tab4. Select Destination 15. Click on Edit Transformer6. Click on HL7 Message Template tab7. Copy one of the messages (choose one that is an A04 event) from the HL7 Browser to the

HL7 Message Template area1. Highlight a message in HL7 Browser2. Press ctrl+c to copy3. Click on the HL7 Message Template area of Mirth Administrator4. press ctrl+v to paste5. Click on HL7 Tree tab of Mirth Administrator

8. You shall see a parsed version of the message4. Add a new step

1. Click on Add New Step2. Make the step a Javascript type of step3. Call the step delete_dob4. In the Javascript area type:

1. // remove the dob2. delete msg['PID']['PID.7'];3.4. // copy transformed message to output5. hl7_msg = msg;

5. Click on Validate javascript to make sure the script has not syntactic bugs5. Click back to channels6. Save the channel7. 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 browser2. Click on connect icon3. Click on Send Mode tab4. Set host to 127.0.0.1


5. Set port to 110006. 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 routed1. HL7 browser will show data it send and received in the console log. Note that it received

acknowledgment messages2. Mirth Administrator will show that it sent 4 messages3. Directory where messages are routed to will have updated file(s)


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 started2. Copy the L3_Filter_Message to a channel called L4_delete_message_fields

1. Click on Channels in the sidebar2. Click on L3_Route_Message3. Click on Clone Channel in the left sidebar4. Call the cloned channel L4_delete_message_fields5. Save the channel

3. Edit the cloned channel so that it deletes specific fields1. Click on Channels in the side bar2. Double click on the L4_delete_message_fields channel3. Click on Destinations tab4. Select Destination 15. Click on Edit Transformer6. Click on HL7 Message Template tab7. Copy one of the messages (choose one that is an A04 event) from the HL7 Browser to the

HL7 Message Template area1. Highlight a message in HL7 Browser2. Press ctrl+c to copy3. Click on the HL7 Message Template area of Mirth Administrator4. press ctrl+v to paste

8. Click on HL7 Tree tab of Mirth Administrator9. You shall see a parsed version of the message10. Add a new step

1. Click on Add New Step2. Make the step a Javascript type of step3. 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 objects6. var currentDate = new Date();7. var dobObj = new Date( dob.substr(0,4), dob.substr(4,2), 1 );8.9.10. // calculate age11. var ageInMillis = currentDate.getTime() - dobObj.getTime();12. var age = Math.round(ageInMillis/31536000000);13.14. // greate obx segment to store age;


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 bugs4. Click back to channels5. Save the channel6. Deploy the channels (Channels->Deploy All)7. Start the Channel (L4_Delete_Fields)8. Send data to the new channel

1. Switch to the Nule HL7 browser2. Click on connect icon3. Click on Send Mode tab4. Set host to 127.0.0.15. Set port to 110006. Click on Connect (or disconnect and the connect again if you were connected already)7. Click on Send now

9. Confirm that messages were sent and routed1. HL7 browser will show data it send and received in the console log. Note that it received

acknowledgment messages2. Mirth Administrator will show that it received 18 messages and sent 18 messages3. Directory where messages are routed to will have updated file(s)


Lesson 1 – Running the Mirth Server and Nule HL7 browser


Lesson 2 – L2_Route_Message settings


Lesson 3 – L3_Filter_Message settings


Lesson 4 – L4_Delete_Fields settings


Lesson 5 – L5_Transform_Fields settings


HL7 Tutorial Lessons

Documents

Transcript of HL7 Tutorial Lessons