In the previous post we have an overview of mirthSync and indicated that it can be used for many purposes beyond just simple pulling and pushing of Mirth Connect channels and configuration. In this post we will demonstrate how mirthSync can be integrated with Git and Git's features can be used to track changes to view, review, and if necessary roll back changes to code and configuration.
At Saga-IT utilizing mirthSync is a vital part of our workflow. It enables us to track and visualize changes to our environments over time which gives us extra confidence to make even significant changes and enhancements without risk.
Git
Git is arguably the most widely used software for tracking changes and managing changes in files and directories. Other version control systems exist and can be used with mirthSync in a similar fashion. This post will show how to install Git (if not already present) on Windows and use Git and mirthSync commands to manage changes to a Mirth Connect instance. This can also be done within non-Windows environments by using your system's Git tools available via the Git site or your package management system.
Installation
Downloads for Git can be found at https://git-scm.com/downloads. If you already have Git installed you should skip to the next section.
Download and run the most recent version of Git for
windows
Click "Run" if prompted
Step through all of the default install options and make any changes if desired. I typically stick with the defaults. One setting that you may be interested in changing is the step that involves setting the default editor. Vim is used out of the box but is an editor that is unfamiliar to many people. If you wish - you can change this to various different editors that may be available on your system. Notepad++ is a good choice for Windows.
If you have any questions about the other settings during installation there are more elaborate tutorials that can be found elsewhere but for most purposes the default options should be fine. One option that I would recommend that you don't change unless you know exactly what you're doing is the PATH setting.
Wait for the installation to complete and then close the install dialog.
Your 'Initial Commit'
Navigate using explorer to the directory that you used as the target for your previous mirthSync `pull`. If you don't know what it means to `pull` or don't have a mirthSync install and `pull` directory, please refer to and follow the directions in the previous post.
Right click within the `pull` directory and select 'Git
GUI Here'
Select 'Create New Repository' in the dialog that
appears
Click 'Browse' and select the `pull` directory. In my case it is located at C:\Users\jesse\Downloads\mirthsync-2.0.2-SNAPSHOT\remotepull.
Select 'Create' when prompted
You should
now see something similar to the following image. Your details
may be slightly different depending on your Mirth Connect
channels and configuration.
This is a
view of all of your unstaged files. 'unstaged' is a Git term
for files that Git is either not tracking or files that have
changed and haven't been 'staged' for committing. 'Commit' is
language that is used to refer to a specific set of changes to
files. In our case, the goal currently is to stage and then
commit our initial batch of files. We'll call this our 'Initial
Commit'. Whenever changes are committed to a git repository
there should be language that indicates something about the
changes. In our case it's the first time we're committing our
files so 'Initial Commit' makes sense.
Go ahead and
type 'Initial Commit' in the bottom right pane. Now, click the
"Stage changed" button. Since there are no previous commits
and we have new files git will ask if you would like to stage
the 'untracked' files. Select Yes.
You'll see that your files now are in the 'Staged Changes' area. This means that you're ready to commit the new files to Git's history of the current repository.
Go ahead and click 'Commit'
You may get the following error if you've never used Git
in this environment before
If so, click 'Ok' then click 'Edit' → 'Options' in the
menu. Put your name and email address in the top-right corner
of the the dialog that appears and click 'Save'.
Now go ahead and click the 'Commit' button again.
Done! You've made your initial commit and the repository is clean (meaning it has no changes or new files since the last commit).
Viewing the repository history
At this point, if you're curious you can view the history
of your commits and see what was done. You can do this by
selecting 'Repository' in the menu and clicking 'Visualize all
branch history'. This will open a dialog that allows you to
view details and metadata about your commit. As you add commits
to the repository this can be a handy tool for inspecting the
changes. Go ahead and close this dialog when you're finished
but leave Git GUI running.
Working with changes
Now that we have our initial commit we'll walk through the process of handling changes. To begin with, we'll go ahead and create a new group and new channel. We'll see how the new files are picked up and how to commit the new changes. Then we'll make edits to the new channel code and configuration and see how to manage and view edits.
Go ahead and create a new Group and then add a new Channel to the group. The names and channel type don't matter for our purposes. The goal is to see how it's handled with mirthSync and Git. In my case, I created a new group called 'New Testing Group' and a new javascript writer Channel within that group called 'New Testing Channel'.
Save your channel and group changes. Next, on
your mirthSync machine, navigate to your repository location
using powershell, a command prompt, or the 'git shell'. Next
run the mirthsync.bat command. For me, I was in the target
repository directory already so the target is '.' (the current
directory). A full path could be used. Also, note that I used
the full bath to the mirthsync.bat file. This is necessary if
you're not in the same directory as the mirthsync install or if
mirthsync.bat isn't in your PATH.
The following
command tells mirthSync to `pull` from the Mirth Connect
instance at 192.168.22.58. The -t parameter pulls everything
into the current directory and the -f parameter tells mirthsync
that it's OK to overwrite any existing
files.
`c:\Users\jesse\Downloads\mirthsync-2.0.2-SNAPSHOT\mirthsync.bat
-u admin -p admin -s https://192.168.122.58:8443/api -t . pull -f`
Great! We have the latest code pulled down from our Mirth instance. Let's take a look at Git and refresh its view of our repository.
Within Git GUI which you should have open from our previous steps - Click the 'Rescan' button
After the rescan you should see something
similar to the following
As you can see - the new group and channel are showing up as unstaged. Using the same steps outlined above about staging and committing - go ahead and stage these changes, put a useful comment in the comment pane (I'll use 'Created new group and channel').
Utilizing the branch history feature you can
see the new commit and its details in addition to the previous
commit. Notice that only changes are staged and committed. Git
is efficient about only committing actual changes and doesn't
save or show code that is identical to the previous
commit.
Close this window but leave Git GUI running for our next step
Go ahead and make a minor change to your new channel. It doesn't matter what you change - the config or code, destinations, transformers, etc. I'll change one property and alter my code a bit. Once you've made your changes do another mirthsync `pull`, rescan your repository in Git GUI and view the changes.
In my case you can see that I've
updated the Channel description and have modified the
Javascript reader javascript a little. The red and green
highlighting indicate the changes from the previous version to
the new version.
Go ahead
and stage and commit your changes with an appropriate
comment.
Finished! We've only scratched the surface of the mirthSync and Git combination in this post. Hopefully you can see the potential. We'll be following up with more posts about mirthSync, Mirth Connect, HL7, and Healthcare IT in the future.