Migrating from Mirth Connect

This documentation covers moving an existing Mirth Connect server onto OIE, on the same host:

• Install OIE alongside it, without starting it
• Prove OIE starts before it touches anything in the running Mirth engine
• Transplant the relevant configurations
• Stop Mirth and start OIE
• Disable the Mirth installation

Then follow the procedure for your platform: Linux, Windows or macOS.

NextGen premium extensions do not migrate

The paid extensions sold for Mirth Connect do not carry over. Work out what replaces anything you depend on before you start, not after the cutover. See Extension compatibility.

OIE kept Mirth's filenames, so an OIE installation has its own conf/mirth.properties and logs/mirth.log despite what they are called. Most files sit at the same relative path in both installations, so the full path is what tells them apart. Each platform page states the paths it uses.

Scope

• The same host. Mirth and OIE are installed side by side and the cutover happens in one maintenance window.
• Either database. An external PostgreSQL, MySQL, Oracle or SQL Server, or the embedded Derby database. Steps 6 and 8 branch on which one you run.
• The native installer with a bundled JRE. The server runs on the bundled runtime, so the host's Java version does not matter.
• One procedure per platform. The steps are the same everywhere. The service and file commands are not.
• Docker is not covered here. Upgrade Guide has a container path for OIE-to-OIE upgrades.

The procedure has been used to migrate from Mirth Connect 4.5.x. What migrates describes what the server does with an older starting version.

What migrates

The server records a schema version in the database. On startup it migrates from that version up to its own.

From Mirth Connect 4.5.x, OIE 4.6.0 changes nothing: no table, no column, no property. The recorded version is updated and that is all.

From a version below 4.5.2, the schema does change, and your database backup is the only way back.

The version property drives migration

version in mirth.properties tells the server where to migrate from. If you copy that file wholesale from Mirth, you are also setting where migration starts. Merge the properties you need rather than replacing the file.

Extension compatibility

An extension declares a <mirthVersion> in its plugin.xml, source.xml or destination.xml. The server compares that value against its own version as an exact string. There is no version range.

An extension built for Mirth Connect 4.5.2 declares 4.5.2 and will not load on OIE 4.6.0. The server logs an error and lists it as invalid.

The version string decides whether the server loads an extension. Whether it then works is up to the extension's own code. For an extension you build or maintain yourself, the value takes a comma-separated list, so 4.5.2,4.6.0 declares both. For anything you did not build, get a build published for 4.6.0 rather than editing someone else's metadata.

Premium extensions

The paid extensions sold for Mirth Connect do not migrate. Nothing in OIE validates a license: extension metadata carries no license or vendor field, and installing an extension checks your permission and the version string, nothing else. A paid extension can carry its own license check inside its own code, and whether a license issued for Mirth Connect functions from an OIE installation is a question for whoever sold it to you.

Plan replacements before you start. Two capabilities people most often need to replace:

Capability	Community plugin	What to expect
TLS and certificate management	TLS Manager, NovaMap-Health	Channels configured against the premium plugin's TLS need reworking. Channels on non-TLS connectors are unaffected
Channel and code template history	Channel & Code Template History, diridium-com	History starts from the day you install it. Existing history does not come across

Neither plugin is published as a replacement for a paid product. Each covers the capability and brings none of your old configuration, so expect a fresh setup. The plugin directory is the current list.

Mirth Connect and NextGen are trademarks of NextGen Healthcare, which is not affiliated with, does not endorse, and does not sponsor this project.

What the keystore holds

appdata/keystore.jks holds two things under fixed aliases. mirthconnect is the TLS certificate the server presents. encryption is an AES secret key, and what that key covers decides whether the keystore has to come across with the database.

The key is used for:

• Message content, attachments and custom metadata columns written to the database, for channels that enable encryption. It is off by default.
• The database.password and database-readonly.password values in mirth.properties, when encryption.properties is enabled. That defaults to off. An encrypted value is visible in the file by its {enc} prefix.
• Anything a channel script encrypts through the EncryptionUtil API.

If none of those apply, the keystore carries your TLS identity and nothing else. If any of them apply, pointing OIE at Mirth's database without Mirth's keystore leaves that data unreadable.

The keystore and its passwords travel together

keystore.storepass and keystore.keypass must be the values that match the copied keystore.jks. On a mismatch the server logs Could not initialize security settings. and carries on starting. Check logs/mirth.log for that line.

Before you start

Take the backups listed in Upgrade Guide. They apply here unchanged, and the database backup is the rollback.

Two additions specific to this move:

• Record what the Mirth service runs as and what owns its install directory. Step 4 reproduces both.
• List your extensions and their declared versions. Step 6 checks them against 4.6.0.

A server configuration export is not a backup

The export at Settings > Server Tasks > Backup Config, and exportcfg on the CLI, omits user accounts entirely, and the matching restore has no step that would put them back. It also excludes the keystore, mirth.properties and the message database. It will not rebuild a server.

Platforms

The eleven steps are the same on every platform. What differs is how you set the service account, change file ownership, and start, stop and disable a service.

• Linux, complete
• Windows, not written yet
• macOS, not written yet

If you have done this migration on Windows or macOS, those pages would be welcome. The Linux page is the template: the same eleven steps, with the service and file commands replaced. See Contributing.