Sunday, 8 May 2022

Processing HL7 in the Cloud

While Integration Host has long been my preferred program for processing HL7 messages I've only really used it in local settings. Being able to handle workflows in the cloud was something I've wanted to do for a while now so you can imagine my delight when I saw the announcement on their website that their program was now available as a Docker container and that they'd already published a tutorial on getting it up and running on Azure as a container instance. 

 It's stupidly easy to get going and the Azure container instance pulls directly from their Dockerhub repo so there's no mucking around with downloading and uploading files. All in all, I can see this being a popular way to use Integration Host going forward.

Tuesday, 22 February 2022

Change HL7 Soup Senders or Receivers to a text Encoding that is not listed

 Not all text Encodings are listed in the HL7 Soup UI.  It makes it too noisy for most users, so only the common ones are there. However, you can change it to any installed encoding via the following steps.

  1. Create your sender. Set the Encoding to 8859-1 and save it.
  2. Close HL7 Soup
  3. Load the file in notepad C:\ProgramData\Popokey\HL7Soup\Settings\1\FunctionSettings.json
  4. Search in the file for the name of your sender.
  5. Change the Encoding property to your Encoding. Google "C# encodings" if you want to find the official encoding name.
  6. Save the file
  7. Reopen HL7 Soup.

Now, if you send with that sender, it will use your Encoding.

Monday, 13 December 2021

Sending Client Certificates with an HTTP Sender in Azure

If you are running inside an Azure App Service and you need to send a client certificate with you message, you'll need to follow these steps. 

             1. To configure the location on the key vault in the config "KeyVault:VaultUri".  Set it with the URL of your Azure Vault

             2. Another app setting, set "WEBSITE_LOAD_USER_PROFILE" with the value of "1".  Without this you will get the error "The system cannot find the file specified"

             3. Add a certificate with a private key in the Azure vault.  You can generate one in the azure vault.

             4. Under the App Service settings/Identity/System Assigned, turn status to ON.  Copy Object ID

             5. In the Vault / Access Policies, Add Access Policy.  

             6. Add Secret Permissions (Get)

             7. Add Certificate Permissions (Get, List)

             8. Set the Principle to the App Service using the object ID you got at step 4.

             8.1 Click "Add", and then also click "Save".  "Add" doesn't save even though the window closes, and this caused me much frustration.

             9. In the workflow, configure the http sender to use the vaults name of the certificate as the thumbprint.

             10. This was a very helpfull page that enabled me to work all this out


Note:  Integration Host stores the certificates once they have been acquired in memory.  It costs money and performance to keep pulling the certificate from the vault.  If you update the certificate, don't forget to restart the app.

Monday, 6 December 2021

Create a self-signed Client Certificate for Mutual SSL authentication

Here are the instructions for creating a self-signed Client Certificate for Mutual SSL authentication.  These can be used to client authentication in HL7 Soup, Integration Host, and their deployments to AWS and AZURE.

  • Install Open SSL.  I got it from here: It requires a $10 paypal donation.
  • Run Win64 OpenSSL Command Prompt from your start menu.
  • CD to the directory you will create your certificate
  • Execute the following commands.  You will want to run them one at a time, and they will ask you for details about your business.  Fill it all out:

openssl ecparam -name prime256v1 -genkey -noout -out client1.key

openssl req -new -sha256 -key client1.key -out client1.csr

openssl x509 -signkey client1.key -req -in client1.csr -out client1.crt -days 1000 -sha256

openssl pkcs12 -export -out client1.pfx -inkey client1.key -in client1.crt 

  • Double-Click the PFX to install it into your user certificates.

Very handy😊


The Azure Certificate Vault also allows you to generate a certificate that has everything you need. It was very easy to do.  You can then export it as a PFX. 

Wednesday, 10 November 2021

OID for MSH-3

A lot of the state COVID reporting requires that the MSH-3 uses an OID in their HL7 for the sending application.  Yeah, I normally use a human-readable code as a preference as I think that's more helpful, but some states require it.

HL7 Soup OID is:


Integration Host OID is:


So you end up with a message that looks like


Thursday, 4 November 2021

Updating a database for each OBX in HL7

The other day I needed to loop over each OBX segment in my message, and call an INSERT statement (or Stored Procedure) in my database. I know there are many ways to do this, but this was so simple that I thought it was worth sharing.

Obviously, in Integration Host (HL7 Soup), the trick is to build up a variable inside a ForEach transformer loop.  With each iteration, append the variable with another INSERT statement.  Add a semicolon at the end of your line to separate this query from the previous.

Note how I am setting the Query variable with its value first.  This builds up the text with each iteration.

Now you just head over to your Database Query activity and insert (right-click option) your variable as the Query Text.

How super simple was that! All done in a couple of minutes.

The only thing to watch out for is that this would be open to a SQL Injection, so only do it for controlled/sanitised data that doesn't allow Mr Johnny Drop Tables to crash your system.

It's all very much like this tutorial if you want help getting going.

Thursday, 16 September 2021

Looping over repeating OBX values and updating the segment

I regularly need to update HL7 messages as the data flows between systems. Often, it's significantly cheaper to take the feed designed for another integration and massage the HL7 message before passing it onto your integration.  

With Integration Host you generally just remap using the Transformers and it's all very simple. But the other day I got a wee bit tangled when trying to update OBX values.

I wanted to loop over each OBX segment, look at the value in the OBX-3.4, then use some conditions and lookup tables (note: loving lookup tables right now) to alter the value before inserting it back into the OBX-3.2.

So I used a FOREACH transformer to loop over the OBX values, then put the OBX-3.4 into a variable that I then updated to the value I needed.  This was all easy, but the trick came when I tried to write the value back into the same OBX line the FOREACH was on.  My mapping just wrote each value into the first segment, overwriting it each time, leaving the last in place. This stumped me for a bit and I contacted HL7 Soup support.

It turns out that the loop is only looping over the incoming OBX values, not the outgoing ones, so you can’t use it to set the value in the destination message.  Rather you need to create a different HL7 path for each iteration and set that value.  Apparently, they looked at creating a feature in the UI to allow this several times, but it turns out that code is by far the easiest way:

//Update the OBX-3.2 on the same index as the for each loop.
IHL7Message destinationMessage = (IHL7Message)activityInstance.Message;
string path = $"OBX[{workflowInstance.GetVariable("ForEachIterator")}]-3.2";
destinationMessage.SetValueAtPath(path,  workflowInstance.GetVariable("UpdatedValueVariable"));

Above, you can see that you just construct the path we wish to write to using the forEachIterator variable (which is automatically populated by the FOREACH Transformer), then set the path in the destination message with the needed value - the variable "UpdatedValueVariable" in my case.