Thursday, 3 November 2016

Setting the Encoding in HL7 Soup

I’ve been working on an integration to an old HL7 system where all the messages are encoded with ASCII.  This was causing values like ┬Ámol/L to show as ?mol/L in HL7 Soup.  It also impacts characters like the copyright © symbol.

OK, so there was a very simple fix – I just had to upgrade to the latest version of HL7 Soup, then everything just started working.  However, in the process I found out some new encoding features.

You can actually set the encoding that is to be used in the HL7 Soup config file.

Navigate to the HL7 Soup Config file found at

C:\Program Files (x86)\Popokey\HL7 Soup\HL7Soup.exe.config

And copy it to your desktop.

Open it up in notepad and locate the Encoding setting

<setting name="Encoding" serializeAs="String">
    <value>Default</value>
</setting>

To change the value across to ASCII

<setting name="Encoding" serializeAs="String">
    <value>ASCII</value>
</setting>

To change the value across to UTF-8

<setting name="Encoding" serializeAs="String">
    <value>UTF-8</value>
</setting>

Save the file and copy it back to C:\Program Files (x86)\Popokey\HL7 Soup\

Overwrite the existing file with this edited version

The Default option suggests that loading documents is to use the default encoding on the PC, but once it is sent it will just use UTF-8. I think that the Default will be the best for most users, but the option is still there if you need to force a change.

If you force ASCII or UTF-8, that will be used for both loading and sending messages.

Monday, 25 July 2016

Mirth CertificateException No name matching found

I keep getting emailed questions about this error, so I thought it would be time to put the answer on the web.

Web Service Sender error
ERROR MESSAGE: Error invoking web servicecom.sun.xml.internal.ws.client.ClientTransportException: HTTP transport error: javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: No name matching xxxxxxx.com found

You get this message in Mirth Connect when trying to call a web service destination. Here is the problem. Mirth seems to generate the wrong Location URI.

Here you see that I don’t have https in the address, but the Location URI has been generated with the ‘s’

clip_image001

The reverse applies sometimes too.

The work around is simple, just edit the text or the Location URI to match that of the WSDL URL (add or delete an ‘s’). The greyed out text box might make you think this is disabled, but not true – it’s just a poor UI choice.

Here is the full error message.

Web Service Sender error
ERROR MESSAGE: Error invoking web service
com.sun.xml.internal.ws.client.ClientTransportException: HTTP transport error: javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: No name matching xxxxxxx.com found
                at com.sun.xml.internal.ws.transport.http.client.HttpClientTransport.getOutput(Unknown Source)
                at com.sun.xml.internal.ws.transport.http.client.HttpTransportPipe.process(Unknown Source)
                at com.sun.xml.internal.ws.transport.http.client.HttpTransportPipe.processRequest(Unknown Source)
                at com.sun.xml.internal.ws.transport.DeferredTransportPipe.processRequest(Unknown Source)
                at com.sun.xml.internal.ws.api.pipe.Fiber.__doRun(Unknown Source)
                at com.sun.xml.internal.ws.api.pipe.Fiber._doRun(Unknown Source)
                at com.sun.xml.internal.ws.api.pipe.Fiber.doRun(Unknown Source)
                at com.sun.xml.internal.ws.api.pipe.Fiber.runSync(Unknown Source)
                at com.sun.xml.internal.ws.client.Stub.process(Unknown Source)
                at com.sun.xml.internal.ws.client.dispatch.DispatchImpl.doInvoke(Unknown Source)
                at com.sun.xml.internal.ws.client.dispatch.DispatchImpl.invoke(Unknown Source)
                at com.mirth.connect.connectors.ws.WebServiceDispatcher$DispatchTask.call(WebServiceDispatcher.java:734)
                at java.util.concurrent.FutureTask.run(Unknown Source)
                at java.util.concurrent.ThreadPoolExecutor.runWorker(Unknown Source)
                at java.util.concurrent.ThreadPoolExecutor$Worker.run(Unknown Source)
                at java.lang.Thread.run(Unknown Source)
