Integrating an HTTPS interface in hospitals using Mirth Connect communication server
A short exploration of the technical challenges faced when we integrate Doctolib within hospital IT systems in a secure manner using a communication server to ensure we delight our users.
At Doctolib, we offer ground-breaking browser-based scheduling software (tap-tap on the shoulder!) for hospitals and medical practices in Germany and France.
Key to ensuring our users love our product is to keep existing clinical workflows intact. We proudly integrate with existing medical software, most of which are hospital information systems, and we do this via programmable interfaces (APIs).
Imagine you are managing the IT network at your local hospital and want your staff and patients to be able to use Doctolib without slowing down your internal processes, such as the admission flow. Naturally, you want the appointments from the Doctolib calendar to be synchronized into your hospital’s primary system, so that your medical personnel can admit and document patients in their primary system (that they already use for all administrative and medical tasks).
Here at Doctolib, it is part of our team’s role to help you do that. However, it presents a unique challenge many people outside of the health-tech world may not realise.
The most efficient way to integrate into a hospital network is by using our state-of-the art web-based and TLS-secure interface, but most existing systems in the hospitals still communicate using a pipe-separated 1980-s style message format (aka HL7 v2) without encryption, running on a different kind of an application layer.
An example HL7 v2 message could look something like the following:
MSH|^~\&|Postman||Doctolib||20200907144441||ADT^A01^ADT_A01|67e4ada8 09318a3cdda5edd7a10b7bb9|P|2.5.1|||||DEU|UTF-8 PID|||573585470^^Doctolib^PI||Bull^John^^^^L||19900101|M|Bull^^^M||| |+491761234567^^^john.bull@mymail.comOur Web API is the preferred way to integrate with hospitals because it runs over HTTP with the state-of-the-art TLS encryption, while a standard hospital software speaks MLLP — a session layer on top of TCP/IP which has been enabling integration between medical software since the early 1990s, but has neither encryption nor integrity checks in place. MLLP is also the de facto standard communication protocol in hospitals around the world.
Bridging the gap between HTTP and MLLP is a recurring challenge for any cloud-based healthcare software provider and can be easily solved thanks to a communication server.
Doctolib works with our clients and partners to bridge this gap and integrate our system into a smooth and natural clinical workflow. And we’ve already done this for multiple clients and projects.
What is a Communication Server?
A communication server (also known as integration engine, enterprise application integration) is a middleman software that connects together the external and internal interfaces in a hospital IT network. Communication servers are capable of converting between different kinds of transport layers, protocols and message formats, and can also transform the data along the way. The communication server would usually convert messages (formatted according to HL7 v2 standard) arising from systems inside the hospital network, to HTTP requests, and send them — encrypted and signed — to the Doctolib server. The same principle applies in the opposite direction too.
There exist many producers of communication servers (Infor Cloverleaf, xTension Orchestra, Enovacom, to name a few). While developing our own independent proof of concept, we chose to rely on Nextgen Mirth Connect — a very common option that many hospitals, medical practices and universities around the world use. Mirth Connect is popular for its ease of configuration, the variety of options, the cross- platform support and a thriving community. Lastly, Mirth Connect is available under a permissive open source license, even though with a somewhat limited functional scope compared to the paid version. Alas, the HTTPS support is missing in the free version.
How to install a communication server?
Mirth Connect (aka Nextgen Connect Integration Engine, since Quality Systems took over Mirth in 2013) is available for free download under Mozilla Public License v.1.1 license. The download instructions are clear. It is important to install JRE (you don’t need to install the larger development runtime JDK, the runtime environment is sufficient). Make sure to pick the right version of JRE, you will find a list of supported JRE versions for the selected Mirth Connect version in the system requirements documentation.
Setting up port forwarding
The problem with the free Mirth Connect version remains, in that it is not capable of forwarding outbound HL7 messages directly to an HTTPS endpoint on the Doctolib server. Thanks to the wonderful Mirth Connect web community, we found a hint. Stunnel is an application that allows to forward data from one socket to another, in particular to forward the outgoing traffic from an HTTP socket to an HTTPS socket.
We configured Stunnel in the following minimal way:
verify = 0
foreground = no
[mirth]
client = yes
accept = 127.0.0.1:9001
connect = {DOCTOLIB_SERVER}:443Stunnel will continue running in the background, while all data which is sent to port 9001 will be automatically forwarded to the HTTPS endpoint on the Doctolib server. With this configuration in place, we can now build our first Mirth Connect channel.
Mirth channel configuration
The concept of a communication server is centred around channels. A channel is a configuration which links one or more inputs to one or more outputs. In Mirth Connect, inputs are called “listeners” and outputs “senders”. When a listener registers a new input, it forwards it to all senders. You may also transform the message along the way if necessary (e.g. stripping the message of the irrelevant information or converting between HL7 message types).
To forward an outbound HL7 message to Doctolib, we need to create a channel that receives HL7 messages in a TCP listener (in MLLP transmission mode) and forwards them to an HTTP port in an HTTP sender. Our Stunnel configuration automatically forwards the traffic from the local HTTP port to the correct endpoint on the Doctolib server.
In just the same fashion, another channel retrieves new updates from the Doctolib server. It does so by polling the server via an HTTP port which is in turn forwarded to the respective HTTPS endpoint on the remote server. Once an update becomes available, the HTTP listener consumes it and forwards it to the MLLP sender inside the hospital network. The MLLP sender in turn informs the primary system (e.g. a HIS) of a new event on the Doctolib server and can reflect appointment creation, modification or cancellation almost instantaneously.
Summary
By employing Stunnel we have been able to send and receive HL7 messages to and from Doctolib using the standard functionality of the open source version of Mirth Connect. By using Mirth Connect we were able to make use of the existing functionality like HL7-conform error handling and out-of-the-box message response generation, without having to reinvent the wheel.
We wanted to share this solution so that it can come in handy for anyone integrating a web-based SaaS interface in networks where systems don’t speak HTTP natively.
We hope you have enjoyed the read and let us know if you have had similar experiences with Mirth Connect and Stunnel!
Useful links:
- Mirth Connect/Nextgen Connect Integration Engine: https://www.nextgen.com/products-and-services/integration-engine
- Mirth Connect Open Source version on Github: https://github.com/nextgenhealthcare/connect
- Stunnel: https://www.stunnel.org/
- Doctolib: https://www.doctolib.de/
Check the list of our open positions if you want to join our team and make a big impact on the healthcare system!
