Receive, Disassemble Acknowledge an HL7 Message in BizTalk

How difficult is it to validate and disassemble a flat file in BizTalk? Not much! I’d say, provided you have the ight document schema(s) and know how a flat file disassembler in the receive pipeline works. Now is that any more difficult when it comes to a HL7 flat file? The answer is “No” and “Yes”. “No”, being the basic concepts remain largely the same and “Yes” because there are a few additional components you have to acclimatize yourself with. If you have had some acquaintance with EDI processing, this should be nothing short of a cake walk.

So, here’s my scenario. BizTalk receives a HL7 flat file message thru MLLP adapter. The BTAHL7Receive pipeline validates and disassembles the incoming message to an XML file and sends an ACK / NACK back to the source system. Now the notable difference this makes with a flat file disassembling is that “the disassembled message breaks into 3 parts or segments – A MSH Segment, body and a Z-Segment”. In this demo, we are only interested in the body part of the disassembled message. If you like to know how these segments could be processed, I’d suggest the HL7 End to end sample in MSDN at https://msdn.microsoft.com/en-us/library/bb981217(v=bts.10).aspx

Development

While processing a HL7 message it’s quite important to realize the Header segment (MSH), Version and the Message type (9^th composite in the MSH Segment).

In my sample, I am going to deal with an ADT^A03 type message wherein ADT – Admit Discharge Transfer and A03 is the action type. There are numerous other message types; MFN (Master File Notification), ORU(Observation Result
Unsolicited) to name a few. I wouldn’t quite attempt a deep delve into the HL7 standard segments here, but if you like to explore more on that area, I’d suggest https://www.interfaceware.com/hl7-standard/

I am expecting a 2.3.1 version message and my party name happens to be Tutorial_ADTSystem. You will find out how the party is relevant towards the later part of this exercise.

SAMPLE FILE

VISUAL STUDIO

1. I’ll start a new solution with 3 projects.

    a. BTAHL7V2XCommon Project
    Contains ACK schemas ACK_24_GLO_DEF.xsd, ACK_25_GLO_DEF.xsd and MSH_25_GLO_DEF.xsd

    b. BTAHL7V231Common Project
    Contains datatypes_231.xsd, segments_231.xsd and tablevalues_231.xsd. These schemas define the segments in your standard ADT^A03 schema in the coming project.

    c. Empty BTAHL7 Project

• Contains the ADT^A03 schema. You should use HL7 schema selector utility to get this schema.
• Add New Item > BTAHL7 Schemas > HL7 Schema Selector. Choose the values as below

Build the first two projects (BTAHL7V2XCommon Project and BTAHL7V231Common Project) and create a reference in the BTAHL7 Project. This is important because the datatypes, segments and tablevalues schemas define the nodes in the ADT schema.
So, below is how my final solution is going to be like;

Strong name the projects, name your application and deploy the solution.

ADMIN CONSOLE

Now, the configuration part; I’ll have;

1. A Request-Response port and a location – To receive the HL7 message and send the ACK / NACK back. Make sure this port runs under a 32 bit host.

The most important amongst the above properties is the Port. It mediates the message transport between BizTalk and the HL7 sender. Make sure that no other services is using the port number you set. It’s also worth checking if the
firewall is blocking this port number. If so, add inbound, outbound exemption rules and get it opened.

2. A send port – To send the disassembled HL7 message (in XML format) to an output folder.

BTAHL7 CONFIGURATION EXPLORER 

Now, this is a very intriguing part. Users familiar with an EDI Trading Partner Management should easily develop a connect with this component. Only difference is that it’s external to Admin console and here’s exactly where the “Party”
comes into picture. You start by creating a new Party in Admin console.
 

The Party name must match the Party (MSH3) in your sample file which in my sample is Tutorial_ADTSystem. The party is the key that associates the incoming HL7 message to the validation, ACK procedures. No sooner the party is created, it shows up on the HL7 Config explorer. Make sure you refresh. You will also see the schemas deployed from the solution. The config console is inherently smart to recognize

