Jayant Singh Website - Healthcare IT Blog

HL7 over HTTP

There are few implementations of HL7 v3 around the world and many of CCD/CDA. Another promising standard FHIR – Fast Healthcare Interoperability Resources is on its way.

With all these movements in market, an integration analyst like me (who still loves HL7 v2) loves to see new initiatives on HL7 v2. One such initiative is HL7 over HTTP – specification available on HAPI project site.

When I first read about this about 2 weeks ago, I started exploring the ways to implement it. I had some technical challenges to use this API:

  • I don’t know java (a typical software developer excuse :)
  • I never had an opportunity to use nHAPI (a .NET version of HAPI) in any of my projects. But I found it very easy to learn & use for this exercise.

So I tried a simple implementation in C# for R&D and not to develop an API. I wish to spread this (initiative by HAPI project team) among people who do not know java.

Here is the implementation:

SimpleServer – This class uses System.net.HttpListener

This will listen for HTTP requests on specific URL like http://localhost:8889/


public Dictionary<string, EndPoint> EndPoints;


EndPoint – This class will serve as base class. We will derive this class to create end points.

For example, class ADTEndPoint : EndPoint

This will provide us ADTEndPoint, which will be accessible on http://localhost:8889/ADT

This way we can extend all the required end points from EndPoint class

We will override ProcessMessage() function of EndPoint class in each child class to provide end point specific processing of received HL7 message. Depending on our processing we will return HL7 ACK message or error message.


When we have implemented all the endpoints we will add these to the dictionary of SimpleServer


server.EndPoints.Add("ADT", new ADTEndPoint());
server.EndPoints.Add("LAB", new LABEndPoint());


server.start() will start the server & our server will listen for HTTP POST requests.


If we receive a request for endpoint which is not available in dictionary of SimpleServer, we will send HTTP 400 – Bad Request with ContentType: text/html.

Whenever server receives any request on ADT end point it will trigger ProcessMessage() function overridden in ADTEndPoint class to process that message and generate ACK for it.

  • If ACK is AA, we will send it with HTTP 200 - OK, ContentType: application-hl7-v2
  • If we encounter any error while processing the message, we will send HTTP 500 with error message - ContentType: text/html

Here is an exapmle of how to implement an End Point by extending EndPoint class


class ADTEndPoint : EndPoint
        public ADTEndPoint()
            Name = "ADT";
        /// <summary>
        /// Process Message
        /// </summary>
        /// <param name="strMsg">HL7 message in string format</param>
        /// <returns>HoHResponse</returns>
        public override HoHResponse ProcessMessage(string strMsg)
            HoHResponse resp = new HoHResponse(); //HoH response - contains ackCode, hl7 ack msg & error msg
            Message msg = null;
            IMessage hl7Message = null;
            PipeParser hl7Parser = new PipeParser(); //nHAPI Pipe Parser
                hl7Message = hl7Parser.Parse(strMsg);
                msg = new Message(hl7Message);
            catch (Exception ex) // Exception occured while parsing the message
                resp.ackCode = "0"; // send response with custome ack code of 0 - means failure - HTTP 500 will be sent
                resp.errMsg = "Unable to process incomming message, error: "; + ex.Message; // err msg
                return resp;
            //implement any custom logic to process the message here
            //after processing the message, let's generate ack
            IMessage ackMessage = null;
                ackMessage = msg.generateACK(); //this will generate ack(AA) for the message..
                //ackMessage = msg.generateACK("AE", new MyException("failed processing the message"); //this will generate ack(AE) for the message..
                resp.ackCode = "AA"; // set response ack code
                resp.ackMsg = hl7Parser.Encode(ackMessage); // set response ack message
            catch (Exception ex)
                resp.ackCode = "0"; // send response with custome ack code of 0 - means failure - HTTP 500 will be sent
                resp.errMsg = "Unable to generate ACK, error: " + ex.Message; // err msg
            return resp;



Now, let's initialize our HTTP server & add this end point

SimpleServer ss = new SimpleServer("http://localhost:8889/");
ss.EndPoints.Add("ADT", new ADTEndPoint()); // add ADT endpoint http://localhost:8889/ADT
ss.EndPoints.Add("LAB", new LABEndPoint()); // add LABendpoint http://localhost:8889/LAB
ss.start(); // start http server

I do not have any mechanism to provide downloads here, those who are interested in full source code can request me by email. Other than exploring Hl7 over HTTP, this source code also provides ways to use HttpListener & HL7 message/ack creation using nHapi.

Download Requests

Name Date Comments
Ned Shah ( This email address is being protected from spambots. You need JavaScript enabled to view it. ) 3rd Jun 2013 I read your articles on your website re HL7 and found them very informative. I appreciate your help and contribution of your research work with the community. Do you mind share your HL7 Http code with me.
Maqbool Hussain ( This email address is being protected from spambots. You need JavaScript enabled to view it. ) 25th Apr 2013 I have read your article "HL7 over HTTP", which is very interesting and I enjoyed lot. It's great work and is really helpful in my one of healthcare project. I would like to have complete source code of your sample, explained in article.
Nevin Brittain ( This email address is being protected from spambots. You need JavaScript enabled to view it. ) 23rd Apr 2013 I would like to see the .NET solution. Please send me the source code.