Skip to content
Migration guide · facts checked 7 November 2026

Mirth Connect migration and upgrade, tested message by message

How to move Mirth channels off an unpatched release: choosing the target, the breakages each version jump brings, a replay-and-diff test harness built from your own production messages, a parallel run, and a cutover you can roll back.

Server rack with network switches and orange patch cables in an equipment room
At a glance
  • Four target pathsStay, licensed Mirth, Open Integration Engine or new servers
  • Replay and diffYour production samples through old and new engines
  • Rollback rehearsedOld engine kept warm until sign-off
  • Effort in engineer-daysTypical ranges, fixed per phase after review

How a Mirth Connect migration works

A Mirth Connect migration moves channels, code templates, global scripts, alerts, configuration and, if needed, message history from an old Mirth release to a supported target: licensed Mirth 4.7.2 or later from NextGen, the open-source Open Integration Engine (4.7.0, October 2026), or the same engine on new servers. The safe order is inventory, choose the target, rebuild the environment, replay production messages through both engines and compare outputs, run them in parallel, then cut over in waves with a rehearsed rollback.

Mirth Connect migration and upgrade

Most Mirth estates now have to move. The risk is in the details nobody wrote down

Since NextGen made every release after 4.5.2 commercial, a large number of hospitals, labs and health-tech vendors have been running the last free build, or something much older, while they decide. That pause has become harder to defend. A US government advisory in September 2026 listed serious flaws in every Mirth version up to 4.7.1, Java 8 is gone from the newer releases, and the operating systems many engines sit on have reached end of life.

An upgrade sounds like running an installer. In practice the channels are the easy part: they export as XML and import into the new engine. What breaks is everything around them. A code template still calls a library that 4.5.0 removed. An SFTP partner only offers an old key algorithm. A lab system cannot do TLS 1.2. A database poller runs on two engines at once during testing. A certificate lives in a keystore nobody backed up. A good Mirth Connect migration finds these before cutover, using your own production messages as the test.

This page is the plan we follow, with the version-by-version breakages, the test harness and the cutover steps written out so your team can run it, check our work, or hand it to us. It sits alongside our Mirth Connect services, interface engine support and HL7 and X12 EDI integration work. If you are weighing a different engine altogether, start with our Mirth vs Rhapsody vs Iguana comparison instead.

Where Mirth stands in November 2026

Three facts shape every Mirth plan this year.

  • The free line stopped at 4.5.2. NextGen Healthcare announced on 19 March 2025 that Mirth Connect would drop its dual licence: 4.6 and every later release is commercial and closed source, sold in Enterprise, Gold and Platinum tiers. NextGen describes the fee as a flat annual charge per server rather than per interface. Release 4.5.2, published on GitHub on 23 September 2024, is the last open-source build.
  • The open-source code continues in forks. The Open Integration Engine (OIE) shipped a rebranded 4.5.2 in July 2025, 4.6.0 in July 2026 and 4.7.0 on 21 October 2026. It is run by community maintainers and an elected steering committee and, since September 2026, is an incubating Eclipse Foundation project. BridgeLink, maintained by Innovar Healthcare, has moved to year-based version numbers; 26.9.0 came out on 1 October 2026.
  • Old builds are now a security finding. CISA advisory ICSMA-26-253-01 (10 September 2026) describes an authenticated SQL injection and two XML external entity flaws affecting Mirth Connect 4.7.1 and earlier, fixed in NextGen’s 4.7.2. That range includes 4.5.2 and every 3.x release. OIE 4.7.0 contains the corresponding fixes.

Step 1: choose the target before touching a server

The target decides the Java version, the licence, which extensions survive and how much testing you need. Settle it first, in writing, with whoever signs off clinical risk.

