HL7 Soup

Steps

Welcome to this quick guide on converting an HL7 message to a JSON file using HL7 Soup's Integration Host. This powerful software simplifies the conversion process, allowing you to automate the transformation of HL7 messages into JSON format effortlessly. Ideal for those familiar with HL7, this guide will walk you through setting up an automatic conversion process. For newcomers, consider checking out introductory HL7 tutorials before proceeding.

1. Get Integration Host Ready

   Install HL7 Soup's Integration Host, utilizing the 30-day free trial or the free development license for testing and development purposes.

2. Initiate a New Conversion

   In Integration Host, select "new" to start a new conversion project in the workflow designer.

3. Set Up File Monitoring

   Name the first step (e.g., "Get HL7 File") and set a directory (e.g., C:\hl7toJSONexample) for monitoring incoming HL7 files.

4. Create a Message Template

   Use a sample HL7 message to create a template, facilitating the mapping of HL7 segments to JSON fields.

5. Configure File Output

   Add a file writer activity (e.g., "Create JSON File") to define where and how the JSON file will be created and stored.

6. Map HL7 to JSON

   Design the JSON output structure in the workflow designer, mapping the HL7 fields to their corresponding JSON attributes.

7. Save and Test the Workflow

   After naming the workflow (e.g., 'HL7 to JSON'), save your settings and test the conversion by dropping an HL7 file into the monitored directory.

8. Handle Complex Conversions

   For advanced data mapping, use the Transformer feature to iterate over repeating segments like OBX.

9. Troubleshooting

   Utilize the logging feature within Integration Host to diagnose and resolve any issues encountered during the conversion process.

Converting HL7 to JSON is straightforward with Integration Host's intuitive interface and powerful mapping tools. By following these steps, you can automate the conversion process, ensuring efficient and accurate data transformation. Whether you're handling simple conversions or complex data mappings, Integration Host facilitates a seamless integration experience.

Video Transcript

Convert HL7 to JSON:

Hello and welcome to this tutorial where we're going to show you how to convert an hl7 message into a JSON file. This video assumes that you've got some knowledge of hl7 so if you don't, I suggest you have a look at my other hl7 tutorial first and then head back here for the nitty-gritty.

So let's begin we have our sample hl7 file over on the left and a sample of what the JSON file will look like once we've finished. Both in a similar hierarchical structure but they are not related formats; the bad news is that there's no automagically conversion between these formats we're going to need to map them. I'm going to show you how to set up an automatic conversion so all you need to do is drop an hl7 file into a directory and it spits out a JSON file. This is possible because we've got the world's best software to do it, which of course is hl7 Soup's, Integration Host.

There's a 30-day free trial so that you can do all this too - better yet if you're training, teaching, or just want to have a play, there's also a free development license you can sign up for. It never expires just can't use it for the live data. Take your pick which license you want to follow along with.

So here it is, this is the Integration Host. The main screen is the dashboard used to monitor your conversions, but first, we need to create a conversion. You just right-click on the left panel and select "new" to load up the workflow designer and define our conversion.

There is so much you can do with workflow designer that goes well beyond the scope of this tutorial; you can connect to all sorts of medical hardware and software together. TCP Web Services database all that sort of stuff. If you'd like to know a little bit more about that, take a look at our getting started tutorials in the link at the top right of the video.

We're going to just dive right in so if you recall, we're going to convert from an hl7 file to a JSON file.

So first, we need to pick up that file, and I'm going to scan for that file. I'm going to call this step "get hl7 file", and I'm going to search in a directory for a file, and I'm going to have it in C:\hr7toJSONexample.

I'll put that in as my directory. We are looking for HL7 from files so that filter is already correct.

We are going to set it to wait for more files to be added. That just means it will keep processing the files are added, and once the file has been processed, we're going to delete it.

We could move it to another directory, but there's no need to do that for this message type.

Now the message template is just an example of what the message is going to look like so I have this one which I prepared earlier. This is just taken from the hl7 soup editors sample files. I'll paste it in here.

The reason I have it is it's got PID information and a little bit of OBX data too. We're going to use that to show the simple way and perhaps a slightly more complicated conversion as well.

Now I've pasted it in we've got a tree over on the right-hand panel; this represents the hl7 message we can see in the message template.

You'll notice if I click on an item inside the tree it highlights the exact same place in the message template vice versa. If I click on something in the message template highlights back in the tree and there's also the search message. Another thing that's helpful to notice is as you move your mouse over the hl7 message you automatically get a highlight of where you are inside the message. So you can easily find what you're looking at.

Now we have the message coming in; we need to write it to another directory. I add another activity, and we're going to make this a file writer.

We'll call this "Create JSON File".

Now I have to give it a file name and path. I want to write it out to this out directory I'm just going to place it in to help me out, and then I just need to get a file name.

I kind of like to have that file name sort of self-generated so what I'm going to do is I'm going to use the message type that was passed into us. That's the MSH-9.1. I'm just going to drag that message type into the file name, and that's created what's called a variable that's going to be replaced at runtime with the actual message type. Then just to make it unique as well, I'm just going to right-click on it and say insert the variable, and I'm just going to put the current date-time. I also want to give that current date-time a specific format. The hl7 dates are perfect for file names because they have got no funny characters in them.

The maximum records for a file should be one as this is a JSON file.

Do we need to write it to another directory after processing now again? Only if you have some sort of locking issues.

Message type; I'm going to write it out as a JSON file.

