HL7 Soup Transformers Tutorial
Return to Tutorial Directory
HL7 Soup Transformers Tutorial
HL7 Soups workflows make it easy to take an inbound message and send or save it elsewhere. But sometimes you need to edit the values a bit first. Sometimes you have to entirely change the message from one type to another!
These are the problems that Transformers is designed to overcome. They transform the message used by an activity with a set of rules, and values from other activities.
Most activities in a workflow are attempting to perform an action on a message of some sort, well in HL7 Soup, we call this message the “message template”.
The Message Template is the base message that the transformer is going to act on. It might just be placeholder showing your messages structure, or it could be a message that’s bound in from your receiver or other activities. The important thing is to realize that the value in the message template is what you will be working on in your transformer.
Editing transformers are easy; most activities have a button in their details, but easier still is the double circle icon that shows when you put the mouse over an activity in the workflow.
Here is our transformers screen.
We have a source tree and a destination tree that are generated from the Message Templates we placed into the activities.
The general goal of transformers is to take values from the source tree and map them to values in the destination tree. The mappings will show here, and their details show here.
For example, we find the patients Family Name in the in the PID-5.1 and drag it across to the Name field in our destination tree. We’ve now created a mapping between the messages that joins the messages together. Each time this workflow runs our transformer, our Destination Message Template will be updated with the Family Name from the Source.
We can even adjust where our source data comes from. Would you like a certain value to come from another activity? Easy, just select your source activity here and watch the message tree repopulate ready to be dragged across. If your activity doesn’t have a response message you can just past one in here and it will reflect back in the activity. The same goes for the destination messages, handy when you forgot to add your Message Template earlier.
You can also easily adjust existing transformers. Clicking on a transformer shows its details, and here you can easily make alterations. Manually adjust the message path, or just drag it in from your source tree. You can even use the anchor button to adjust which activity you are getting your value from.
The type of transformer you’ve just seen is called a “Mapping Transformer”, but there are others. Click here and you can set all that are available to you.
With this one, you can create variables, and I’ll show you what this means in just a minute, but I thought I would also bring your attention to this transformer. It is my own special transformer that I created. It does whatever I need it to do because I wrote it myself in .net. We’ve got a video on creating your own transformers. It’s really easy to do and allows you to do just about anything you like when transforming your data. Better yet, you can even debug your transformers with Visual Studio. But all that is in another video that I have linked to in the comments.
Let’s take a look at what a Variable Transformer is for. We’ll, it creates variables, and variables are simply a place to store values for use elsewhere in the workflow. What’s great about them is you can combine variables with fixed text and other variables to create dynamic or complex values.
For example, I can put a variable value into a file path of a file I’m writing out. I just add the variable, give it a name, navigate to where I want it, and then just right click and insert the variable.
I’ll head back to my Transformers, where you’ll remember I bound the Patients Last Name to my Name field earlier. Well, I would actually prefer this was the patient’s full name written in the format of:
I can’t bind multiple items into my Name field, so I’ll create a Variables that merges this text together.
I create a Variable for the LastName by dragging it in, and I give it the name I want. And now the FirstName, and I rename it too.
Now I create another variable for the full name, I’ll give it a sample value, and then just insert the variables in the order of LastName, then FirstName, and place a comma between these. So now our full name variable is ready, we just head over to my earlier transformer, change it’s source to Text/Variables, and add in the FullName Variable. Done.
When transformers are executed they run in order from top to bottom in this list. That means you have to make sure that variables are set in the correct order. There would be no point setting the Name field with the FullName variable if it hasn’t yet been set. Thankfully, you can easily adjust the order with simple drag and drop. I’ll adjust all of mine into the appropriate order. Great.
To join the names together, I also could have just created my own Custom Transformer, and that could have simplified creating the FullName variable. Fortunately, I can demonstrate this because concatenating the names is exactly what this sample Custom Transformer does. If I add it to our transformers list you’ll see a place for the first and last names. Now I just drag these into the boxes, and it is ready to go. Custom transformers can automatically create variables for you too, and this one creates a variable for called Concatenated Name, so I will set this for my name field instead.
Don’t forget to take a look at our “Custom Transformers” video where we show you how simple it is to create your own transformers, and even provide you with the sample code.
If you find our videos helpful, then please subscribe to this channel, and if you would like to help us out, then please like this video.