TargetSuitsJavaLicenceWatch out for
Stay where you are, hardenedA bridge of a few months while budget or a decision is pendingUnchangedUnchangedNo fix for the 2026 CVEs; rely on isolating the admin port and API, reviewing accounts and tight network rules
Licensed Mirth 4.7.2 or laterTeams that want vendor support and NextGen’s commercial extensionsJava 17 minimum from 4.7.0Annual subscription per serverFewest channel changes; licence key needed in every environment, including test
Open Integration Engine 4.7.0Open source with community support, optionally a paid support vendorJava 17 minimum; installers bundle Temurin 21MPL 2.0, no feeNextGen commercial extensions do not come with you; replace each one
New servers or cloud (with any engine above)OS end of life, data centre exit, consolidationAs the engineAs the engineNew IP addresses mean firewall and VPN changes at every partner

BridgeLink is a fifth option with Innovar’s commercial support behind it; it now requires Java 17 or later, and from 26.9.0 its built-in Derby database needs Java 21. If the licence price is what decides it, our sister site keeps a Mirth Connect licence cost guide.

Step 2: inventory everything the engine knows about

Export first, read second. Take a full server configuration backup from the Administrator (or the command-line client’s exportcfg), and also export each channel, code template library and alert to its own file in a Git repository, so later diffs are readable. Then list:

  • Channels: name, ID, enabled or not, source and destination connector types, data types, message storage mode, pruning settings, and the trading partner on each end. Disabled channels count; someone will ask for one after cutover.
  • Code templates and global scripts: every Java package they call (Packages.org.apache.commons.lang…, java.sql, Xerces), every globalMap or globalChannelMap key, and what the deploy and undeploy scripts do.
  • Alerts: the triggers, which channels they watch (by ID) and where the email goes. Check the SMTP settings still work from the new network.
  • Configuration map and resources: every ${variable} and $cfg value, every library resource and the JAR files in custom-lib.
  • Extensions: the Extensions tab, with version and whether each is NextGen commercial, third-party or home-grown.
  • Server files: mirth.properties, the vmoptions file, appdata/server.id, appdata/keystore.jks and any custom log4j settings.
  • Users and roles: who logs in, how (local, LDAP, MFA) and what each person may do.
  • Endpoints: every listening port, every outbound host and port, file shares and SFTP servers, with the certificates and keys for each.
  • Volume: messages per day per channel, peak hour, largest message, and the size of the message database.

Step 3: check extensions, libraries and Java

This is where most of the surprises are. NextGen moved the FHIR extension into its commercial catalogue back in 4.0, and the 4.6 Enterprise package bundles items such as SSL Manager, Channel History and Message Generator. A channel built on a commercial connector will not deploy on OIE or BridgeLink. For each one decide: drop it, rebuild the logic in JavaScript, use a community plugin (OIE’s listing includes role-based access control, a web administrator, channel history and the Sentinel monitoring plugin), or stay licensed.

If TLS on your MLLP or HTTP listeners came from a commercial extension, plan its replacement before you leave: a TLS-terminating proxy such as stunnel, HAProxy or NGINX in front of the engine is the usual answer. If FHIR output was the reason for the commercial FHIR extension, our HL7 to FHIR conversion guide covers doing the mapping yourself.

Then check Java. Mirth up to 4.5.2 still runs on Java 8 (NextGen’s own 4.x Docker images use Java 17); NextGen’s 4.7.0, OIE 4.6.0 and BridgeLink 26.3.0 all require Java 17. Custom JARs compiled for old Java, reflection tricks in scripts and the Windows default character set (UTF-8 from Java 18 onwards, per JEP 400) all need a test.

Common breakages by version jump

Each row is taken from the vendor’s upgrade notes. A jump from 3.10 to OIE 4.7.0 inherits every row in between.