Caused by: javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: No name matching leandrovm2008c.winscribe.com found
                at sun.security.ssl.Alerts.getSSLException(Unknown Source)
                at sun.security.ssl.SSLSocketImpl.fatal(Unknown Source)
                at sun.security.ssl.Handshaker.fatalSE(Unknown Source)
                at sun.security.ssl.Handshaker.fatalSE(Unknown Source)
                at sun.security.ssl.ClientHandshaker.serverCertificate(Unknown Source)
                at sun.security.ssl.ClientHandshaker.processMessage(Unknown Source)
                at sun.security.ssl.Handshaker.processLoop(Unknown Source)
                at sun.security.ssl.Handshaker.process_record(Unknown Source)
                at sun.security.ssl.SSLSocketImpl.readRecord(Unknown Source)
                at sun.security.ssl.SSLSocketImpl.performInitialHandshake(Unknown Source)
                at sun.security.ssl.SSLSocketImpl.startHandshake(Unknown Source)
                at sun.security.ssl.SSLSocketImpl.startHandshake(Unknown Source)
                at sun.net.www.protocol.https.HttpsClient.afterConnect(Unknown Source)
                at sun.net.www.protocol.https.AbstractDelegateHttpsURLConnection.connect(Unknown Source)
                at sun.net.www.protocol.http.HttpURLConnection.getOutputStream0(Unknown Source)
                at sun.net.www.protocol.http.HttpURLConnection.getOutputStream(Unknown Source)
                at sun.net.www.protocol.https.HttpsURLConnectionImpl.getOutputStream(Unknown Source)
                ... 16 more
Caused by: java.security.cert.CertificateException: No name matching leandrovm2008c.winscribe.com found
                at sun.security.util.HostnameChecker.matchDNS(Unknown Source)
                at sun.security.util.HostnameChecker.match(Unknown Source)
                at sun.security.ssl.X509TrustManagerImpl.checkIdentity(Unknown Source)
                at sun.security.ssl.X509TrustManagerImpl.checkIdentity(Unknown Source)
                at sun.security.ssl.X509TrustManagerImpl.checkTrusted(Unknown Source)
                at sun.security.ssl.X509TrustManagerImpl.checkServerTrusted(Unknown Source)
                ... 29 more

Friday, 24 June 2016

HL7 Soup Review

It might come as no surprise to my readers to hear I’ve started a little love affair with a delightful piece of software. It’s not something that happens often in the world of medical integrations; that software captures your imagination and yet fits so seamlessly with the way you already work. But that’s how I feel about this delicious treat called HL7 Soup.
HL7 has always been tedious to work with, counting pipes, unintuitive codes, and unreadable dates. So by necessity, there have been a number of apps designed to help deliver you through the jungle of an HL7 Integration. But before I discovered HL7 Soup I always found these to either little more than putting a message in a tree view or something nearly as fiddly as HL7 itself.
HL7 Soup just seems to focus on the human element of an integration, providing you depth but still focusing on clarity. By that I mean it is uncluttered, there aren’t buttons and menus everywhere, but it presents your message from several angles all at once in the manner an architectural diagram presents you a house.
HL7 Soup window definitions
The first of these elevations is what they call the interpretations window. I don’t think I like the name much, it’s a bit of a mouthful, but it is a unique view on the message that must be essential for those wanting to learn HL7, and just a big time saver for old dogs like me.
Put simply the software tries its best to read the HL7 message and present you with sentences that represent the topics within. Ultimately it produces a story about the patient and the visit. I’m pretty sure you can picture how this helps the beginner, but what makes this helpful to the expert is that the whole thing is covered with hyperlinks that change the context of every other view when clicked. Click the age of the patient for instance and you can instantly see their date of birth, ready for you to work with inside the raw view.
The raw view of an HL7 message is still where I find myself working most of the time. Because I’ve been working with HL7 for so long I just find it more natural than tree views. But even this view offers a plethora of simplifications to help me work with the message. I love that clicking on a field with a table automatically gives me a drop down, just like the auto-completion I’m used to within Visual Studio. Better still is that it includes the definitions, not just the values like some of the alternative tools I have used. In fact, every character you click on gives you a descriptive tooltip that puts all the useful information right in front of you.
Instead of a tree view, HL7 Soup includes a color-coded grid. Different colors represent different depths in the message. This does a good job of grouping together related values. But as I mentioned earlier, I mostly prefer working in the raw view, so I can’t authoritatively say if the use of a grid is better than the more traditional tree view. But I think it is worth noting that date values in this view actually have a calendar, and tables have lookups.  This might make for the deciding vote when you can actually see and change dates with ease.
The final view is another that just works like you feel it should. It lists all the messages that you have loaded in a list. Sounds simple I know but I just love the way it works with filters. You can create views of relevant messages, and then manipulate just the current ones in bulk. This is incredibly helpful, but mostly I just appreciate how intuitive it all feels.  All other HL7 software I have used always feels so cumbersome in comparison when working with lots of messages.
Intuitive is, therefore, the how I would sum up this app.  Everything is there, but it doesn’t feel hard to find. Right-click in the message and every command you need becomes available. Open a badly formatted message and it just fixes for you. If you type an invalid date it just highlights it and tells you what is wrong.
What this all boils down to is by using HL7 Soup as your HL7 editor you become an instant HL7 expert.  I don’t make a phone call without having it handy now.  I can talk about an integration type I’ve never used before and sound like I’m totally familiar with it.  I have a little laugh to myself when I hear people on the other end of the line counting out the pipes or trying to determine what the PID-25 value is for.
It saves me time and money, and that is totally the point of software like this.  But it is how it connects with the way I work that makes HL7 soup the best HL7 viewer/editor on the market.









