This is Part 1 of a series of posts describing the usage and benefits of utilizing mirthSync with Mirth Connect instances. Future posts will cover more sophisticated usages that allow for you to safely manage environments and view changes being applied.
mirthSync is an open source tool developed by Saga-IT LLC that interacts with the excellent NextGen Connect© (formerly known as Mirth Connect) healthcare IT integration engine to provide many useful benefits to both the open source and closed source versions of Mirth Connect.
Please keep in mind that mirthSync is a free and open source tool that is under active development. Ensure that you have read the License and understand that Saga-IT LLC or any project contributors are not responsible for any issues related to use of the tool. We highly recommend that you utilize the tool only with development or staging environments.
Target Audience
mirthSync should be of interest to anyone that desires more insight into and control over changes being made to their Mirth Connect environments. With mirthSync you will be able to have a fine grained view of changes over time to a single Mirth Connect instance or multiple instances and you will also be able to selectively migrate changes between environments if desired.
Features
- Runs on any system. Windows, Linux, Mac, etc…
- Is able to work with any Mirth Connect instance whether the instance is running remotely or locally
- Reads Mirth Connect channels and configuration on any Mirth instance and writes them to the local filesystem as multiple files within a sensible directory structure
- Allows for fine grained tracking, management, and deployment of changes by integrating with version control systems (Git, Subversion, etc)
- Can take changes pulled from one Mirth Connect instance and then push those changes to another instance
- Selectively roll back and merge changes
- Manage and share code between different environments (prod, staging, dev)
- Run as a service that records changes between different time intervals
- Allows for making changes with a text editor if desired
- Allows for viewing changes over time to whole system or just individual channels, scripts, and configuration
- Code uses a permissive open source license so you can use freely in any environment and even enhance or change the mirthSync code if desired
Prerequisites
You will need a recent mirthSync release downloaded.
You will also need Oracle or OpenJDK JRE/JDK 1.8 or above installed.
Installation
The installation process is very similar on Windows, Linux and Mac. The following steps will illustrate how you can set up mirthSync in a very minimal configuration to allow for pulling code to your local filesystem and then pushing code back again. Future blog posts or documentation will show more sophisticated ways to utilize mirthSync for a variety of purposes.
Note: The following instructions assume that you are in a Microsoft Windows environment. You can, however, run and use mirthSync anywhere that Java runs. In fact, mirthSync is mostly developed and utilized using Linux. Mac environments should be fine too. When in a unix-like environment utilize the equivalent commands and syntax that you see in the following instructions. (bash instead of powershell, forward slashes for paths, use the mirthsync.sh script instead of the .bat script, etc...)
Download and verification
Navigate to the list of MirthSync releases (https://github.com/SagaHealthcareIT/mirthsync/releases)
Click on the zip file for the most recent release (mirthsync-2.0.2-SNAPSHOT.zip as of this writing)
Navigate to the downloaded zip file and extract the contents
Open a command prompt...
mirthSync is currently a command line tool. At this point you
will need to run a command prompt or powershell. For our
purposes, I'll use powershell but the command prompt should
work just fine. 
Navigate to the location of mirthSync's unzipped
files. You should see something like the following...
Ensure that java is on your path by running the following
command
`java -version`
You should see JRE or JDK version information similar to the
following..
If java is not on your path you will see an error message. At this point you will need to download a JRE and ensure the `java` command is on your PATH. There are many tutorials online that can be referenced if needed. For our purposes, we only need a JRE (but a JDK is fine) and it can be either OpenJDK or Oracle's java.
Validate that you are able to run mirthSync and view the
help instructions
`.\mirthsync.bat -h`
Running your first `pull` command
Within your command prompt or powershell, navigate to your mirthsync install directory.
Run a mirthSync `pull` command to fetch everything from a
remote mirth instance to a local directory. This is a
non-destructive operation. In other words - nothing is changed
on the remote mirth instance. The command simply authenticates
to mirth and then downloads to the local filesystem a bunch of
xml files that represent channels, code templates, and more
found within Mirth Connect. Here's an example of a `pull`
command. You will need to substitute -u admin and -p admin
with your appropriate username and password for the
instance.
`.\mirthsync.bat -s 'https://192.168.122.58/api'
-u admin -p admin -t .\remotepull pull`
When you run the preceding command, you're telling mirthSync
to pull everything to a subdirectory called 'remotepull'. The
naming doesn't matter and both full and relative paths are
supported. All that is necessary is that your user account
running the command has permissions to create that directory,
if necessary, and place files within it. If any files already
exist in the target location they will not be overwritten by
default. Here's an example of the output that you'll see when
executing the `pull` command...
If you navigate in explorer to your target pull location
you should now see something similar to the
following...
If you explore this directory structure you will find
that mirthSync has split your Mirth channels, code, and
configuration into a sensible directory hierarchy. Each file
contained within these directories represents a subset of
your Mirth Connect instance. The files contain XML similar to
what you would see if you backed up your Mirth Connect
instance. Here is a tree view example of what you might see
depending on your channels, groups, and libraries...
Now that you've pulled your code down to your local
directory you may wonder what happens if you run the command
again. If you run the same command again against the same
target directory that has already been populated - mirthSync
will refuse to overwrite any existing files. Any new channels
or other Mirth objects will different names will, however,
still be pulled. Here's an example of mirthSync refusing to
overwrite files...
To allow for mirthSync to update existing files within
your target directory you may add the `-f` parameter to
'force' mirthSync to overwrite...
Pushing from your local target pull directory to the same or different Mirth Connect instance
Now that you have a local repository of channels and more within your target directory on your filesystem you may wish to push the changes to a remote Mirth Connect instance. You can use the same instance you pulled everything from, or you can push to a completely different instance.
Warning- the push command will overwrite any matching channels, channel groups, configuration map, global scripts, code templates and libraries within the destination instance! If the destination instance does not contain a matching item - it will be created. Existing channels that don't exist in the local filesystem should be fine.
Note: the following commands assuming the goal is to have the destination server perfectly match the server that was pulled from. In future posts we'll describe how you can manage 'merging' changes between environments that have different configurations
within a command prompt - navigate to your mirthsync installation directory (location of mirthsync.bat, etc)
The following command will take any items that you have
within your previously 'pulled' target directory and update
the remote Mirth Connect instance to contain everything within
your local target directory. The syntax of the command is
identical to the `pull` command except you use the verb
`push`. The `push` command does not warn you if the remote
mirth channels have been updated currently though that may be
a feature added in a future release of mirthSync. Please be
careful and understand the consequences before your run this
command.
`.\mirthsync.bat -s 'https://192.168.122.58/api'
-u admin -p admin -t .\remotepull push`
You should see something similar to the following...
Use Mirth Connect Administrator to verify that the destination instance was successfully updated
Done!
Plans for future posts
Initializing change tracking - use Git to track
changes
Scheduling mirthSync pulls
Creating and switching between branches