1. Mirth Connect
2. Home
3. Upgrade Guides (Official)

Created by Ken Tucker, last modified on Feb 27, 2017

The Mirth Results plugin is an extension for managing and posting to Mirth Results endpoints. With it you can post clinical documents to a Mirth Results server, or use the Mirth Results client (or libraries like CDAPI / HL7API) in JavaScript, without having to manage connection pooling or libraries. Also, the Mirth Connect server does not need to be restarted after adding a new Mirth Results resource. This guide is meant to assist upgrading existing Mirth Connect to Mirth Results implementations to the new extension.

Currently, you are probably posting messages to Mirth Results manually using a JavaScript Writer:

You may also have a similar deploy script which is initializing the MirthResultsClient object:

The new extension doesn't require any manual JavaScript to post messages to Mirth Results, so you'll be replacing that current code with the new Mirth Results Sender destination connector.

The Mirth Results extension is installed like any other Mirth Connect extension. This can be done through the Mirth Connect Administrator in the Extensions view, or by extracting the contents of the provided ZIP file into the extensions directory inside the Mirth Connect installation directory.

Icon

After restarting the server, make sure that you launch the Mirth Administrator by clicking the Launch Mirth Connect Administrator button and not using a previously downloaded JNLP file.

For each different Mirth Results server you'll be connecting to, create a new resource on the Resources settings panel. Enter the connectivity information and set SSL-specific options if applicable. If you will be using the libraries associated with the resource (MR Models / CDAPI / HL7API) in one of the global scripts, check the checkbox in the Global Scripts column. Once all changes have been made, save the resource.

Each channel that was previously manually posting to MR in JavaScript should now use the new Mirth Results Sender destination. Select one of the resources you created earlier, and the data type to post (HL7 v2.x, CDA, or CDM). For CDA documents, the source and receiver IDs are also necessary. For HL7 v2.x you may also choose to post the original data along with the modified message. If there is no modification happening on the source connector and the message coming into the channel is the original raw data, then "${message.rawData}" will suffice. Otherwise, you may need to retrieve the original data from somewhere else, such as through a source/channel map variable.

For Mirth Results Sender destinations, queuing is always recommended (set to Always). Advanced queue settings recommendations will change depending on the implementation though.

If your channel implementation involves many channels that directly post to Mirth Results without the use of a central routing channel, then the destination queue threads should usually be left at 1. This is because the Mirth Results resource itself has its own connection pool (you can set the size on the resource settings). So even if you have 10 channels each with 10 destination queue threads all posting to Mirth Results, the actual number of simultaneous requests will still be limited by the connection pool size set on the Mirth Results resource (e.g. 10).

However, if your channel implementation involves many channels routing messages to a single channel which does the actual posting to Mirth Results, then you should consider increasing the number of queue threads (e.g. to 10). You could have done that before with the JavaScript Writer, however when using multiple queue threads order wasn't guaranteed. In order to get around that existing implementations may be using multiple destinations with an identical JavaScript Writer, but with mutually exclusive filters:

For example, in the screenshot above you can see that each destination uses the same JavaScript Writer (using one queue thread), but also has a filter that only accepts the message if the patient MRN ends with a specific digit (0 through 9). That way, messages for the same patient will always be sent to the same destination queue, and therefore will always process in order.

In 3.2 however, there is a new destination queue setting called the Thread Assignment Variable. With this, you can use multiple queue threads and still preserve message order for certain messages. For example if you add "mrn" as a channel map variable:

Now, all messages with the same value for "mrn" will always process in order. Messages with different values for "mrn" may be picked up by different queue threads and processed simultaneously. So there's no longer any need to make 10 (or however many) destinations with mutually exclusive filters. Instead use a single destination with multiple queue threads and the new Thread Assignment Variable setting. If you decide later that throughput should be increased, you can simply increase the number of queue threads on the queue settings; no need to clone the destination a bunch of times.

