Install & Launch Mirth

Rick Wattras -

Welcome to Datica's implementation of the open-source integration engine software Mirthconnect, or Mirth for short! This will be your guide to creating and effectively utilizing your Mirth environment in order to integrate your product with various healthcare systems and technologies. There is a lot of functionality available inside the Mirth application, this guide will attempt to introduce you to the software's most relevant functionality for basic standards-based integration, although we offer several additional interfaces covering more distinct workflows in our supplementary materials here: https://github.com/daticahealth/Mirth-Transforms. For a more in-depth look at the ins and outs of the Mirthconnect application, you can go to the source itself and review the Mirthconnect User Guide here: https://bridge.nextgen.com/media/3244/mirth-data-sheet-mirth-connect-3-5-user-guide.pdf

Add a Mirth OCI to your environment

Mirth OCI is a "One-Click Install" Mirthconnect integration environment for Datica platform customers. If you are a platform customer and want to create an environment that includes Mirth, then simply go to your platform Dashboard, click Datica Account Support → Plans and payment → Create new environment. In the One-click apps section, you'll see a "Mirth+" button which you can click to have the Mirth services added to the environment. Included in your Mirth environment are:

  • 2 Mirth services, a primary and a secondary for HA (for failover, not load balancing)
  • 2 backend Mirth database services, a master and slave for HA
  • 1 monitoring service
  • 1 logging service
  • 1 service proxy for configuring public-facing web services
  • 2 VPN appliances for connecting to your Mirth instance and later for adding customer connections to, a master and slave for HA

Once you've provisioned your new Mirth OCI environment, the service creation process will begin. A Datica employee will contact you when your environment is ready to be used and will include information on how to access Mirth. More on that below.

One note about HA Mirth - as mentioned above, the primary Mirth instance is where you will do all of your build with the secondary Mirth instance acting as a failover should there be an issue on the primary instance. In the case that the primary Mirth instance becomes unavailable, any inbound connections will be routed to the secondary Mirth instance instead.

However while they both share the same backend database and thus have the same channel lists and settings, the secondary Mirth instance does not automatically deploy channels that are deployed on the primary instance. In order to make sure individual channels are truly HA, you will need to access your secondary Mirth instance and deploy your channels (as well as any pending changes) there as well. We'll cover how to access Mirth below, and will guide you on how to access both the primary and secondary instances.

Accessing Mirth

Once Datica has contacted you to say that your environment is ready for use, you'll be provided with information on how to set your VPN connection in order to connect to the system and access Mirth. You'll also be provided with the IP address of your Mirth instance, which you'll need in a moment.

Once your connection is setup and you're successfully on the VPN, browse to the Mirthconnect homepage for your instance by opening a web browser and browsing to http://<IP you were given>:8080. If this is successful, you should see the following on the page:

If you don't see the above, or if the page times out when attempting to load, first check whether you typed in the address correctly and also that you are successfully connected to the VPN. If everything looks ok but you still aren't seeing the above page, please contact Datica support and someone will be happy to help.

By default, the primary Mirth service running in your environment is listening on ports 8080 and 8443. Your secondary Mirth instance is listening on 8081 and 8444, so to access that you would browse to http://<IP you were given>:8081.

If you do get to the above page, simply click the "Launch Mirth Connect Administrator" button and you will download a .jnlp Java Web Start launcher file that you will use to launch the Mirth application itself. This file can be saved and re-used - as well as manually modified - so feel free to store it on your machine in an easily accessible location so that you will only need to use that the next time you want to access Mirth instead of browsing to the homepage each time.

  • NOTE: There's not much else of consequence on this homepage, although you can see a couple other buttons. More info about the cog button here and about the "Access Secure Site" button here.

Now that you've downloaded your Mirth launcher, you're almost there! Before launching Mirth, make sure you have a compatible version of the Java Runtime Environment installed on your machine. Here is the compatibility matrix for all current versions of the Mirth client, so consult that before choosing which version to install. At the time of this writing the default Mirth build you'll receive will be version 3.4.1, so JRE 1.7 and JRE 1.8 are acceptable. When you have successfully installed a compatible JRE, you're ready to go! Simply double-click the .jnlp file and you'll see a series of popups similar to the following:

 

If you get the following prompt, click the "Do not show this again" checkbox and click "Run" to bypass this and not receive in the future:

 

If you don't get to this final prompt, or received errors along the way, check the following:

  • Check the directory you launched the file from for a .log file that may have appeared. If there was an issue with the launch, the Mirth process may have written a log file containing information about the error. If there is a log file, take a look inside and see if that provides more details about the issue. A common one is that not enough memory resources are available to allocate to the Mirth session so you may see something like "There is insufficient memory for the Java Runtime Environment to continue" in the log.
  • If you received Java-related errors, see if the internet provides any insight on the specific error language. Sometimes there are issues with the Java security prompt settings, or with the exception site list. Try relaxing the security settings or adding the Mirth homepage URI address to the exception list and attempt to relaunch. If issues persist, contact Datica support for guidance and help troubleshooting.
  • For any other errors or issues, reach out to Datica and/or try searching the internet - specifically the Mirth support forums.

Logging Into Mirth

When you receive the final Mirth Connect Login popup above, you'll be prompted for a Username and Password. During the provisioning of your Mirth environment, there were credentials generated for you that you should have received when you received the VPN connection and Mirth IP information. Supply those credentials and click "Login". If the credentials don't work or you did not receive them, please reach out to Datica support to receive new credentials via a secure method. PLEASE DO NOT SHARE YOUR CREDENTIALS WITH ANYONE!

After clicking Login, the launcher will start loading - which for first launch can take a minute or two:

If you run into any errors here, or if Mirth doesn't actually end up launching, refer to the troubleshooting steps at the end of the above section.

Once you're past the loading popup, the Mirth application will launch and you'll be presented with a prompt to change your user credentials:

You can just supply the username and a new personal password, but you can also choose whether or not to "Register user with Mirth" which will send your info along to the Mirthconnect folks and will require you to fill out the rest of the fields.

Once that's set, click Finish and you'll get another popup with the latest new and notifications coming out of the Mirthconnect team:

This can be useful for keeping up with the latest Mirth news, but if you don't want it to popup with each login, feel free to uncheck the "Show new notifications on login" box in the bottom left corner before closing that window.

You've now successfully launched and accessed Mirth! Here's what you'll see:

 

First steps

Some good first steps to take once you're in Mirth would be:

  • Set a Server Name for your Mirth instance
    • This is primarily an aesthetic setting as it really only changes the name of the application window from the default URI that you accessed the launcher with. But it's useful if you would ever have multiple Mirth instances open.
    • Go to Settings in the top left → under the General section, simply fill in the "Server name" text box and click Save on the left.
  • Set up any other user necessary accounts
    • If there are only one set of user credentials for your team, you can create temporary accounts for each user that will need access to your Mirth instance
    • Go to Users in the top left → Click "New User" to the left, or right-click on the screen and select New User → Fill out the username and password for each user → Securely provide the credentials to each user
      • The users will be prompted to change their password when they first login
  • Set Mirth to use Group view instead of List view if not already set
    • One of the features introduced in Mirth 3.4 was the ability to "group" channels together into named groups that help to organize your list of interfaces. This can be useful for organizational purposes. On both the Channels and Dashboard screen, there are a couple of buttons in the bottom right corner that allow you to toggle between the Groups and Channels views:
    • We recommend using the Groups view, but feel free to use whichever one you feel most comfortable using!

 

Now you're ready to start exploring the rest of the Mirth application, so continue on in the next guide: Navigating Mirth