Now we just need set the message template.

I've got a cut-down version of our JSON file that I'm going to start with.

I just wanted to show you the sort of basics before we go on to the more complicated things.

You can see this JSON file has a patient with the ID, first name, and last name. There are some sample values in there currently. We can replace those values with the variables just like we did in the file name.

So with that ID, I can navigate to the patient's ID, and I just drag that into the message. I get the patient's family name and maps to the last name the patient's given name which maps to their first name and finally their date of birth.

With the date of birth, we are going to want to format that again to a .net date format.

I'm going to name this workflow, and it's going to be called 'hl7 to JSON'. That's done so I'm just going to hit the save and close button here.

If we navigate now back to the Integration Host, we will see that this converter is sitting there running and ready to go. It's processed zero messages so far, so let's test it out.

I'm going to go into my example directory where I prepared some files already. I've got a sample hl7 file just sitting here, so I'm going to copy the file, and I'll drop it into this directory for processing. You can see it's processed that one message. If we now look in the out directory, we're going to see a JSON file. I'll load that up a notepad, and you can see it's got the ID first name is John last name is Smith it's got the date of birth in the right format, so that's worked perfectly fine.

That was a straightforward example of how to convert from HL7 to JSON. Let's make this a little bit more complicated now and what I'll do is I'll go back to the original file that I had on the screen. You'll see it's got the same stuff that we've already done. The ID, the first name, last name, and it's also got a group of results. That's going to make things a bit more complicated. I will take the result section, and I'm just going to copy that back to Integration Host. Double click on the conversion to open the workflow and head over to the second step, and where we will append the result section into the message.

Now we've got the full message we've still got our variables here bounden and as you can see what we need to do is we need to produce multiple items.

There are multiple results one, two, three, and we need to get those out of here. We've got the OBX results we want to get in. You'll notice that there's four of them here and there is three of them here. If it happened to be exactly the same thing I could just continue mapping like early was, but in actual fact, there could be any number of results, so we're going to have to build those results as we go.

We will do this via string manipulation. We're going to build this section here, over and over, and we'll be inserting those into the message. So I'm just going to start by copying one of those, and now we're going to head into what's called the Transformers.

Transformers are steps to convert from one message type to another.

On the left-hand panel, we've got all the source values and the right-hand panel we've got the destination values. We could have done this earlier in here. We could just take the patient in drag, so the patient ID and that message and it creates a binding between those two, but we're not going to use that technique because of the complexities I'm about to show you. What we're going to do instead is we're going to try and loop over all the OBX values that are in this message. To do that I click on the bottom transformer, and I'm going to add a new one just below the highlighted one, so I add a 'for each', and that's because we're going to loop over the OBXs. I'm going to grab one of those OBX bindings. I'm just going to grab the header of it and drag it into the source path. That's effectively saying I'm going to loop over all the OBX values. Something to watch for here I've seen people make this mistake before, there are two options here if your text is green that's bound and if iText and Variables were selected, you'll notice that the text would be blue.

That means a literal OBX text value, so you're not going to be looping over that. I'll just drag in the bindings I'm going to use as the observation. I want the value as well, which is OBX-5. It's going to populate these values in a loop. We need to create another variable, and I'll add it below this one, and I've got a set variable value. I'm going to call this variable 'result', and I'm going to add the text that I grabbed from the destination message. I just need to replace these bits. I'm going to use the observation value. It's going to loop over, and it's going to build up this text, but of course, that would put the same value again into the same variable, so we want to make sure it appends. What we do is we just put the values that are currently in that variable first. Okay so that's going to build up a list, and then it's going to have a comma after each one. That's good for JSON except for the very last one. If you've got a comma in the very last one JSON doesn't like that. I'll use a little bit of code to do this. I'm going to add a new condition and say if the result is not empty, run some code.

We will insert a code activity, and now it's giving you a whole lot of code by default. This is just example code. I open it in the editor, and it's a bit easier to read as you get all the color coding and everything.

We can extract out little bits of code that we want. There's an example here of how they get a variable value, and there's one to set the variable value. Those are the two that we want and so add this code in.

//truncate the last comma
string result = workflowInstance.GetVariable("Result");
workflowInstance.SetVariable("Result", result.Substring(0, result.Length - 1));

It's just going to remove that last character in the message which will be the comma.

I need to replace the sample values in the message template, and put in my variable for results.

I'll save and close, and let's try that out. It'll error, you can see things are going about hectic, lots of attempts, lots of failures. I'm just going to go stop this. Refresh here so you can see the logs. Logs are beneficial if things are going wrong because you can have a look at the error. You'll see the error message here actually gives us instructions of what we've done wrong. It'ss is a limitation of JSON that it's very strict on not putting funny characters into the JSON message. We just have to edit the workflow, go to the second activity, and change the message type from JSON to Text. We lose all that nice coloring, but it's converted it now for a flat-file, so it's no longer going to be parsed by the runtime engine, which means it doesn't mind the fact that it's got this random field sitting in the middle of the text.

I'm going to save and close it again. I don't want all this junk, so I'm just going to clear out all the statistics. I can just start it up, and it's processed.

We've had success, so I'm just going to refresh the logs and have a look. Here is our new JSON file, and it has the four values, not just the three that the sample message had. It's populated all the fields correctly, and we've got all the other OBX values, so that's worked really well.

If you found this video helpful, you would help me out by ‘liking’ this video.

Download Free Trial of Integration Host