Also, if the destination has a transformer that utilizes the libraries provided by the Mirth Results server (such as MR Models, CDAPI, or HL7API), the Regenerate Template and Include Filter/Transformer options are also recommended to be enabled. This is because when you use those libraries manually to, say, build up a CDM document, the final CDM XML generated could be different for differing versions. So for example, say you generate CDM XML using a certain version of CDAPI, and then that message gets queued. If in the meantime you upgrade Mirth Results to a newer version, then the previously queued message may always fail to post, because the generated XML is out of date.

When you include the Mirth Results resource on the channel / script using CDAPI, the libraries get automatically reloaded whenever a Mirth Results Sender using the resource detects that the version has changed. So if the destination using CDAPI has queuing enabled, then the Include Filter/Transformer option will allow you do re-create the CDM XML on each queue attempt. If it fails the first time, then after the libraries get reloaded, on a subsequent queue attempt the transformer script will be run again with the new libraries in the context, so on that attempt the CDM XML should be correct.

Once you've made all necessary changes, save and redeploy the channel.

If any other channels aren't posting messages to Mirth Results but instead are using the libraries to call other methods on MirthResultsClient (or using classes within MR Models / CDAPI / HL7API), you should set the appropriate Mirth Results resource on the channel/connector.

On the channel's Summary tab, click on the Set Libraries button. Here you can apply the resource to specific contexts. If you're using the libraries in one of the channel scripts (deploy / undeploy / preprocessor / postprocessor / attachment / batch), select the Channel Scripts node. If you're using them in a specific connector, select that connector. Then check the Mirth Results resource that you created earlier.

Once you've made all necessary changes, save and redeploy the channel.

Now that all applicable channels are using the new Mirth Results plugin, and libraries (JARs) are handled automatically by the plugin, you should no longer need to include the MR / CDAPI / HL7API libraries in custom-lib. So remove them from the custom-lib folder, then go to the Resources tab, and select the "Default Resource" row. Click the "Reload Resource" task to trigger the default (custom-lib) resource to reload it's libraries from disk. Once done, you should no longer see the libraries you removed in the Loaded Libraries table at the bottom.

You also don't need any deploy (et al.) scripts that manually create the MirthResultsClient object. If you were just using a deploy script to create the client and store it in the global map, that is no longer necessary and should be removed.

If you need a MirthResultsClient object to do things other than posting clinical documents to Mirth Results, then you can still do that in JavaScript. However instead of manually creating the client object, you can use the new MirthResultsUtil utility class to retrieve a client object directly from a resource:

Just supply the resource name you set on the Resources settings view.

Here's a good example of how to use the Mirth Results resource in a JavaScript Writer (with queuing enabled, of course):

try {
    var client = getMirthResultsClient();
    var resultModel = client.createOrUpdateClinicalDocumentFromHL7(connectorMessage.getEncodedData());
    if (!resultModel.isOperationSucceeded()) {
        // Force the message to ERROR if the WS call went through, but the operation failed
        return ResponseFactory.getErrorResponse(resultModel.toString());
    }
    // Store the serialized XML of the actual result as the response, if you want to
    return MirthResultsUtil.cdmToXML('Mirth Results Prod', resultModel.getResult());
} catch (e) {
    // Queue the message if it failed for any reason. The resource will automatically be reloaded if MR was upgraded.
    var cause = e.javaException;
    if (cause) {
        return new Response(QUEUED, '', cause.getMessage(), org.apache.commons.lang3.exception.ExceptionUtils.getStackTrace(cause));
    } else {
        return new Response(QUEUED, '', e.toString(), e.toString());
    }
}

Then your code template would look like this:

function getMirthResultsClient() {
    return MirthResultsUtil.getClient('Mirth Results Prod');
}

Using a common code template is still good, because if you change the name of your resource, then you only have to update your code in one place.

Images on this page point to https://devtools.mirthcorp.com/ . This makes these images broken for users who are not internal Mirth users. Is it possible to fix these images? Posted by jbartels at Sep 06, 2016 14:29

As Jon Bartels said above, images on this page are still not visible to an external Platinum Support customer.  Please fix.  Thank you! Posted by wross at Feb 27, 2017 16:49

The images have been updated so now they should be visible to external users. Posted by kent at Feb 28, 2017 09:51

Document generated by Confluence on Nov 11, 2019 08:40

Atlassian