HL7 over HTTP Relay

Basic Configuration

The Relay is configured with a file in the conf directory called config.xml. This file is a Spring Framwork bean definition file.

To configure the relay, you must first understand a few basic concepts:

  • Beans: Each bean element in the config file is a single module which serves a specific purpose. Each bean has an ID which is defined in the config file. The relay is configured by defining multiple beans and "connecting" them to each other using a process that Spring calls "wiring".
  • Listener Beans: Listener beans are used to receive messages.
  • Sender Beans: Sender beans are used to transmit (i.e. relay) messages which have been received by listener beans.
  • Binder Beans: Binder beans connect listener beans to sender beans. In a basic configuration, you will have one listener bean bound to one sender bean using a single binder bean, but you can get more complex by binding multiple beans on either side.

The Listener Bean

The following is a simple example of a listener bean which uses MLLP to listen for incoming messages: 

<bean class="ca.uhn.hl7v2.hoh.relay.listener.RelayMllpListener" id="theListener">
   <property name="port" value="8079"/>
</bean>

The class attribute indicates what type of listener should be used. Listeners must be of type IRelayListener.

The port property selects the port on which the listener will receive messages.

The Sender Bean

The following is a simple example of a sender bean which uses HL7 over HTTP to transmit messages: 

<bean class="ca.uhn.hl7v2.hoh.relay.sender.RelayHttpSender" id="theSender">
   <property name="urlString" value="http://localhost:8080/relayURI"/>
</bean>

The class attribute indicates what type of listener should be used. Listeners must be of type IRelayListener. Configuration properties suported by the chosen implementation (such as "socketTimeout" and "responseTimeout") may also be set here.

The port property selects the port on which the listener will receive messages.

The Binder Bean

The binder bean "joins" a specific listener to a specific sender. In a basic configuration, you will bind one listener to one sender, but it is possible to bind multiple senders to a single listner, or multiple listeners to a single sender. 

<bean class="ca.uhn.hl7v2.hoh.relay.Binder">
   <property name="listener" ref="theListener"/>
   <property name="sender" ref="theSender"/>
</bean>

Binder beans are always of class Binder. Note that the "ref" property indicates the "id" of the corresponding listener and sender.

Advanced HL7 over HTTP Sender

There are a several configuration options you can add to the HTTP Sender in order to meet specific application requirements.

Authorization

In order to add HTTP basic authorization (username/password) to each request, use the following configuration on your sender bean: 

<!-- First, create a credential callback, and provide it with the
     username and password to be transmitted -->    
<bean class="ca.uhn.hl7v2.hoh.auth.SingleCredentialClientCallback" id="theAuthorizationCallback">
   <property name="username" value="hello"></property>
   <property name="password" value="hapiworld"></property>
</bean>

<bean class="ca.uhn.hl7v2.hoh.relay.sender.RelayHttpSender" id="theSender">
   <!-- ... Add other properties to the sender ... -->

   <!-- Add the authorization callback property, referencing your bean above -->
   <property name="authorizationCallback" ref="theAuthorizationCallback"/>
</bean>

TLS (SSL) Encryption

To enable encryption on an outgoing HTTP connection (aka HTTPS), you simply need to provide a socket factory as a property to the sender. 

<!-- 
Define a SocketFactory bean. The TlsSocketFactory bean class creates standard
encrypted sockets using built in trusted keys. This means that this will
only work if the receiving system has a private key signed by a trusted
certificate authority.
 -->
<bean class="ca.uhn.hl7v2.hoh.sockets.TlsSocketFactory" id="theSocketFactory">
</bean>
				
<bean class="ca.uhn.hl7v2.hoh.relay.sender.RelayHttpSender" id="theSender">
   <property name="url" value="http://localhost:8000/relayURI"/>

   <!-- ...other properties go here... -->

   <!-- Add a property for a SocketFactory -->
   <property name="socketFactory" ref="theSocketFactory"/>
</bean>

TLS (SSL) Encryption With Explicit Certificate

To enable encryption on an outgoing HTTP connection (aka HTTPS) using a specific certificate, the process is similar to regular TLS (as above), but you must first put the certificate into a keystore and configure the Sender to use it.

This mechanism is useful in several circumstances:

  • Sending messages to a recipient who is using a self-signed certificate
  • Sending messages to a recipient who wishes to us TLS Mutual Authentication

The following example requires that you have your trusted certificate in a keystore. See Creating a Client Keystore for more information on how to do this. 

<!-- 
Define the SocketFactory itself. Note that this example
assumes that the keystore has been placed in the "conf" directory
within the relay installation, and that the keystore has a passphrase
of "changeit". Make sure the "id" matches the "ref" name in the
property above.
-->
<bean class="ca.uhn.hl7v2.hoh.sockets.CustomCertificateTlsSocketFactory" id="theSocketFactory">
   <property name="keystoreFilename" value="conf/keystore.jks"/>
   <property name="keystorePassphrase" value="changeit"/>
</bean>

<bean class="ca.uhn.hl7v2.hoh.relay.sender.RelayHttpSender" id="theSender">
   <property name="url" value="http://localhost:8000/relayURI"/>

   <!-- ...other properties go here... -->

   <!-- Add a property for a SocketFactory -->
   <property name="socketFactory" ref="theSocketFactory"/>
</bean>

Troubleshooting

In order to troubleshoot the relay if something isn't working correctly, the first thing to try is to increase the verbosity on the log files.

The HL7 over HTTP Relay uses log4j for its logging. The log4j configuration is found in the "conf" directory in a file called "log4j.xml". Open this file for examples of how to increase logging verbosity (look for a tag named "appender").