JumpWhat changedSymptomFix
To 3.8MySQL driver 8.0.16; MySQL 5.6 minimumDatabase connectors to very old MySQL failLoad the old driver as a channel resource
To 3.12DOCTYPE declarations rejected; HAPI 1.x to 2.x; PDF generation moved off iText; Database Reader XML follows the query’s column casingXML with a DOCTYPE errors; HL7 namespace oddities; PDF layout changes; transformers miss columnsStrip DOCTYPEs upstream; untick “Strip Namespaces” if needed; re-test PDFs; alias columns
To 4.0TLS 1.1 and weak cipher suites off by default; FHIR extension becomes commercial; casing change of 3.12 reversedHandshake failures to legacy partners; FHIR channels will not deployPartner upgrades TLS, or a proxy in between; rebuild FHIR logic or license it
To 4.1log4j replaced by log4j2Custom logging settings silently lostRe-apply them in log4j2.properties
To 4.3Resources load classes child-first; default encryption becomes AES/CBC/PKCS5PaddingA bundled driver replaced by the one in your resource folder; changed behaviourTick “Load Parent-First” where needed; leave old encrypted data alone
To 4.4Password hashing moves to PBKDF2 with 600,000 iterationsUsers unable to log in after upgradeSet the digest.fallback.* properties before first start
To 4.5commons-lang 2.6, jdom 1 and digester 2 replaced; Jasypt, SoapUI, XMLBeans and Woodstox removed; new JSch fork turns ssh-rsa offCode templates throw class-not-found; SFTP to old servers fails; SOAP envelope generator output changesPort code to commons-lang3 and jdom2 or add the old JARs as resources; re-enable ssh-rsa per connector only where the partner cannot upgrade
To NextGen 4.6 and 4.7Licence key; MySQL 8.0 minimum; Java 17 minimum from 4.7.0Engine will not start on Java 8; old MySQL rejectedUpgrade Java and database first, in a separate change
To OIE 4.6.0Java 17 minimum; Xerces removed; logins case-insensitive; HTTP parameter order preservedScripts importing org.apache.xerces fail; parameter-order assumptions changeUse javax.xml.parsers; test HTTP listeners
To OIE 4.7.0DOCTYPE rejected in XSLT input, XML batch splitting and strict HL7 XML; SQL Server JDBC 10.2 encrypts by default; no admin/admin on new installs; Temurin 21 bundledEngine on SQL Server stops with “PKIX path building failed”; XSLT channels errorTrust the SQL Server certificate (not trustServerCertificate in production); send XML without DOCTYPE; set the initial admin password
To BridgeLink 26.xJetty 12; refuses to start as root; Java 21 for built-in Derby; jTDS driver removedService fails to start; SQL Server channels fail to deployRun under a service account; rewrite jTDS URLs to the Microsoft driver before upgrading

Step 4: rebuild the environment, not just the install

  • Database. Do not run production on the embedded Derby database; use PostgreSQL, MySQL, SQL Server or Oracle. An upgrade migrates the schema on first start and cannot be undone, so work on a copy and time it: per-channel message tables that have never been pruned can make that first start take hours. Prune, and archive if your retention policy needs it, before the copy. Moving message history between database products is a data project in its own right; often it is simpler to start the new engine with an empty store and keep the old one read-only for look-ups.
  • Server identity and keys. If you carry the database across, carry appdata/server.id too, so queued messages are recovered by the new host. The keystore holds the server certificate and the key that decrypts any encrypted message content; lose it and that content is unreadable.
  • Properties and memory. Port across ports, database settings and keystore passwords from mirth.properties, and heap settings from the vmoptions file. Do not copy blindly; newer releases add properties with safer defaults.
  • Users and roles. Re-check logins after the 4.4 hashing change and OIE’s case-insensitive usernames, and apply a password policy at least as strict as OIE 4.7.0’s new 15-character default.
  • Certificates and TLS endpoints. List each certificate’s expiry date, and test each MLLP-over-TLS, HTTPS and SFTP connection from the new host, not from a laptop.
  • Environment configuration. Move hostnames, ports, paths and credentials out of channels into the configuration map, one per environment, so the same channel export runs in test and production. Windows paths and SMB shares change if the engine moves to Linux.

Step 5: build a regression harness from production messages

A migration is only as good as its test. The most reliable one we know is to replay real messages and compare outputs:

  1. Sample. For each channel, pull recent messages per message type and trigger event, plus the awkward ones: errored messages, Z-segments, repeating fields, non-ASCII names, empty required fields, the largest files and any batch formats. The message store or the engine’s REST API gives you the raw content.
  2. Capture the baseline. Run the samples through the old engine in a test copy, with every destination pointed at a capture sink (a file writer or a mock MLLP listener that returns an ACK) through the configuration map.
  3. Replay. Send the same samples through the new engine with the same sinks.
  4. Diff. Normalise the fields that legitimately change (MSH-7 timestamps, MSH-10 control IDs, generated UUIDs, “now” dates), then compare segment by segment. Compare ACK codes, filtered counts and error counts too.
  5. Classify. Every difference is identical, expected (and written down), or a regression to fix. Re-run until there are no regressions.