Tuesday, 21 June 2016

Sending and Receiving HL7 Messages

HL7 Messages are normally sent using the MLLP protocol.  For those that are interested, that just means there are a couple of characters at the front of the message to signify the start, and a couple of characters at the end the signal the conclusion of the message.  Other than that it is really just plain text.  For the most part though you don’t really have to worry about MLLP at all as most HL7 software is just going to handle it for you.  You’ll see in my illustrations that I’m using HL7 Soup which is probably perfect for most people too.

I’ll start by creating a test where I just send the message from HL7 Soup back to the same instance of HL7 Soup.

Start by configuring the receiver by clicking on the drop down for the “Receive” button and selecting “Create New”.  You’ll then be presented with the Receiver configuration dialog.

clip_image001

Here you configure the receiving address and port for you message.  For the more technical readers, you’ll notice that this configuration is for TCP communication.  MLLP sits on top of this. 

Because we are sending to ourselves we will use the server address of 127.0.0.1, which is just a relay address according to TCP\IP.  It will send the message straight back to the sender.  The default port HL7 Soup uses is 22222, but you are welcome to change this as required.

So that’s it.  Basically you can just load up this dialog and accept the defaults and you are done.  Your welcome to change the Name if you like, but then just click ok and your receiver is created.

If only creating the sender was that easy.  Actually, only joking – it is exactly the same for creating the sender.  Just click the “Send” button, the send dialog loads, accept the defaults, click ok and you’re done.

clip_image002[1]

You can now send a test message by clicking “Start Receiving”, the clicking the “Send” button a few times.  You’ll see the message going through, and the responses coming back too.  If not then see further on in this document for the trouble shooting section.

HL7 Message once received should always return a response to the sender that lets them know everything went ok. An Application Accepted response message (AA) signifies the message was received and processed without problems.  If things went wrong then an (AE) is sent, and if the message was rejected it’s an ER.  HL7 Soup shows these in different colors so that they are easy to spot. You also have the option to load only successful, errored, and/or rejected messages into the UI, and you can also configure the receiver to respond in a fixed manner to help with testing. 

Sending to another computer on the same network is exactly the same process, just the addresses are a bit different.  It also can be a bit fiddler because of firewalls etc.

All you need to do is adjust the Server IP address for both the Sender and Receiver configurations to be the IP address of the Receiver.  Yep, they will both have the same IP address, and they will both have the same port.

So how do you get the IP address I hear you ask?  Well when you are on the Receiving computer just load up a command prompt and type ipconfig.

Here you will find the IP address that should go into the configuration.  Note that you don’t need to use IP addresses, and it works perfectly well with DNS too.  That means the Server text box can just be the name of the computer.

That’s it, you should now be able to just start the receiver, and click send a few times to watch you messages fire across.

Troubleshooting:

Although it’s normally pretty straight forward there are a number of things that could go wrong, so here is a list of things worth checking:

1. Make sure that the ports are the same on the sender and the receiver.

2. Make sure the Server address is the same on the sender and the receiver.

3. If you are using IP Addresses in the Server text box then change to the computers network name, or vice versa.

4. Ping the receiver from the sender to make sure they can talk over the network.

5. Turn off the windows firewall on both computers (or configure HL7 Soup to be allowed to use the desired port by whatever means your firewall allows)

Please let me know if there is anything else that should be added to this list and I will add it to help others.

Monday, 23 May 2016

Custom Metadata in Mirth Connect

Have you ever wanted to see more details on Mirth's channel dashboard? It would certainly be handy if you could see the patients Id, but depending on the purpose of your channel there might be all sorts of relevant information - Visit ID, Referring Doctor, Etc.

Fortunately Mirth supports this with the feature they have called "Mirth Custom Meta Data".

clip_image001

It's also pretty easy to use, if a little non intuitive. In your channel, navigate to the summary tab and then add fields to the Custom Metadata section

clip_image002

