Validate HL7 messages against a profile
What this tutorial covers
The Validate HL7 Transformer extension adds the Validate HL7 Message activity to Integration Soup. Use it when you already have an HL7 Soup validation profile and want an automated workflow to check each incoming HL7 message before the message is transformed, delivered, or accepted as good data.
The supporting video above shows how validation sets work in HL7 Soup: invalid date checks, lookup table checks, multiple validation sets, and exporting rules for customers or colleagues. The written guide below focuses on using one of those saved profiles in an Integration Soup workflow.
Before you start
- HL7 Soup and Integration Soup installed.
- A saved HL7 Soup validation set/profile with the rules you want to run.
- The exact profile name, including spacing and capitalization.
- An Integration Soup workflow that receives or creates a typed HL7 message.
- The Validate HL7 Transformer extension MSI.
Download IntegrationSoup.ValidateHl7Transformer.msi
Step-by-step guide
- Create or choose the validation profile. In HL7 Soup, use the Highlighters and Validation window to build a validation set for the customer, feed, application, or message type you care about. Give the set a clear name because the workflow activity uses that profile name later.
- Install the extension. Run the MSI on the machine hosting Integration Soup. If the Integration Soup service is already running, restart it so the new custom activity is available to the Workflow Designer.
- Open the workflow that receives the HL7 message. The activity works best when it is placed soon after the receiver, parser, or earlier step that still has the message as an HL7 activity message.
- Add the Validate HL7 Message activity. Insert the activity before downstream transformation, delivery, or database work. That gives you a clean place to stop or route bad messages before they affect other systems.
- Pass the HL7 activity message into the validator. In the activity message template, right-click and choose Insert Activity Message. This keeps the incoming content as an HL7 message object rather than flattening it into plain text.
- Set the Profile parameter. Enter the exact name of the HL7 Soup validation profile you want to apply. If the profile name does not match, the workflow will not be validating against the rule set you expected.
- Read the JSON response. The activity returns JSON describing the validation outcome. Use that response in later steps to log errors, branch the workflow, alert support staff, quarantine the message, or stop delivery.
- Test with one good and one bad message. Send a message that should pass and another that should fail one of the validation rules. Check the workflow logs and the response JSON before relying on the activity in production.
What to place in the parameters
- Profile: enter the exact name of the HL7 Soup validation set you want this activity to run. Use a practical name such as a customer, feed, application, or message type so the workflow is obvious later.
What to place in the activity message
The incoming activity message must still be an HL7 message in the HL7 message template. The simplest approach is to insert the message directly from the earlier HL7 receiver or HL7 activity.
If the content has already been flattened into plain text before it reaches this activity, the validator cannot treat it as an HL7 message. Keep the typed HL7 message available until after validation, then convert or transform it if your workflow needs to.
A good workflow pattern is receive HL7, validate against profile, then route or transform based on the JSON result. That keeps invalid messages visible and stops bad data before it is harder to diagnose.
What the activity returns
The response message is JSON describing the validation outcome for the profile you selected. The exact structure depends on the validation result, but the important idea is that later workflow steps can inspect the response instead of relying on a human to open HL7 Soup and review the message manually.
- Passing messages: continue to the normal destination, transformation, database write, or acknowledgement path.
- Failing messages: write the JSON result to a log, send an alert, move the original HL7 message to a quarantine folder, or return a failure response to the sender.
- Warnings: branch separately if your validation profile distinguishes warnings from hard failures.
Useful checks and troubleshooting
- The activity cannot find the profile: confirm the profile name exactly matches the saved HL7 Soup validation set name.
- The message always fails or cannot be read: check that you inserted the earlier activity message as an HL7 message, not as plain text.
- The activity is not available in the designer: restart the Integration Soup service after installing the MSI and confirm the extension was installed on the same machine that hosts the workflow.
- The JSON result is hard to use: log one passing result and one failing result first, then bind later workflow decisions to the fields you actually see in your environment.
- The rules are too broad: create separate validation profiles for different feeds, message types, customers, or receiving applications.
Typical uses
- Rejecting or quarantining invalid HL7 messages before transformation or delivery.
- Logging validation failures for troubleshooting, reporting, or support review.
- Using validation results to drive workflow decisions automatically.
- Letting customers or suppliers test against the same profile before they send production messages.
Related tutorials and downloads
- Validate, highlight, and compare HL7 messages
- Integration Host Getting Started Part One
- Mastering the Integration Host Workflow Designer
- Extension Library Directory
- Download HL7 Soup and Integration Soup
Video Transcript
The target extension page did not originally have its own embedded video. This transcript is for the related validation-profile video above, which shows how to create and manage the HL7 Soup validation sets that this transformer activity can run.
Read the full transcript
Hello, and welcome to this tutorial where we look at how to validate, highlight, and compare your HL7 messages.
I'm going to start by loading HL7 Soup. We see here that it comes with a list of sample messages, and these are what I will use to demonstrate the features.
Let's start with the basics and look at how we can highlight a particular field in every message. For argument's sake, I will set my patient's last name to always highlight as green so I can easily find it. I'll quickly click in the interpretations window to find the last name, and now I can right-click and select to highlight the last name, PID-5.1, green whenever the field is in the message.
Now you can see that this field is highlighted green, and it shows that way for every message I have going forward. This makes it much easier to find.
You probably noticed, however, that the rules extend beyond just checking for its existence. If I go back to the highlights menu, I can select other options, like equaling or containing a certain value, or when it actually has any value. I can also go to the Not indicator and highlight where it is not a certain value or does not have a value.
If I highlight a date field, I get options that are more suitable to date values, such as greater than or less than. I can, for instance, highlight this date orange when it is older than 2014. This might be when a system change took place, and the orange can warn me of a risk.
Notice if I change this date, it only highlights when the date is older than 2014.
The red color highlight has been given additional functionality. It is reserved for invalid values, those that deserve special attention. One bug I find frequently with HL7 messages is invalid dates. It is surprisingly difficult to spot this issue without highlighters. Let's add a red invalid highlighter to this date field.
Now notice as I change this date's value to an invalid month, we see it instantly highlights it red, but it goes further and adds an error message to the interpretations window, and also highlights any other currently loaded messages that have the same problem.
If I right-click on my messages list, I can create a filter that shows only valid or invalid messages, so I can work through them and find my issues.
By the way, HL7 Soup has validations out of the box that check for invalid dates on the most popular HL7 message types.
Another popular highlighter shows when your fields need to have values that are in the lookup tables. Let me show you by marking any administrative sex fields, PID-8, invalid if they are not found in the data table. See how HL7 Soup instantly highlights all the messages and also gives a detailed description of what is wrong.
So now that we have some highlighters, let's see what can be done to manage these.
Navigate up to the Highlighters and Validation window, and we can see the list of current highlighters. From here we can change any of the existing highlighters we have made, including the ability to change the values to anything that we like, values that were not in the original message. We can even add custom text that will show in the field's tooltip or in the invalid message description.
Something I find extremely helpful is the ability to create different sets of validation. To clone an existing set, I simply click the plus button and give the new set a new name. This allows me to create rules specifically for a certain customer or application, then easily jump back and forth between them.
Perhaps most importantly of all, I can even export these validation sets to my colleagues or customers so they can take advantage of them. Imagine being able to create validation rules that ensure messages will work with a certain integration, and then allow others to use this. Your customers or suppliers could be given the set and have the chance to make sure their messages conform before you even get them.
From the management window, we can also generate a bulk list of highlighters from the existing message. This allows us to rapidly build large sets. For instance, let's validate all invalid dates and data tables.
If I go back to the sample messages, we can see that they all have lots of errors. This is because the samples come from real-world examples that did not often conform to the data tables. However, because of the highlighting, it is very easy to go through and fix these as required.
Now I'm going to create a new highlight set, clear out all highlighters, and show off some of the other generation features.
Firstly, there is the Does Not Exist highlighter. Once generated from an existing message, this will make sure that all other messages have the same segments and fields as a minimum. The fields do not need values, but they must at least be in the message. It simply creates a filter for the last field in each segment that ensures it is there.
Then we have the Value Is Empty highlighter. This scans the current message, looking through all fields and components. If they have a value in this message, then a highlighter will be created that suggests they need to be in other messages too. Fields missing from the current message do not have to be in other messages.
Finally, we have the Value Is Different highlighter, or simply the message comparer. It creates a highlighter for every field and component and checks that it has the same value. I can now take two messages and see exactly how they differ. I can even generate this from the second message so it highlights both ways. Very helpful when you are looking for subtle differences between messages.
Don't forget that HL7 Soup comes with a free 30 day trial, particularly helpful if you'd like your customers or suppliers to use your validation rules on their messages without cost.
You can download HL7 Soup by Googling HL7 Soup and clicking on the free trial.
Also, if you have found my videos have helped you, then please click like or subscribe to the series so YouTube can inform you when more tutorials are released.
Comments and suggestions for future videos are very welcome.