Receive HL7 via HTTP(s)

The HTTP listener device can act as a web service which can receive any type of message. In this example, we will create a channel which receives HL7 messages via a TLS-enabled endpoint.

The first step is to create a channel which contains the HTTP Listener device (and a downstream queue).

In the HTTP Listener configuration, select the IP address and port which your service will listen on. Normally you would be using a static IP assigned to your Connexion host machine, but in this sample we will listen on the local loopback 127.0.0.1.

For this example we will leave the rest of the Connection tab settings default. Check the Enable SSL checkbox and then click the Create Self-Signed Certificate button. This will generate a self-signed certificate and automatically assign it to the port configured previously. In production systems, you will be using 3rd-party purchased certificates (or ones generated by your security staff). In this case you should use the Choose Certificate File button to select a certificate.

Save your channel and then return to the Connection configuration tab. At this point we must manually associate the Connexion service account with the port on which our service will listen. Click the [Run Command] link to make the association.

If the port reservation is successful, you should see a ‘Command Completed’ dialog.

Start your channel. We should now be able to send any message data by POSTing data to https://127.0.01:8485. You can test sending some messages by using the free Postman tool. Since we are using a self-signed certificate, we will need to disable certificate validation within Postman.

This tutorial is about receiving HL7, so let’s try sending some HL7 from Postman. Copy a sample HL7 message into the Postman value field and post the message.

Great! But this service accepts anything, and we want it to only accept valid HL7. This will require us to enter some custom logic in the Custom Actions tab.

The following code was added to the AfterMessageParsed(…) callback:

// use the HL7Message.Create method to parse the sent payload
var hl7 = HL7Message.Create(args.ParsedContent);
if (hl7.Errors.Any())
{
  // if there are any errors, throw a descriptive exception back to the sender
  args.Exception = new Exception($"Invalid HL7: {hl7.Errors.Stringify()}");
  throw args.Exception;
}

For our scenario, we want to ensure the incoming payload is valid HL7. We use the HL7Message.Create() method to parse the incoming payload and provide any parse errors. If there are any parse errors, we throw a new exception with a descriptive message. This will return a 500 status code along with the error back to the sender, effectively rejecting the message.

We could also update the code to the following to alert us when we receive an invalid payload. This might be useful to enable/disable when a customer is unsuccessfully attempting to send data.

public override void AfterMessageParsed(MessageReceivedEventArgs args)
{
   // use the HL7Message.Create method to parse the sent payload
   var hl7 = HL7Message.Create(args.ParsedContent);
   if (hl7.Errors.Any())
   {
     var errorText = $"Invalid HL7: {hl7.Errors.Stringify()}";
     var sender = args.HttpContext.Request.RemoteEndPoint.Address;
     var payload = args.ParsedContent.Truncate(5000);
        
     // log an event that someone tried to send malformed HL7        
     MessageChannel.Logger.Write(EventSeverity.Warning, $"Received invalid payload from {sender}: {payload}");
        
     // if there are any errors, throw a descriptive exception back to the sender
     args.Exception = new Exception(errorText);
     throw args.Exception;
   }
}