Mirth Connect development environment

So, you came to the point where Mirth no longer cover all your needs, and you are ready to build your own custom connector. I'll show you how you can get a working development environment for Mirth Connect up in a matter of minutes. Note that I will not be using Eclipse for any of my tutorials, but rather I will be using Intellij for the most parts. I believe most professional programmers would too. The only exception is the part where we do Swing forms, where it was easiest to simply download Netbeans to do that work.

Getting an editor to work with, or two

First thing you will need to do, even before you get the source, is to download an IDE to work with. My choice is Intellij from Jetbrains. They provide a free Community Edition that I will use throughout this tutorial in order for occasional Java coders to do their work. I used to be a pro-java-coder earlier, but these days I don't own a license for a Java IDE.

First you need to download the Java SE 6 from Oracle. Install that right after download.

Then go ahead and download Intellij Community Edition from Jetbrains. Install the editor after download. Throughout the text I will refer to Intellij as IDEA. This name is for historical reasons, and also easier to type.

Lastly, you need to also download and install Netbeans Java SE bundle from netbeans.org. You will only use this editor if you want a form editor to work with the Swing interface.

Getting Mirth Connect source code

Intellij ship with built-in subversion support, and we will use that to gain access to the source for Mirth Connect. If you use other software for Subversion (like SmartSVN) you can of course skip this part.

Start Intellij, and from the quick start, choose “Check out from Version Control"

Select subversion as the provider and provide the repository URL (https://svn.mirthcorp.com/connect). This is the official read-only repository for the Mirth source.

Select the tag you want to checkout. At the time of writing, the trunk is early 3.x, and the blog is about 2.x development. Therefore, you should select the latest source tagged with 2.x.x. In my case it is 2.2.1. Select the tag and press Checkout.

You will need to provide a path on the disk where you want to store the source-code. For the rest of the dialogs, just accept the defaults and IDEA will download the source. This will take quite some time, it is a lot of code and libraries.

Setting up a the IDEA project

When the dialog disappears and the source is downloaded, you are ready to create your IDEA project. Select Yes when asked if you want to create a new IDEA project. You will be importing the project from the Eclipse project that the Mirth developers use (poor guys).

Accept the defaults in the next couple of dialogs, and then you will be asked for which project to import. For development of Mirth you should select Client, Command, Manager and Server. The Command module is the command-line interface for Mirth, and if you are not planning on using that, it can be skipped.

After pressing Next you need to select a JDK 1.6. Click Next and Finish. When IDEA ask if you want to add files to Subversion, choose No. You will not have enough access rights to do this, and you will only need these files for your own development. The files that IDEA creates is the project files native to IDEA (*.iml)

Creating a working project in IDEA and setting up the build environment

Now IDEA has created the project for you, and you need to initialize the development environment by running ANT. The easiest way of running the necessary build is to select in in the Ant Build tab of IDEA. The ant build-file to use is named mirth-build.xml.

Choose the default build target (also named build) and let IDEA execute this for you. Running the ant build will take a long time, but is absolutely necessary. Most of the time is actually spent signing JARs, and I will show how to remove this step during development for a much better development experience. This will build and configure the development environment for running and debugging Mirth Connect from within IDEA. 

When IDEA is finally done, the result should look like this…

Anything else is probably incorrect, and you are officially on your own. Please don’t ask.

Before we will be able to compile and start Mirth there are some adjustments to the project configuration we need to do. Open the project configuration in IDEA and change the Command module dependency settings. You will need to add a Module Dependency to the Server module.

You will also need to change the output directory of the Server Module to match that which is used by Ant. You set this to the “build” directory instead of “bin”.

Now we are ready, and you can “Make” the project from the Build|Make Project on the menu. This will compile the whole solution and also copy some vital configuration files into the correct output directories. We are now ready to run!

Running the Mirth server and client inside IDEA

Now that we have the environment initialized, we will make the first attempt to start Mirth. IDEA works with Run/Debug configurations that you will need to configure. We start with the server configuration (you will find these setting in the Run|Edit Configurations)

In the dialog above we add a new configuration, point to the main class of Mirth Connect Server. You also have to make sure that the Working Directory is set to the service module path. Also make sure that the classpath points to the server module.

We repeat the exercise for the Mirth Connect Administrative Client.

Note that besides the main class and working directory, we also provide some Program Arguments. The arguments provided (https://localhost:8443 0.0.0 admin admin) will simplify greatly when you start the Mirth client by logging in automatically (except after each time your run the build with Ant). Again, makes sure that the classpath points to the client module.

We will now use the run-configuration that we added earlier. From the toolbar in IDEA you select the run configuration for the server, and press the debug/run button. This should now start the server. In the output you will see some errors which seem to have no effect on the functionality. Example output below

This output seem to be perfectly normal, so ignore. Now that we have started the server, time to start the client. Select the run configuration for the client and press “Debug/Run” button. This should start the client. The debug output should be clean (not output).

First time you start the Mirth client after a build with and, the database is reverted back to its original state. That means that you need to configure some settings. Set the username, password and uncheck the two boxes at the bottom of the dialog. Press “Finish”.

You should now have a fully functional Mirth Connect server and client running, and you should see the client dashboard without any channels deployed.

Congratulations, you now have a working development environment

Summary and next steps

So, it took a bit longer than a “couple of minutes”, sure. But we now have the foundation for developing Mirth Connect, ultimately creating our very own customizations to make Mirth fit our special needs.

Next step is to build a simple customized connector, a Hello World ala Mirth. Stay tuned.