Keep production samples inside the client environment, de-identify where you can, and never copy them to personal devices. Keep the harness in Git: the next upgrade then costs a fraction of this one.

Step 6: run old and new side by side

A parallel run feeds the new engine a copy of live traffic while the old engine remains the system of record. Inbound feeds can be copied with a channel writer on the old engine; destinations on the new engine still point at sinks. Compare outputs daily for one to two weeks, long enough to include a month-end, any weekly batch and an upgrade window at a busy partner. One rule matters more than any other: only one engine may poll a production source. A database reader that marks rows as processed, or a file reader that deletes files, will race if two engines run it. Keep pollers disabled on the new engine, or point them at a copy.

Step 7: cut over in waves, with a rollback you have rehearsed

  • Waves. Start with outbound-only and low-risk feeds, then inbound feeds partner by partner. Clinical results and orders go in their own wave with the lab and ward teams told in advance.
  • Partners. New source IPs must be on partners’ allow-lists before the day; some partners need weeks. Senders that hold a TCP connection open must be bounced to reconnect, and DNS records need a short TTL in advance.
  • The switch. Freeze channel changes, stop source connectors on the old engine, let destination queues drain to zero, switch the address or port, start the new engine, and watch the first messages and ACKs end to end.
  • Rollback. Agree the trigger beforehand (for example, ACK failures or an error count above the agreed limit for a set period), keep the old engine installed with channels stopped but not deleted, and rehearse the switch back in test. Messages handled by the new engine during the window need reconciling, so log them.

Step 8: watch the first 30 days

Most post-migration problems are quiet ones: a feed that stops at 2 a.m., a queue that grows slowly, a heap that creeps up. Alert on queue depth, feed silence during expected hours, error rate, JVM heap and disk, and check that the data pruner actually ran. Put certificate expiry dates in a calendar. Review the dashboards with the interface team daily for the first week, then weekly.

Illustrative plan: 40 channels from Mirth 3.10 to OIE 4.7.0

Illustrative, not client work. A regional hospital group runs Mirth 3.10 on Java 8, Windows Server and MySQL 5.7: 40 channels (12 ADT, 10 lab orders and results, 4 scheduling, 3 documents, 3 charge feeds, 2 X12 eligibility, 4 database pollers, 2 file drops), 6 code template libraries and one commercial extension. Target: OIE 4.7.0 on two Linux servers (test and production) with PostgreSQL and a TLS proxy.

PhaseElapsedWorkTypical effort
AssessmentWeek 1Exports into Git, inventory, extension and library scan, target confirmed, partner list for IP changes4–5 engineer-days
BuildWeek 2Servers, Java 21, PostgreSQL, OIE, TLS proxy, configuration maps for test and production4–6 engineer-days
Import and fixWeeks 2–4Import channels; port commons-lang calls; SFTP key algorithms; replace the commercial extension8–12 engineer-days
HarnessWeeks 3–5Samples for all 40 channels, baseline, replay, diff, fixes6–8 engineer-days
Parallel runWeeks 6–7Copied live traffic, daily comparison, partner allow-lists confirmed4–6 engineer-days
CutoverWeek 8Three waves, rollback rehearsed first4–5 engineer-days
HypercareWeeks 9–10Monitoring, tuning, handover notes, old server retired after sign-off3–4 engineer-days

Total: roughly 33–46 engineer-days over ten weeks. The things that stretch it are partners slow to change firewall rules, undocumented channels nobody can explain and commercial extensions with no simple replacement.

Questions to ask before you approve a migration plan

  1. Which target, which Java version and which database, and who signed that off?
  2. Which commercial extensions are in use, and what replaces each one?
  3. How many production samples per channel will be replayed, and what counts as a pass?
  4. Which pollers could run twice during the parallel run, and how is that prevented?
  5. Which partners must change firewall rules, and have they confirmed dates?
  6. What triggers a rollback, and has the rollback been rehearsed?
