General Tips and Tricks

Rick Wattras -

General tips and tricks for using Mirth and the OCI resources to the extent of its capabilities. 

Avoid your Mirth session crashing due to running out of memory by increasing the Max Heap Size 

Sometimes you may see the following error, or Mirth may even just crash unexpectedly:

This can be caused by your launcher file only allocating a limited amount of memory to your session. To increase this, browse to the Mirthconnect homepage where you downloaded your launcher file and click the little cog next to the "Launch Mirth Connect Administrator" button. Here you can set the Max Heap Size that will be allocated to your local Mirth session. The default value is 512 MB and you can select up to 2 GB. Note that this is taken from the system where you're launching Mirth so make sure that if you increase this value that your system has enough memory to allocate or you may either see issues launching Mirth or may not be able to take advantage of the additional memory capacity:

View message statistics via the Mirth Dashboard view

On the Mirthconnect homepage where you downloaded the launcher file, there is an "Access Secure Site" button that can take you to a "Dashboard" view of the Mirth instance. Simply click the button and it will prompt you for a username and password, which you'll find is just your Mirth account credentials. If you receive a security notification about the connection not being private, this is just because it's attempting to go from unsecured http to httpS and just doesn't recognize the "localhost" domain. You should be able to just click "Proceed to localhost (unsafe)" if on Chrome or follow the prompts to add the localhost domain to trusted sites if on another browser.
Once you're through the prompt, you'll be taken to The "Dashboard Statistics" page where you'll see the list of running interfaces (you can also click down into the specific Destinations on each interface) and their current or lifetime statistics. This view is read-only and really only provides a look at the number of messages received/filtered/queued/sent/errored for each running interface channel. This can be useful at a high-level but doesn't give you any information about the message content or metadata, or about the interfaces themselves. But it's available should you have need of this type of dashboard view for just tracking message numbers. 

Search the Mirth support forums for info/advice when looking for solutions or troubleshooting a Mirth error

Mirth, being a popular open source tool, has a pretty active community containing a bevy of resources that cross the spectrum of utilization and workflows. Check it out here: http://www.mirthproject.org/community/forums/index.php

If you're troubleshooting a Mirth error, or if you're looking for solutions to problems that you're attempting to build in Mirth itself, the Support forum specifically can be of use: http://www.mirthproject.org/community/forums/forumdisplay.php?f=6

If you still can't find what you're looking for, feel free to reach out to Datica and they can provide their expertise to help you find what you need.

Export all channels at once by turning on "Channels" view instead of the "Groups" view

When in the channel list, if you're currently in Groups mode (see the buttons in the bottom right of the screen) you can switch to "Channels" view and the "Export All Channels" button becomes available in the "Channel Tasks" pane to the left. This will create individual XML files for each channel in the directory of your choosing.

See what a button, setting, or text box is for by hovering over it

This is useful if you're unsure as to what a certain setting does. For example:

Set a timeout of 0 on a sender to not have it ever timeout

For some of the destination senders, you can set a timeout of 0 to allow for it to never timeout and wait infinitely for a response. Be careful that the resource does exist though so you're not causing it to wait forever for nothing! One useful place for this is when it comes to TCP Senders - configuring it to Keep Connection Open and then using a "Send Timeout" of 0 should allow you to keep the connection to the external resource up indefinitely (be aware of network pieces in between that may have their own timeouts however).

CSV file processing settings

You can modify what delimiter to process fields by, as well as whether to ignore a header line in a CSV file via the File Reader "Set Data Types" configuration menu:

  • "Column Delimiter" automatically defaults to the standard ",", but you can set this to any delimiter you like - even tabs via the "\t" character!
  • "Number of Header Records" allows you to set Mirth to ignore the header line (or lines) on incoming CSV files if you don't need to parse it

Using the Outbound Message Template configurator

This is a useful tool that allows you to pre-populate an outbound HL7 (or any other available format) message in order to then build your outbound messages on top of it. So if you have a standard format for an outbound message with some static values then it may be useful to just populate those values automatically:

MSH|^~\&|Mirth||||||SIU^||D|2.3
SCH|||||||||||||||||||||||||
PID|1||||||||||||||||||||||||||||||||||||||
PV1|1|||||||||||||||||||||||||||||||||||||||||||||||||
RGS|1|||
AIG|1|||||||||||
AIL|1|||
AIP|1|||||||||||

However, be aware that you either have to populate each field in the correct order (so PID.3 after PID.2, etc) or you have to pre-build all the necessary fields in the template and just pre-populate them with blank spaces (like PID|1|||||||||||||||||||||||||||||||||||||| above). Otherwise when it builds the message it will write to the fields in the wrong order.

Improve channel performance by not storing unnecessary information

When building a channel, on the Summary tab there is a "Message Storage" section with some useful capabilities. The slider on the left will set how much message content is retained in the database and available for view in the dashboard for each message. You'll see that as the slider goes down, less and less information is retained (for example, dropping it down to "Raw" retains only the raw message content and not any mapped variables or metadata) but the Performance of the channel is increased (the blue "Performance" meter indicates this). This means that it will potentially process messages faster and consume less memory, so if you don't care about retaining extra information but the speed at which the message is processed is important then adjusting this setting could prove useful. 

