odoodo / mirth-migrator

A tool for migrating Mirth Enterprise Service Bus channels and code templates from one instance to another

Mirth Migrator automates the transfer of Mirth Enterprise Service Bus channels and code templates from one instance to another.

Features

• Code Templates and Channel Migration
  Code templates, channels, and even entire Channel Groups or Code Template Libraries can be migrated between Mirth instances with a single click. Code templates of directly or indirectly referenced functions can be automatically migrated with the channels.
  
  If a component already exists at the destination instance, conflict handling will be activated. The component to be migrated will be compared with the corresponding component of the target system, and the user can choose to skip its migration or overwrite the one on the target side.
• Meta Data and Source Code Viewing
  When a component is selected, important metadata and the source code are displayed.
• Documentation
  Upon clicking on a component, the relevant documentation is displayed. In the case of functions, this may include their descriptions, parameter definitions, and expected return values. In the case of channels, this may include a description and a change history. Multiple functions in one code template will be displayed as separate items.
• Compare
  If a component selected at one instance already exists at the other instance, it will be highlighted, and a compare button will appear. The source code and metadata for components can be compared in two ways: side-by-side or inline.
• Function Dependency Checking
  For each function, it is indicated which other functions it uses, as well as the channels and/or functions through which it is used.
• Channel Dependency Checking
  For each channel, either directly or indirectly referenced functions are shown. It is further indicated which code template libraries it references and if these references are correct. Non-needed as well as missing library references are highlighted
• Web-Based Application
  Mirth Migrator is a fully web-based application provided via a Mirth channel. There is no need for a separate user management system as it utilises the user pool of the Mirth installation, which runs the channel.

Screenshots



Installation

For Mirth experts:


1.	Place the "web" folder in your "Mirth Connect" folder
2.	Reference MirthMigrator.jar that you find at ./web/MirthMigrator/jar/ as custom resource
3.	Import the MIRTH_MIGRATOR channel and reference the custom resource
4.	Configure Mirth Migrator (see configuration section for details)


Detailed step by step instruction:
Behind each step you can find a screenshot indicating what/where to click and in which order.


1.	Copy the folder "web" to your Mirth installation (to "<Your Install Path>\Mirth Connect")
2.	In Mirth Administrator open the menu item "Settings", there the tab "Resources" and press "Add Resources"
3.	In the field Directory enter "./web/MirthMigrator/jar" and name the new Resource "MirthMigrator"
4.	Save the change and press "Reload Resource". Depending on your Mirth version it should now show something like "<Your Installation Path>/Mirth%20Connect/web/MirthMigrator/jar/MirthMigrator.jar" or just "MirthMigrator.jar" under "Loaded Libraries"
5.	Now go to menu item "Channels" and press "Import Channel"
6.	Import MIRTH_MIGRATOR.xml
7.	Within the MIRTH_MIGRATOR-channel click on tab "Summary" (1st tab) and press "Set Dependencies"
8.	Choose the tab "Library Resources" (2nd tab) in the up-popping dialog, activate the checkbox for "Mirth Migrator" and press OK
9.	Save the channel changes and deploy the channel
10.	Mirth Migrator should now be available under http://<YOUR MIRTH SERVER>:1339/MirthMigrator $${\color{red}Please \space be \space aware \space that \space the \space Mirth \space Migrator \space needs \space to \space be \space configured \space before \space you \space can \space use \space it.}$$ $${\color{red}Check \space the \space configuration \space section \space below \space for \space details}$$

Configuration

Mirth Migrator does not (yet) feature a graphical configuration frontend. Thus, the configuration has to be changed in the configuration file directly.

This configuration file can be found at: "<Your Installation Path>/Mirth Connect/web/MirthMigrator/config/MirthMigrator.conf"

The configuration consists of 4 sections:

sessionLifeSpanInMinutes		Allows to determine the maximum inactivity period for a user session in minutes. If the value is 0, the user session will not expire
environment	id	A unique identifier of the environment 1, 2, 3, etc.)
	position	The order position of the environment 1 will be displayed on top of the list, 2 will be displayed as second, etc.
	name	The name of the environment e.g. Production, Test, Development, Fallback
	color	The color in which servers of this environment will be shown use html colors
system	name	The name of the Mirth system Any name can be used, e.g. Production Server 1, My Test System
	server	The name or ip of the Mirth server that should be accessed
	port	The port at which the Mirth server exposes it's API By default, this port is 8443
	environment	The ID of the environment to which this Mirth server should be assigned This ID must correspond to an id attribute of the environment section
	description	An optional text that describes your Mirth environment e.g. "Hosts all medical channels" or "Server for administrative channels"
	user	The Mirth user that Mirth Migrator should use to access this Mirth instance It makes sense to create a "system"-user on every Mirth instance that should be accessed by Mirth administrator. This might be a user like "system", or "maintanance", or "migration"
	password	The password of the Mirth user that Mirth Migrator should use to access this Mirth instance
excludeFromFunctionDetection		Mirth Migrator has a parser that detects function references for detecting user defined functions. However there might be false positives like function calls in SQL statements or calls to Mirth maps. Those functions would be displayed as functions for which the source could not be identified. For avoiding false positives, the function names can be added to this filter list.

Any changes of the configuration are applied on the fly. There is no need to restart the MIRTH_Migrator channel.

When you access Mirth Migrator, it asks you to log in. Simply use your Mirth account of the Mirth instance at which the MIRTH_MIGRATOR channel is running.

Kudos

Mirth Migrator makes use of a number of other open source projects:
• JSON in Java (A JSON implementation for Java)
• Difflib.js (for providing diffs)
• highlight.js (for code highlighting)

Please let me know if I forgot to mention your project.