Friday, September 30, 2022
Home Uncategorized Why You Must Master Mirth's Message Template Tool Today

Why You Must Master Mirth’s Message Template Tool Today

Prerequisuites

  • Basic Knowledge of Mirth Connect
  • Knowledge of Programming in Mirth Connect

Introduction

When writing scripts in Mirth Connect, you have a message template tool that allows you to easily reference the incoming message via code. Furthermore, Mirth supports different data types so these references will differ depending on the data type you select for your channel.

For example, XML is a tree-type data structure, composed of parent and child nodes. The message template tool allows you to simply drag and drop code from the tree structure onto the editor. This piece of code references the data in the XML message that you initially point and clicked in the message template.

The tool is really intuitive to use once you do it a few times. In fact, the best way to learn this trick is just to paste your message in the text box and start dragging and dropping on the code editor. In this article, XML, HL7v2, Delimited Text, and JSON will be showcased with the message template tool.

Accessing the Message Template

There is no singular place where the message template exists. Instead, you can leverage it in almost any part of Mirth Connect that contains a code editor (i.e. Source Filter, Source Transformer, Destination Filter, Destination Transformer, Destination Response). Most commonly, you will use the message template tool in the Source Transformer and Destination Transformer.

If you are scripting in the source or destination transformer, first go to Channels.

Double-click on the channel you wish to begin development on (FILE_READ in this case).

Edit the Source or Destination Transformer by clicking Edit Transformer under either the Source or Destination tabs.

Notice the tabs on the top-right-hand side of the transformer screen.

Select the Message Templates tab.

Notice you have an inbound and outbound message template. The data types for both the inbound and outbound reflect the data types that you have chosen under the summary section of your channel.

You can change these on the Summary tab itself or by selecting the drop-down.

You can also access the properties of your data type by selecting the Properties button.

Before leveraging the message templates, you must create at least one JavaScript step in your transformer. You can do this by clicking Add New Step under Transformer Tasks.

A new row will appear above. From here you will change the type to JavaScript.

This is when you will see the code editor appear on your screen.

Lastly, note that the inbound and outbound message templates work exactly the same way except for the variable that they use. The inbound template uses msg while the outbound template uses tmp.

HL7v2

Inside your HL7 channel, select the Message Templates tab and paste your HL7 into the text field.

Next, select the Message Trees tab.

Here you will see each segment contained in the example message. If there are optional segments in potential messages, make sure that they are included in your sample message. Otherwise, you will not be able to drag and drop anything from the Message Trees tab.

Next, expand one of the segments by clicking the small + icon to the left of the node.

From here, you can expand specific fields to see individual components and sub-components.

Notice the green nodes in the message tree. These are the nodes that you can drag and drop into your code editor. You will also notice that the value of your sample message appears in the message tree. In this scenario, MSH.4.2 of the sample message has the value ‘LINDAS TEST ORGANIZATION’.

If you drag and drop ‘LINDAS TEST ORGANIZATION’ onto the code editor, you will see the following.

Since this value was pulled from the inbound message template, it uses msg. From there, Mirth uses an XML referencing scheme. You will notice that the first index is the value of the segment (i.e. MSH), the second index is the value of the field (i.e. MSH.4), and the third index is the value of the component (i.e. MSH.4.2).

Lastly, Mirth will automatically add the toString() invocation (this converts the serialized XML value into a JavaScript string). Once you drag this onto the code editor, you can assign it to a variable for future use in your code.

Delimited Text

The delimited text message template looks similar to that of HL7. A delimited text file could be a CSV (Comma Separated Value) or Pipe-Delimited file, for example.

Say that you need to process a CSV file that contains patient data. The first column contains the patient ID, the second column contains the first name, and the third column contains the last name.

On the Message Trees tab, you will see the following structure.

Drag the FirstName value out unto the code editor. You should see the following.

The first index references the row and the second is always the column. Now, consider referencing a delimited text file with multiple rows.

If you were to access the first name in the second row, the reference would look like this.

Notice the index reference after the row. The ‘1’ index tells us that we are referencing the second row in the delimited file. Note: index referencing always starts at 0 in almost every programming language so 1 would be the second row.

XML

The XML message tree is similar to that of HL7. Consider the following SOAP (Simple Object Access Protocol) envelope:

<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"
    xmlns:wsa="http://www.w3.org/2005/08/addressing">
    <soapenv:Header>
        <wsa:Action soapenv:mustUnderstand="true">urn:ihe:iti:2007:RegisterDocumentSet-bResponse</wsa:Action>
        <wsa:RelatesTo>urn:uuid:D7D54C00006A3C11D00000872150000</wsa:RelatesTo>
    </soapenv:Header>
    <soapenv:Body>
        <rs:RegistryResponse xmlns:rs="urn:oasis:names:tc:ebxml-regrep:xsd:rs:3.0"
            status="urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success"/>
    </soapenv:Body>
</soapenv:Envelope>

Paste it into the inbound message template.

Select the Message Trees tab.

Here you can expand the message tree to access the data within the envelope. Notice that the nodes that represent attributes are prepended with a ‘@’. This can be seen when you drag an attribute node onto the code editor compared to when dragging a tag node onto the code editor.

Consider the @xmlns:soapenv node:

Which appears as the following in the code editor:

Next, consider a different attribute node that is not an XML namespace.

Notice that the namespace function isn’t invoked this time. Additionally, the .@* notation is used to account for the soapenv namespace that prepends the mustUnderstand attribute.

Lastly, consider a non-SOAP XML message. For example, this could be a CDA (Clinical Document Architecture).

Say you want to reference the data within the text tag (i.e. ‘Some Data’ in this case). To do so, you would type (or drag) the following onto the code editor.

Next, notice the attribute named testAttribute in the CDA above. It contains a value, “test”. To reference “test”, you would do the following in the code editor.

Again, notice the @ which denotes that the node is an XML attribute.

At this point, you should have a good understanding of what is required to reference XML data within your Mirth Connect channel. XML is one of the most common data types in Healthcare Integration so learning how to manipulate it within Mirth is vital to your success as an Integration Engineer.

JSON

Using JSON in the Message Template is very similar to using XML in the Message Template. This should make sense to you because XML and JSON are considered alternative data types. In fact, you will often see HTTP responses returned in either JSON or XML (Although, JSON is still the most common).

Now, consider the following JSON message.

Which will display as follows when you select the Message Trees tab.

As you’ve done before, drag patientId onto your code editor. This piece of code will evaluate as 123456789.

Similarly, you can do the same for street, which will evaluate as ‘Main St’ when the code executes.

At this point, you should have noticed that Mirth always uses XML-style referencing for every data type. This is because internally, mirth stores msg and tmp as serialized XML.

This is convenient for Mirth professionals as many different data types can be referenced the same way.

Mastering the manipulation of data in Mirth Connect is an essential skill for any Integration Engineer.

RELATED ARTICLES

Mirth Connect Extensions: What You Need to Know

Prerequisistes Basic Knowledge of Mirth Connect Overview Users can navigate to Mirth Connect's Extensions screen by selecting Extensions on the left-hand side. You should now see the following...

Take a Tour of System Settings in Mirth Connect Now

Prerequisites Basic Knowledge of Mirth Connect Introduction Mirth Connect has a multitude of system settings that are available for configuration. In larger companies, there will often be...

Make Sense of HL7 v2 Messages Effortlessly Now

Prerequisites Beginner Knowledge of HL7 Introduction If you've been in Healthcare Information Technology for any period of time, you have definitely heard of HL7 (Health Level 7)....

Most Popular

Mirth Connect Extensions: What You Need to Know

Prerequisistes Basic Knowledge of Mirth Connect Overview Users can navigate to Mirth Connect's Extensions screen by selecting Extensions on the left-hand side. You should now see the following...

Take a Tour of System Settings in Mirth Connect Now

Prerequisites Basic Knowledge of Mirth Connect Introduction Mirth Connect has a multitude of system settings that are available for configuration. In larger companies, there will often be...

Why You Must Master Mirth’s Message Template Tool Today

Prerequisuites Basic Knowledge of Mirth ConnectKnowledge of Programming in Mirth Connect Introduction When writing scripts in Mirth Connect, you have a message template tool that allows you...

Make Sense of HL7 v2 Messages Effortlessly Now

Prerequisites Beginner Knowledge of HL7 Introduction If you've been in Healthcare Information Technology for any period of time, you have definitely heard of HL7 (Health Level 7)....

Recent Comments