When a message goes thru the BTAHL72XReceivePipeline, it calls to the Config console. The config console is inherently smart enough to realize the Party name within the sample file, loads the settings and does the validation, disassembling and acknowledges the sender.

Below are the settings at each Tab you have to make to get this sample working.

1. Party Aliases – No changes. You will see the party name, Tutorial_ADTSystem listed by default.
2. Batch Definition – We aren’t doing debatching here. So this is irrelevant.
3. Batch Schedule – No changes here either.
4. Acknowledgement
   1. Change Acknowledgement Type to Original Mode
   2. Check Route ACK to send pipeline on request-response receive port
5. Validation
   1. Check Validate Body segments
   2. Check Allow trailing delimiters (separators)
   3. The schema name space defaults to https://microsoft.com/HealthCare/HL7/2X
6. MSH Map – We don’t need anything here either.

Save the settings are you are almost done!

TESTING 

As I have no real time HL7 system to test my solution, I am going to have to leverage onto alternate simulation methods. Fortunately, HL7 accelerator comes with a pair of fine utilities that let you simulate receive and send for MLLP adapter. Navigate to Drive: \Program Files (x86)\Microsoft BizTalk 2013 Accelerator for HL7\SDK\MLLP Utilities and you will locate the below utilities there;

You need to execute these utilities from command prompt. In my tests, I’d only need the MLLPSend.

You could read more on this at https://msdn.microsoft.com/en-us/library/ee404935.aspx

Let me explain my test cases. Process a

1. Clean file with a valid header segment (MSH), and body. [GoodMsg.txt in the attachment]

For starters, open a cmd and set the path to the MLLPSend utility folder.
   CD Drive: \Program Files (x86)\Microsoft BizTalk 2013 Accelerator for HL7\SDK\MLLP Utilities

- Edit and copy the below command onto the window and submit.
MLLPSend.exe /i localhost /p 10000 /SB11 /EB 28 /CR 13 /f "—filepath--\GoodMsg.txt" /twoway

- This sends my file to the two way receive location, ReceivePort2Way.MLLP we created thru port 10000.

- The file is first disassembled against the ADT^A03 schema and validated to true.

- Since it being a two way port, the ACK is sent back over the same channel by the response port. You will get to see a RESPONSE file in the same folder the source file resided, thanks to MLLPSend. And it content looks like below. The “AA (Application Accept)” value in the MSA segment signifies that the transaction was a success.

- The resultant xml message is subscribed to by the file send port, SendOutput.FILE.

2. File with a valid header, but invalid body composite. [InvalidDate.txt in the attachment]  

This file contains an invalid datetime stamp in its third row as highlighted:

- I execute the same MLLPSend command with the exception of the filename.
   MLLPSend.exe /i localhost /p 10000 /SB 11 /EB 28 /CR 13 /f "—filepath--\InvalidDate.txt" and below is how my RESPONSE file is going to be like.

- My HL7Receive pipeline instantly found the datetime value to be invalid and threw a “Data type error”. And if you take a closer look, you will see that MSA flag changed to “AE (Application Error)” this time.

3. File with an invalid header [InvalidHeader.txt in the attachment]  

I deliberately messed up with the Party name and the MessageType here.

- I had no acknowledgments this time. However, event logs showed me what happened.

Validation error in header during parsing
Error # 1
Segment Id: MSH
Sequence Number: 1
Field Number: 9
Error Number: 200
Error Description: Unsupported message type
Encoding System: HL79999 

Error # 2
Segment Id: MSH
Sequence Number: 1
Field Number: 9
Error Number: 201
Error Description: Unsupported event code
Encoding System: HL79999

- It clearly couldn’t recognize the message type of the message and without any further ado rejected the message.

I hope this helped you with a fundamental understanding of how the HL7 message processing works in BizTalk.Microsoft started supporting HL7 accelerator alongside ROSETTANET and SWIFT in BizTalk 2006 though these standards existed before that. And there has been an overwhelming improvisation rate on this area ever since. I am confident that the coming years would see the advent of more and more interesting features on the accelerators.

Written BY
Rajkumar Damodaran

Reviewed BY
Maria Quian

Microsoft GTSC

TestFiles.zip