Welcome to this tutorial, where we look at PDF and binary inside of HL7 messages. We can see in front of us that I have a PDF and an HL7 message, which has an embedded PDF inside it. It is base64 encoded as they always are inside of HL7 messages. There is a trick to verify this inside of HL7 Soup. If you right-click on that message and select ‘View Document’, it will load up the PDF, enabling us to view the contents of that HL7 message PDF.
In this tutorial, we will take a look at a lot of the things that you can do with PDF’s and binary files inside of HL7.
To start, we will look at the message that we have and extract the PDF and put it in the file system. To do that, we will create a new workflow in Integration Host and set it to listen on a port for us (Port22222).
Next, in the ‘Message Template’ box, right-click and select ‘Insert sample Message’. In this example, ‘ORU^RO1 Observation Message’ has been selected as it often has an OBX inside of it. The message will then come in, and now we need to write out the file.
To do that, we need to add another activity, and in this instance, a ‘File Write’ is selected as the ‘Activity Type’.
In the ‘File to Write’ section "c:\pdf\output\myPDF.pdf" is entered, and then ‘MSH-10 Message Control ID’ is dragged from the ‘Bindings’ in-between ‘PDF.pdf’. This means it will always generate a unique file name. As we want to write out just that OBX value ‘Binary’ is selected from the ‘Message Type’ dropdown. This will take care of the fact that it is base64 encoded because when it is written out to the actual disk, it needs to be a binary file.
Then delete the default binding, select ‘OBX-5 Observation Value’ from Bindings, and drag this into the ‘Message Template’ box. This is going to grab the OBX file, and the next step is to try this out. It will start running. We need to send the message. It was set to listen for ‘Port22222’, and this will be selected from the ‘Configure Sending settings’ at the bottom and then send. It has now come through, and if we refresh the logs, we can see that it has written out the file with the data. It has created the output directory for us, and the PDF will be there.
Let’s say that every time an HL7 message comes through, we need to append a PDF to it.
First, create a new workflow and listen on another port (in this example, port 22223). The message comes in, and we want to append it in a PDF, so we will add another step by running code (‘Run Code’ is selected from ‘Activity Type’. The sample code in the ‘Code’ dialogue box will be deleted, and then ‘Binary’ is selected from the ‘Message Type’ dropbox. Now we need to give it some code, and we can use the code editor to do this. To make this video faster, I will paste in some code I already have.
string filename = @"c:\PDF\January.pdf";
var bytes = System.IO.File.ReadAllBytes(filename);
activityInstance.Message.SetValueAtPath("",Convert.ToBase64String(bytes, Base64FormattingOptions.None));
Now that we have that writing out, it is going to be the output of this activity, and we need to get that into that incoming message. This will be sent after we finish to the other connection we previously created, which was listening on ‘port 22222’.
We now have our HL7 message. It is already bound to this incoming message by default, and we need to append it in a new line. I am going to do that via ‘Transformers’ and add in an ‘Append Segment’. This is just one of the many ways we might want to add it, but it seems pretty logical while tracking an OBX. In the ‘Source Path’ dialogue box ‘OBX|||||’ is entered, and then right-click ‘Insert Activity Message’ and then ‘Run Code Sender’.
Try it out and look at the logs. It has picked it up, run the code on it, and added it into that HL7 message, and it should then be received with the PDF in it. If we view it inside the HL7 Soup editor, it provides another view, and it shows us the logs inside it, which is very useful.
Tip: If we try to view the document, an error message will pop up that states ‘This document was truncated’ because there is a log set up in the system to truncate the messages. This is simply to stop the logs from getting too big. If I wish to open it, it will come up with another error message. To fix this, we go into ‘Integration Host’ and quickly change the message logs and up the maximum size of the MegaBytes allowed per message. If we resend the message again, head over to integrations, and refresh the list, we can see it has come through without being truncated. It is up to the user to set the max MegaBytes allowed per message.
That was one way to do it; now we will look at another.
The previous method was done using the ‘Run Code’ Activity; however, we will add a ‘Code Transformer’ and then select ‘Edit Code’ in this second method.
We will use the same code from the previous method, except we are no longer sending an ‘Activity Message’. This part of the code will be replaced with ‘workflowInstance.SetVariable(“PDF”) This means we are reading in the PDF, putting it into a bite array, base64 encoding it and adding it to the variable called PDF. Then in the ‘Source Path’ box, the ‘Run Code Sent Message’ is deleted, and right-click insert variable and PDF is selected.
To give this one a try, we will go back to HL7 Soup, hit send and then go to integrations and refresh. The new message will be created, and the PDF has been added. If we double click, it should view nicely, and this is the second method of adding in the PDF.
Now that we have covered two different methods let’s look at another scenario. Let’s say we had PDF’s being created, and we want to create an HL7 message every time a PDF is dropped into this directory. We have an output directory; every single time a PDF is put into here, we can pick that up and put that into an HL7 message. To do this, we will create a new workflow and set the ‘Activity Type’ as ‘Directory Scanner’ and copy the file path of the output directory into the ‘Directory’ text box.
In the ‘File Filter’ section, PDF will be entered so that it will search this directory for any incoming PDF’s. The ‘Inbound Message’ section ‘, Binary’ will be selected from the ‘Message Type’ dropdown menu.
There is no message template required for binary.
We will add another step to pick that up and write that out to a file with HL7.
I will put it into the same directory as we are only picking up PDF’s. In the ‘File to Write’ section ‘C:\PDF\output\$(DirectoryScannerFileName).HL7 is entered, and this will write it out as an HL7 file.
The next step is to build the HL7 file so, in the ‘Message Template’, a sample template will be selected. It is prepopulated with dates and the workflow instance ID, but it does not relate to the patient or other variables. In most cases, there would probably be another step here where an ‘Activity Type’ such as ‘Database Query’ or ‘HTTP Sender’ is added to get the data needed to populate the HL7 message. Once this data is populated, we will add in the incoming PDF and put that into the OBX so ‘Insert Activity Message’ and then ‘Directory Scan C:\PDF\output’ is selected.
The next step is to select save and close. It has already created 3 HL7 messages, and the PDF’s are embedded.
If you right-click and select ‘View Document’, it has picked it up and processed it.
These are the different techniques of handling PDF’s or any Binary file.
If you have any questions, please get in touch with HL7 Soup support, and it would be doing me a huge favour if you 'like' and 'subscribe' to the channel. You are welcome to interact and leave a comment on YouTube and do not forget to download the Integration Host or HL7 Soup trials to make sure it is the right solution for you.
