In this tutorial we're going to show you how to convert from XML to HL7. I have the sample files here: there is an XML file and the HL7 file that we're going to convert it into. I'll include a link to these if you want to download them and follow along.

Both files have a similar hierarchical structure, but they are not related formats. The bad news is that there is no automagical conversion between the two. We're going to need to map them together. I'm going to show you how to create an automated conversion so all you need to do is drop an XML file into a directory and it spits out an HL7 file.

This is going to be very easy because we're using HL7 Soup's Integration Host. You can follow along with the 30-day free trial, or if you're training, teaching, or just want to play, there is also a free development license available.

Here is Integration Host. This main screen is the dashboard used to monitor your conversions, but before we can monitor one, we first need to create a conversion. We just right-click on the left-hand panel and select New to load the Workflow Designer and define our conversion.

There is so much you can do with the Workflow Designer that goes well beyond the scope of this video. You can connect all sorts of medical hardware and software together: TCP, web services, databases, and all that sort of stuff. If you'd like to know more, take a look at our getting started tutorials. For now, we're just going to dive right in.

To begin with, I need to define how to receive my XML message. I'm going to select a Directory Scanner because I want to pick it up as a file, and I'll call it "Get XML file".

I already have a directory that I want to get the data from. It is C:\XMLToHL7example, so that is the directory to scan for our XML files. We're going to be looking for XML files, so I'll change the file filter to *.xml.

I'll leave the setting "keep waiting for more files to be added" on because we want this to be a permanently running process. In my case, I'm just going to delete the file once we're finished processing, but I could move it elsewhere if I wanted to.

Now we set the message type to be an XML message, and finally we include that XML message in the message template. You can see up on the right that it gets the structure from that message. That is very helpful when we're mapping the messages together.

Now that we've defined where we get the data from, we need to add another step into our workflow. I'm going to write it out as a file, and I'll name it appropriately. Now I just need to define how I'm going to name the file.

I'm going to use that same directory I used before, and I've got an Out directory inside that, so that's where I want it. In this example, I want to create a new HL7 file for every XML message that comes into the system, so I need to give it a file name.

I can insert a variable called WorkflowInstanceID into the file name. It's an ID that increments with each message, so it will make sure that each file has a unique file name. I therefore want to set the maximum records per file to 1, so it creates one message per file.

Now I add in my HL7 file as the message template. This is just a message I took from the HL7 Soup samples. There are a whole lot of different HL7 message types there if you want to base yours on those. Otherwise, if you can get your hands on the actual HL7 message you're going to create, that will be best.

If you don't know your way around HL7 messages, make sure you have a look at some of my other tutorials where we go through the basics of HL7 and load up the HL7 Soup editor. It's a great help for navigating these files.

If you look at the message, we've got our standard message header, patient information, and results information. Here is where we'll map in the XML values. As you can see, there is a little bit of patient information and we also have repeated result values.

We need to drag the appropriate fields from the XML message into the HL7 message. Let me show you how that is done. I'd like the patient to be dragged here, so I'm going to drag that field in from the structure created from the XML message. It automatically creates a variable placeholder in the message.

The idea is that we're creating locations inside the message that will be swapped out at runtime with the other values. The remaining message template will just be left there at runtime. For instance, the sending application and facility details are just going to be hard coded into the message template.

Let's bring in some more of these values, starting with the first name. Notice as I move the mouse over the message I can see exactly where in the message I am, so I know where to drop the binding. That's my first name, last name, and date of birth into the appropriate locations.

I don't have the gender for this one, so I'll remove that field. I'm also going to remove all of these OBX values because we don't have a one-to-one mapping here. We will need to generate an OBX value for each result instance, so for now I'm just going to remove all this additional stuff to simplify it for the demonstration.

What else needs to be done? We probably want to change the date/time in the message, so let's insert a variable. We'll insert the current date/time, and we're going to format that as well. Right-click and select Format Date. We're going to format it as an HL7 date, and I want to include the time up to the seconds.

For the message control ID, we're going to insert the WorkflowInstanceID variable. That's our incrementing value, so each message will have a unique ID. All the other stuff, such as the version number, is fine to keep.

That was super simple. If all you have is a conversion with one-to-one mapping, then that's all you need to do. You would be pretty much up and running.

However, in this example we have a repeating value, so I'll quickly go over the requirements for doing that. We have multiple results, so what we need to do is loop over those results and add in a new OBX value for each one of them. To do that, we need to go into the Transformers section of the activity.

Transformers represent the mappings from one system to the other. As we dropped the bindings into the message earlier, it was creating variables in the background that would be populated in the Transformers. Alternatively, we could have bound the fields by dragging the items from the source tree into the destination tree. Our getting started tutorial goes into that in a lot more detail.

We're going to loop over the results, so we want to add a new transformer step after this one. I right-click in the Transformers list and choose a For Each transformer. That allows us to loop over repeated items.

Now we need to configure what we want to loop over. We want all of these result values. All I need to do is drag the first value into there, and now we've said that we want to loop over every result in this message.

I'm going to take all the values out of each result and put them into variables so I can use those in the message. All I do is drag the value into the Transformers list, and it is created as a variable.

For each of those results, I am going to append a segment into my message. We want the source path to be the value of the OBX message. I can literally type in that segment now: OBX||. At this point, I can start inserting the variables that I've used. I'll put my device here, a couple more pipes, and insert the value and the observation.

You can see that we are creating variables for each of the result values and then appending an OBX value into the HL7 message for each one.

That's our workflow created. It has the nice name "Convert XML to HL7". I'll save and close this workflow.

If we take a look at Integration Host, we now have the workflow sitting there and it's in a running state, so let's give this a try. I'll go back to this directory, take my sample XML message, copy it, and place it into the directory that's being monitored. We see it gets deleted out afterwards.

If I now go to the Out directory, we can see our created HL7 message with its unique file name. If I double-click on that and take a look, sure enough, here is our generated HL7 message.

It's got the correct dates and details. The patient has been brought across. The patient's birth date is in the wrong format, but it at least has the value. We'll fix that in a second. Each of our results has gone in as we defined, so that was great.

I can now edit the workflow pattern by double-clicking, and we'll head back to where the birth date was written. This is a straightforward fix. I just need to right-click on the patient's date of birth, change the formatting for a date of birth, and we want it to be an HL7 date.

Here is a chance to rerun it. I can go back to my directory and paste in another file. You will see the new messages being created. Double-click, and great, the data is now in the correct format.

It is also worth noting the logs that have been generated for each instance. We can view inside those and look at the details of all the messages we created. If we have any debugging to do, this is a great place to do it.