Packages

Mirth Connect migration packages

Effort is shown in engineer-days for 20 to 40 channels. These are typical ranges; we confirm a fixed price per phase after reviewing your exports.

Migration assessment

The problem

You know the engine has to move but not what is in it, which target fits or how big the job is.

How we do it

We read your configuration exports and server files, scan code templates for removed libraries, list extensions and endpoints, and recommend a target with the reasons and risks written down. Typical effort: 4–8 engineer-days.

What you get

  • Channel and endpoint inventory
  • Extension and library compatibility report
  • Target recommendation with trade-offs
  • Phased plan with effort per phase
How it runs

How a migration runs with us

Typical for 20 to 40 channels. Larger estates add waves, not stages.

Before

Exports and access

You send configuration exports and server files, or give us read-only access; we agree how production samples stay inside your environment.

Week 1

Assessment

Inventory, compatibility report, target decision and a phased plan with a fixed price per phase.

Weeks 2–5

Build, fix and test

Target environment, imported and fixed channels, and harness runs until there are no unexplained differences.

Weeks 6–7

Parallel run

Live traffic copied to the new engine, daily comparisons, partner changes confirmed.

Week 8 on

Cutover and hypercare

Waves with a rehearsed rollback, then monitoring and handover, or ongoing support if you want it.

Senior engineers firstYour first call is with someone who will do the work, not a sales script.
You own everythingCode, configuration, reports and documentation stay in your accounts and are handed over.
We run our own products15 live platforms we build and operate, so we feel production pain too.
Honest about fitIf a cheaper route or another provider suits you better, we will say so.
FAQ

Questions about Mirth Connect migration and upgrades

Not for new releases. NextGen Healthcare ended the dual licence with version 4.6, announced on 19 March 2025, so 4.6 and later are commercial and closed source. Version 4.5.2 remains the last open-source build. The code continues in open-source forks, mainly the Open Integration Engine and BridgeLink.

Usually yes. The server migrates its database schema when it first starts on the new version, so you do not have to install every release in between. But every intermediate version’s upgrade notes still apply to your channels, from the 3.12 XML changes to the 4.5 library removals, so test the whole jump against production samples on a copy first.

Most do with little change, because OIE started from the Mirth 4.5.2 code and imports Mirth channel exports. The exceptions are channels that depend on NextGen commercial extensions, code that uses libraries removed in 4.5 or Xerces removed in OIE 4.6, and anything affected by the Java 17 move. A replay-and-diff test finds these.

Mirth up to 4.5.2 runs on Java 8, and NextGen’s own 4.x Docker images use Java 17. NextGen’s 4.7.0, OIE 4.6.0 and BridgeLink 26.3.0 all require Java 17 or later. OIE 4.7.0 installers bundle Java 21, and BridgeLink needs Java 21 if it uses the built-in Derby database. Upgrade Java as its own change and test custom JAR files on it.

For 20 to 40 channels, a like-for-like upgrade typically takes 6 to 15 engineer-days and a move to the Open Integration Engine 12 to 30, spread over about six to ten weeks once testing, a parallel run and partner firewall changes are included. We confirm a fixed price per phase after reviewing your exports.

Yes, if the new engine uses the same database product: copy the database, keep the server ID and keystore, and let the new version migrate the schema on a test copy first. Moving history between different database products is a separate data project, so many teams start fresh and keep the old engine read-only for look-ups until the retention period ends.

No. Extensions licensed from NextGen are tied to its commercial product. Each one needs a decision: drop it, rebuild the logic in JavaScript, use a community plugin such as OIE’s role-based access control or monitoring plugins, or stay on licensed Mirth. TLS for listeners can also be handled by a proxy in front of the engine.

CISA advisory ICSMA-26-253-01 lists Mirth Connect 4.7.1 and earlier as affected and names 4.7.2 or later as fixed; OIE 4.7.0 carries corresponding fixes. If you cannot upgrade yet, restrict access to the administrator port and API, review user accounts and limit who can reach the engine from the network until you can move.

Last updated