This repository contains Saga-IT's MirthSync plugin for Mirth / NextGen Connect.
The plugin embeds the mirthsync CLI so administrators can pull, push, and inspect channel configuration from within the Mirth Administrator UI or directly on the server.
Key capabilities:
- Unified server and client execution: run mirthsync either on the Mirth server or locally inside the Administrator UI.
- Session-aware authentication: automatically reuses the current user's
JSESSIONIDwhen no username/password is provided; tokens/passwords are never persisted. - Opinionated presets for common pull/push and Git actions (both server and client targets) with sane defaults such as
/api/<MIRTH_VERSION>URLs. - Built-in Git helpers (status, log, diff, etc.) that understand Mirth's constraints (e.g., color disabled, helpful error messages when repos are absent).
- Signed jars and packaged dependencies ready for installation (
mirthsync-plugin.zip). - GitHub Actions workflow to build on every push/PR and publish tagged releases automatically.
├── client/ # Swing UI & Administrator integration
├── server/ # Servlet + REST endpoints invoked by Mirth
├── shared/ # Constants, DTOs, and API interfaces shared by client/server
├── libs/ # Runtime/compile-time dependency stubs (populated by build)
├── certificate/keystore.jks # Self-signed cert used for jarsigning
├── build.sh # Orchestrates Maven build, signs jars, assembles plugin zip
└── .github/workflows/build-release.yml # CI/CD workflow
Each Maven module produces one jar (mirthsync-plugin-{server|shared|client}.jar) which is bundled and signed during the build.
External runtime libraries (including mirthsync) are copied to mirthsync-plugin/libs/ and referenced from plugin.xml.
- Java 17 (Temurin/Adoptium recommended)
- Maven 3.9+
- Git
- Access to a Mirth Connect or Open Integration Engine 4.5.2, 4.6.0 or 4.7.0 environment (the exact versions listed in
mirth.plugin.compatible_versionsinpom.xml) - Optional: custom signing certificate/keystore (default self-signed cert lives in
certificate/keystore.jks; password isstorepassand aliasselfsigned)
The plugin depends on com.saga-it:mirthsync, which is published on Clojars and resolved automatically during the Maven build. The embedded CLI version is pinned in server/pom.xml and client/pom.xml (currently 3.9.0); bump both together, and publish that mirthsync release to Clojars first.
git clone https://github.com/SagaHealthcareIT/mirthsync-plugin.git
cd mirthsync-plugin
./build.shWhat the script does:
- Runs
mvn install packageacross the multi-module project. - Copies mirthsync + runtime dependencies into
mirthsync-plugin/libs/. - Signs any unsigned shared libs plus the three module jars using
certificate/keystore.jks. - Generates
plugin.xmlvia themirth-plugin-maven-plugin. - Packages everything into
mirthsync-plugin.zipin the repo root.
Note: the script prints repeated
jansi ... is not executablewarnings on GitHub-hosted runners; these are harmless.
- Stop Mirth Connect.
- Copy
mirthsync-plugin.zipinto<mirth-install>/custom-plugins/. - Start Mirth Connect. The plugin will be extracted and jars validated.
- Launch the Administrator and navigate to Settings → MirthSync to configure.
To upgrade, remove the previous mirthsync-plugin directory under <mirth-install>/custom-plugins/ and drop in the new zip before restarting.
From Settings → MirthSync inside the Administrator UI:
-
Connection
- Server URL automatically appends
/api/<PlatformUI.SERVER_VERSION>(e.g.,https://localhost:8443/api/4.5.2). - Username/password fields are optional; if blank, the servlet injects the current session token.
- Server URL automatically appends
-
Execution Mode
- Run on server: executes mirthsync beans on the Mirth server.
- Run locally: executes mirthsync inside the Administrator JVM (target directories can be browsed via file chooser).
- For Git actions, connection inputs are disabled because they are not required.
-
Presets
- Default presets cover server and client pulls, Git status/log/diff (working tree & staged).
- URLs always include the correct
/api/<version>suffix. - Users can save/delete custom presets; names are shared across all users (via plugin properties).
-
Flags & Toggles
- Includes mirthsync options like
--force,--include-configuration-map,--git-init,--delete-orphaned, etc. - Deploy after push: “Deploy channels after push” (
--deploy), “Deploy all together” (--deploy-all), “Deploy only changed channels” (--deploy-changed, mirthsync 3.7.0+) and, with it, “Also deploy new channels” (--deploy-new). - “Sort unordered collections” (on by default, mirthsync 3.8.0+): on pull, sorts collections Mirth stores in no fixed order (code template context types, library/alert channel IDs, the configuration map, etc.) so pulled XML stays stable and diffs stay clean. Uncheck it to keep the server's order (
--no-sort-unordered). Expect a one-time commit that only reorders elements the first time you pull with “Force overwrite” checked after upgrading; without it, a pull does not overwrite existing files. - “Allow interactive prompts” is currently disabled with a tooltip (“Currently unsupported”).
- Includes mirthsync options like
-
Upgrading to plugin 0.0.7 (mirthsync 3.9.0)
- mirthsync 3.9.0 changes some file and folder names so that a target directory works on Windows.
%," * : < > ? |and control characters are percent encoded (for example:becomes%3A), trailing dots and spaces are encoded, Windows device names such asAUXhave their last character encoded, and names longer than 240 bytes are shortened with a hash. Other names are unchanged. See Upgrading to 3.9.0 in the mirthsync README. - Upgrade everyone who works on the same target directory or Git repository together, including CLI and VS Code extension users.
- In each target directory, push any changes made with the older plugin first. Then run one pull with “Force overwrite” and “Delete orphaned files on pull” both checked, “Restrict to path” empty and “Skip disabled channels” unchecked. Review the result and commit it.
- Without “Delete orphaned files on pull”, the old files stay next to the new ones. Without “Force overwrite”, existing XML is kept, so a renamed channel, group, template, library or alert gets a second XML file and the next push uploads both.
- With a restrict path or with disabled channels skipped, the orphan cleanup still deletes the old files of the items it skipped but does not write their new ones.
- Update “Restrict to path” values (the saved setting and any presets) that name an affected item to the new names. It now takes only the item it names, and mirthsync warns in the output when it matches nothing.
- mirthsync 3.9.0 changes some file and folder names so that a target directory works on Windows.
-
Git Metadata & Commands
- Git author/email pre-filled from the current Mirth user and cannot be toggled read-only (per design).
- Git command field supports arbitrary sub-commands (e.g.,
diff --cached,log -n 5). Color/pager flags are automatically suppressed.
-
Output Panel
- ANSI escape codes and non-XML-safe characters are stripped to keep Mirth’s serializer happy.
- Git-style syntax highlighting is applied (adds/removes/hunks/headers), and you can pop the output into a detached window.
- Session tokens/passwords are redacted everywhere.
.github/workflows/build-release.ymlbuilds on every push and pull request targetingmain.- On tagged pushes matching
v*, the workflow:- Rebuilds the plugin using
build.sh - Uploads
mirthsync-plugin.zipand a SHA-256 checksum - Publishes both assets to the GitHub Release associated with the tag
- Rebuilds the plugin using
To cut a release:
git tag v1.0.0
git push origin v1.0.0The GitHub Action will attach the installable zip to that release automatically.
- Maven property
mirth.plugin.path(defaultmirthsync-plugin) defines the staging folder for assembled artifacts. - The build script signs jars with the self-signed keystore in
certificate/for local development. Official release signing is handled externally after the CI build. - When adding dependencies that must ship with the plugin (e.g., new clojure libs), drop them into
libs/runtime/{client|shared}so the build script can bundle and sign them. - Remember that Mirth’s Jersey stack serializes via XStream/MOXy. Avoid immutable Java collections or custom DTOs unless you register converters; we stick to primitives and
ArrayList/LinkedHashMap.
The MirthSync plugin is built and maintained by Saga IT, LLC. For hands-on help:
- Mirth Connect consulting & development
- Open Integration Engine (OIE) services
- mirthsync CLI and the VS Code extension
Issues and pull requests are welcome!
When submitting changes:
- Run
./build.shand ensuremirthsync-plugin.zipis produced without errors. - Include details on how the change impacts the client/server modules.
- If applicable, update this README, presets, or build/release automation.
For significant features, open an issue first so we can align on expectations.
Thanks for helping improve the MirthSync plugin!