Here I have added a Patients name variable to the existing two (these two are here by default when the channel is created - they can be removed if you don't like them).

The column name is how you would like it to be named on the dashboard. It is pretty restrictive on allowed characters, so don't expect to put in a space or anything like that - basically you are defining a database column in the D_MCMx table in Mirth's database.

clip_image003

The data type also correlates with the database type, so choose one that suits your data.

The Variable Mapping just creates a variable name. It doesn't accept expressions, so you will have to populate your variable elsewhere, most likely in your source transformer like so.

clip_image004

Here I am mapping the HL7 PID.3.1 to my PatientId variable.

That's it, I've done it. The best thing is that not only can I easily identify patients on my dashboard, but also searching for them is much faster (if you have ever run a search for text in the dashboard you will know how painfully slow it normally is).

Further, I can just as easily add any other fields I find useful.

Tuesday, 17 May 2016

Converting a .NET date to a Mirth date

A colleague was having a problem in Mirth where they were trying to get a date sent in from a .NET app to a Web Service Listener. It was a patients date of birth, and it was formatted in the .Net WCF service way - ISO 8601.

yyyy-MM-ddTHH:MM:ss

They needed to convert it to a US date format. Here is what they had been trying:
DateUtil.convertDate('yyyy-MM-ddTHH:MM:ss', 'mm/dd/yy', msg['Correspondence']['MedicalDemographics']['Patient']['DateOfBirth'].toString());
This looks fine on the surface, but Mirth doesn't like that "T" sitting in the date. I've never found a workaround other than removing that "T". This is particularly easy to do here because date of birth doesn't have a need for the time anyway. So we just take the first 10 characters and convert with that.

DateUtil.convertDate('yyyy-MM-dd', 'mm/dd/yy', msg['Correspondence']['MedicalDemographics']['Patient']['DateOfBirth'].toString().substring(0, 10));
You can do the same for dates with times, but I will save that for another post.





Friday, 13 May 2016

HL7 Message Types

HL7 Message Types are a key part of the HL7 specification as they inform us what a messages purpose is.  I thought it would be helpful to create a beginners guide to introduce the basics that you need to know as you get started out in HL7.

Firstly it’s important to know where to find the message type.  The first line of an HL7 message is always the MSH.  Count the number of |’s and the message type is always after the 8th |.

E.g.          image

The message type is broken into two parts by the ^ character.  The first one is the Message Code which categorizes what the message is for (Administration, Scheduling, Orders, etc.) and the second part is the Event Type that signifies what action is being taken (Add, update, delete etc.)

While researching this post I came across this video on HL7 Message Types which uses this very helpful HL7 tool called HL7 Soup.  You can just paste in your messages and it tells you the details of the message type – very helpful.  I’m using it for the screen shots in this post, so I thought I might share this little bag of goodies with you.

There are dozens of different message types available to be used, but you’ll find that there is just a handful that you will use often, so for the sake of simplicity I'm going to focus just on these.

image

HL7 Soup lists them all – look at the scroll bar to get an idea of how many Message types there are!

ADT:

The most common message type I work with is ADT which stands for Admission, Discharge, and Transfer.  The Event Types available for this are also very numerous, but they are well defined and therefore pretty easy to select

image 

Depending on your use case, the most common message will likely be the A04 for registering an outpatient.  This contains the basic administrative details of a patient, their primary health care provider, and details about the visit.

An A08 is sent to update these values, so is also another popular event type.

There is also an inpatient alternative to the A04, the A28.

SIU:

These are scheduling messages for people, equipment and rooms.  There aren’t too many Event types for this messages type, and I only ever seem to use a few of them (S12, S13, S14, S15, S17)

image

I have a little mnemonic for remembering SIU message; I call them See-You messages as they are often used for scheduling appointments with doctors.

ORM:

Order messages are used for all sorts of purposes, and you’ll probably have a need for them for something.  It really depends on what area/department you are in as to what the use case would be.  Radiology would use them for ordering X-rays, Pathology would use them for specimens etc.  The basic thing to keep in mind is that they are requesting something

There is only one Event Type I have ever used for an ORM, and that is the O01.

image

 

ORU:

These are providing results from one system to another.  All the Event Types are unsolicited, meaning that they are sent once a system produces the results e.g. When the x-rays been examined and a diagnosis has been made.

Within this message are the segments ORC, OBR, and OBX that are used to transfer information of the order about.

The ORC and OBR contain information about the order, while the OBX is the actual values being passed.  I’ve seen all sorts of OBX values, from a list of blood test results, to whole medical documents.

image

Once you have selected the Message Type you can then add each of the Segments you need.  Each Event Type has it’s own list of valid Segments that can be added.  It’s not uncommon for HL7 to be abused, and for Segments that are not valid for the selected Event Type to be included anyway, after all the HL7 format is very flexible.  But I suggest if the design of the message is under your control that you hunt for a different Event Type that better conveys the data you need to transfer.  HL7 has been about for such a long time that it’s pretty thorough and it is very unlikely that you are working on something in medical that hasn’t been done before.

When looking for the appropriate available segments the documentation on HL7 is very comprehensive, but it does take a bit of hunting to find exactly what you need.  Again I found an HL7 Soup feature that solved my problem.

With a message containing the Message Type you’d like to use, click on the header of the message, and you get a nice drop down that list all the Segments available for the current Event Type.  You can then just double click on an item to add one to your message with the correct number of ’|’s.

image

I like to create a follow up post on this one at some point looking either at more message types, or going into the details of particular ones.  I’ll look forward to your feedback.