Queue outgoing messages on failure to continuosly retry sending

In the Destination Settings of a channel (under the Destinations tab in the Edit Channel config), you can modify the Queue Messages setting to automatically and continuously retry when attempting to send a message. By default the "Never" setting will allow messages to flow normally, without any queueing behavior, and in cases where they fail to send they will simply be marked as ERROR in the dashboard and the channel will move onto the next message. The "On Failure" option will queue messages up if they fail to send and will continue to attempt sending until the message goes through successfully. "Always" will always queue the message before attempting to send. Both of the latter queueing-based options are useful if you want the message to continue attempting to send, so for instance if there is a temporary network issue with the receiver it will automatically send the message through when the issue is resolved. Also, they will still allow new messages to flow into the interface and attempt to send on their own destinations, so in this way they don't cause a backup of messages as the Source Queue does. Note however that if the issue that's causing the message to fail is due to something within the message content itself (so that it would be unchanged for each subsequent attempt) then you could possibly see the Destination end up in a QUEUED state indefinitely. Enabling the "Rotate Queue" option int he Advanced Queue Settings (more on that below) will allow for stuck messages to be sent to the back of the queue instead of holding up future messages, which should help to resolve the issue of a single message holding up the queue. However be aware that this does not guarantee that messages will be sent in the order you received them, if order is a concern.

Use mapping variables to save values for later use

Mapping variables like Channel Maps and Global Maps are useful for saving values that you may need to refer back to at either a later point in the channel processing workflow (Channel Map), or even from a different channel entirely (Global Map). Channel Map variables can be stored with the JavaScript freehand channelMap.put("descriptor", value); and are primarily used to pull values from one part of a channel (say, the Source Transform) to a later part (a Destination sender). Be aware that they are not reference-able beyond the current message being processed though. Global Map variables are channel-agnostic, and can even be viewed on the Dashboard under the "Global Maps" tab at the bottom. These values are best utilized for static data, kind of like environment variables. Or you could store something like a message counter value that changes often due to some other logic that manipulates the value but that needs to be referred to by multiple channels or multiple messages. Create Global Maps with the JavaScript freehand globalMap.put("descriptor", value);. Also, if you want to view whether a Global Map variable exists you can use the syntax globalMap.containsKey("variableName") and it will return a boolean true/false as to whether the map already exists or not.

A non-freehand way to map these variables is to use the GUI present in a Transform step inside a Source or Destination transformer of a channel. 

Formatted data can also be saved to a Mapped variable, but it's suggested to save them as strings where possible as that won't cause Mirth to mess with the formatting (for example, JSON might be stored string-escaped characters). See the next tip for an easy way to turn JSON into a string and back. Binary data can be saved, but just be aware that if you view the saved value on the dashboard that it will always just look something like "[B@40ea84a1" as that is the binary object ID. But it's still stored correctly underneath!

Stringify JSON to pass it into Map variable

As mentioned above, Mirth can struggle to store JSON in a channel map without altering the content (ex. string-escaping characters) but this can be avoided by stringify-ing the JSON object you want to store.

When storing the JSON, use the following code:

var objectJSON = {
	"key": "value"
}
var stringified = JSON.stringify(objectJSON);
channelMap.put("objectJSON", stringified);

Then when you want to retrieve it and turn it back into an actual JSON object, use:

var objectJSON = JSON.parse($('objectJSON'));

Manually return an ERROR status for a Destination

If you want to manually cause a message to ERROR out in the dashboard, but also want to provide more error context then you can utilize the Response class detailed here: http://javadocs.mirthcorp.com/connect/3.1.0/user-api/com/mirth/connect/userutil/Response.html

An example usage is: return new Response(ERROR, "The actual response data", "A brief message explaining the reason for the current status", "The error string associated with this response");

This propagates into the message dashboard like so:

  • With the ERROR destination selected, on the 'Response' portion of the Messages tab

  • With the ERROR destination selected, on the Errors tab

Manually route content from within one channel to another channel

If you're using a JavaScript writer and want to pass some content from the current channel to another channel, you can use the built-in router. The syntax is as follows: router.routeMessage('Channel Name', content);

One example usage might be to manually trigger functionality that exists on a different channel, such as error alerting or a dedicated and custom message processor.

Use the built-in DateUtil functions to handle dates

Dates are a common headache when it comes to anything Java or JavaScript-based, but Mirth makes this slightly easier by including a built-in DateUtil library with some useful functions. For example, to get the current datetime in the format of your choosing, simply call DateUtil.getCurrentDate("yyyyMMddHHmm") and it will return the local datetime in yyyyMMddHHmm (ex. "201710101200").

More information and explainations on the other available functions can be found on this Mirthconnect Confluence page here: http://www.mirthcorp.com/community/wiki/display/mirth/Working+with+Dates