Plugin Guide

MirthSync Plugin Guide

Complete guide to using the MirthSync Admin Console Plugin. This page covers the interface, all features, common workflows, and best practices.

Looking for Command Details?

This page documents the plugin UI. For detailed command behavior and options, see:

• MirthSync CLI Reference - Complete command documentation
• Git Operations Guide - Git workflow examples

---

Interface Overview

The MirthSync Plugin appears as a panel in the Mirth Connect or OIE Administrator console. The interface uses dropdowns, checkboxes, and text fields to provide complete version control functionality without leaving the Admin Console.

Key Benefits:

• No terminal required - everything is point-and-click
• Presets for one-click execution of common tasks
• Real-time output with detailed feedback
• Choose local or server execution

---

Connection Settings

Configure which Mirth Connect or OIE server to interact with.

Field	Description	Example
Server URL	Mirth Connect/OIE API endpoint	https://localhost:8443
Username	Admin username	admin
Password	Admin password	(stored in session)

These settings tell the plugin which server to pull configurations from or push configurations to.

---

Presets System

Save frequently-used configurations for one-click execution.

What Gets Saved

A preset stores:

• Selected action (Pull, Push, Git command)
• All flag settings
• Git metadata (author, email)
• Execution mode

Controls

Control	Purpose
Save	Store current configuration as a named preset
Load	Select from dropdown to load saved configuration
Delete	Remove preset

Example Presets

• “Dev Pull” - Pull from development with Skip Disabled Channels
• “Prod Deploy” - Push to production with Deploy All + Force Push
• “Daily Commit” - Git commit with standard metadata pre-filled
• “View Changes” - Git diff to review modifications

Save Time with Presets

Create presets for each environment (Dev, Test, Prod) and common operations. This eliminates repetitive configuration and reduces errors.

---

Action Selector

Choose which operation to execute.

MirthSync Operations

Action	Purpose
mirthsync pull	Extract server configurations to files
mirthsync push	Deploy file configurations to server
mirthsync git	Execute Git commands

Git Commands

When you select mirthsync git, choose from these Git operations:

Setup

Command	Purpose
init	Initialize repository
status	Show current state

Track Changes

Command	Purpose
add	Stage files
commit	Save changes
diff	Show differences
log	View history
reset	Undo changes

Branches

Command	Purpose
branch	List/create branches
checkout	Switch to existing branch

Remote

Command	Purpose
remote	List remotes only
push	Upload commits
pull	Download & merge

Git Command Limitations

Some git operations require native git commands:

• Create branches: Use git checkout -b branch-name in your repo directory
• Merge branches: Use git merge branch-name in your repo directory
• Add/modify remotes: Use git remote add/set-url in your repo directory
• Clone/fetch: Use native git commands

Git Command Details

See Git Operations in CLI Reference for complete command documentation.

---

Execution Modes

Choose where commands execute.

Mode	Executes On	Use When
Run Locally	Your workstation	Personal repos, local development
Run on Server	Mirth server	Shared repos, team environments

How to choose:

• Local: You have a Git repository on your workstation and want to work locally
• Server: The repository lives on the server or you want centralized team access
• Mixed: Use Local for development, Server for production deployments

Execution Mode Strategy

Use Server execution for shared team environments. Use Local execution when working with personal repositories on your workstation.

---

Pull Operation

Extract server configurations to files.

Flags

Flag	Effect
Include Configuration Map	Extract server-wide settings
Skip Disabled Channels	Ignore disabled channels
Force Overwrite	Overwrite files without prompt
Deploy After Pull	Deploy immediately (rarely used)

Command Details

See mirthsync pull for command-line options and behavior.

Workflow

1. Select mirthsync pull from Action dropdown
2. Choose execution mode (Local or Server)
3. Check desired flags (e.g., Skip Disabled Channels)
4. Click Execute
5. View output to confirm files were extracted

---

Push Operation

Deploy files to server.

Flags

Flag	Effect
Deploy Channels	Deploy channels after upload
Deploy All	Deploy all configurations
Force Push	Overwrite without confirmation
Auto-Commit Changes	Commit before pushing

Production Deployments

Use Force Push carefully in production. Review changes with mirthsync git diff first.

Command Details

See mirthsync push for command-line options and behavior.

Workflow

1. Select mirthsync push from Action dropdown
2. Choose execution mode
3. Check deployment flags (Deploy Channels, Deploy All)
4. Click Execute
5. Monitor output for deployment status

---

Git Metadata

Required for commit operations.

Field	Example	Used In
Author Name	John Smith	Git commit history
Author Email	john@example.com	Git commit attribution
Commit Message	Update ACK timeout	Commit description

Commit Message Best Practices

Short summary (50 chars max)

Detailed explanation of changes and reasoning.
Reference ticket numbers if applicable.

Good example:

Fix HL7 ACK timeout issue

Increased ACK timeout from 5s to 15s to handle slow
downstream systems. Resolves issue #127.

Workflow: Git Commit

1. Select mirthsync git from Action dropdown
2. Choose commit from Git command list
3. Enter Author Name and Email
4. Write Commit Message describing changes
5. Click Execute
6. Check output for commit confirmation

---

Output Panel

Displays real-time results from command execution.

Displays:

• Command being executed
• Real-time stdout/stderr
• Success/failure status
• Execution time
• Git output (diffs, logs, status)

Actions:

• Scroll to review output
• Copy text
• Open in New Window - Separate output viewer

Output Window for Diffs

When viewing Git diffs or logs, use “Open in New Window” to see full output without cluttering the main panel.

---

Common Workflows

Initialize Repository

Step	Action
1	Git → init
2	mirthsync pull
3	Git → add
4	Git → commit (with message “Initial commit”)

---

Daily Development Work

Step	Action
1	mirthsync pull (get latest from server)
2	(Make changes in Admin Console)
3	mirthsync pull (extract changes to files)
4	Git → diff (review changes)
5	Git → add (stage files)
6	Git → commit (save changes)

---

Deploy to Another Environment

Step	Action
1	Git → push (upload commits to remote)
2	(On target environment) Git → pull (download commits)
3	mirthsync push + Deploy All flag (deploy to server)

---

Work with Branches

Step	Action
1	Git → branch (create feature branch)
2	Git → checkout (switch to branch)
3	(Work on feature, commit changes)
4	Git → checkout main (switch back)
5	Git → merge (combine changes)

---

View Git Diff

1. Select mirthsync git from Action dropdown
2. Choose diff from Git command list
3. Click Execute
4. Review changes in output panel
5. Optionally click Open in New Window for detailed review

---

Common Flag Combinations

Development:

Pull + Skip Disabled Channels

Get configurations but ignore channels you’re not working on.

Production Deploy:

Push + Deploy All (on Server)

Deploy all configurations and ensure they’re activated on the production server.

View Changes:

Git diff (Run Locally)

Review what you’ve modified before committing.

Safe Testing:

Pull (no Deploy After Pull flag)

Extract configurations to files but don’t deploy them automatically.

---

Advanced Topics

Remote Repository Setup

Use Git → remote to configure remote repositories:

# Add remote
remote add origin https://github.com/user/repo.git

# Verify
remote -v

Then use Git → push/pull in the plugin to sync with the remote.

Authentication: SSH vs HTTPS

Type	Setup	Auth
HTTPS	Easier	Username/password or token
SSH	Requires key setup	SSH key

Configure authentication outside the plugin at the system level:

For HTTPS:

• Use personal access token instead of password
• GitHub: Settings → Developer settings → Personal access tokens
• Create token with repo scope

For SSH:

• Generate SSH key: ssh-keygen -t rsa -b 4096
• Add public key to GitHub: Settings → SSH Keys
• Change remote URL using native git: git remote set-url origin git@github.com:user/repo.git

MirthSync Git Remote Limitations

MirthSync’s git remote command only lists remotes. To add, remove, or change remote URLs, use native git commands directly in your repository directory.

Execution Mode Tips

Local Execution:

• Fast for personal work
• Requires local Git repository
• Good for development and testing

Server Execution:

• Best for teams with shared repo on server
• Centralized version control
• Good for production deployments

Mixed Strategy:

• Use Local for development work
• Use Server for production deployments
• Keeps development fast, production controlled

---

Security Best Practices

Never Commit Passwords or Credentials

Mirth Connect security best practice: Never hardcode Mirth Connect database passwords, channel credentials, or API keys in your code. Passwords in JavaScript transformers, connectors, global scripts, or code templates create security vulnerabilities when committed to version control.

1. Use Mirth Connect’s Configuration Map for password management:

Reference the Configuration Map (Settings → Configuration Map) in your channel code instead of hardcoding passwords:

// GOOD - Reference Configuration Map
var dbPassword = configurationMap.get("DB_PASSWORD");
var apiKey = $cfg("API_KEY");

// BAD - Hardcoded password (will be committed to Git!)
var dbPassword = "MySecretPassword123";

Critical: MirthSync excludes the Configuration Map by default (the --include-configuration-map flag defaults to false). Store actual Configuration Map values in AWS KMS, HashiCorp Vault, Azure Key Vault, or another secrets management service.

2. Where hardcoded passwords commonly appear in Mirth Connect code:

• JavaScript transformers
• JavaScript preprocessors and postprocessors
• Source and destination connector scripts
• Global scripts
• Code templates

3. Scan for secrets before committing:

Use a secret scanning tool as a pre-commit hook to detect accidentally hardcoded passwords. Popular open-source options:

Gitleaks (most popular):

# Install Gitleaks
brew install gitleaks  # macOS
# or follow https://github.com/gitleaks/gitleaks

# Scan repository before commit
gitleaks detect --source . --verbose

TruffleHog (alternative):

# Install TruffleHog
brew install trufflehog  # macOS
# or follow https://github.com/trufflesecurity/trufflehog

# Scan repository before commit
trufflehog git file://. --since-commit HEAD --fail

4. Additional protections:

Add to .gitignore as a safeguard:

# Safeguard if --include-configuration-map is accidentally used
ConfigurationMap.xml

For CI/CD deployments, store Configuration Map values in platform secrets (GitHub Actions, GitLab CI, Jenkins) or enterprise secrets management (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault). You can populate the Configuration Map via the Admin Console, local file edits, or programmatically—just ensure ConfigurationMap.xml stays in .gitignore and is never committed.

Always Use HTTPS for Mirth Connect Connections

Mirth Connect security best practice: Always connect to Mirth Connect and OIE servers using HTTPS URLs to encrypt credentials and data in transit. Unencrypted HTTP connections expose admin passwords and channel configurations to network interception.

In the plugin Server URL field, use HTTPS:

GOOD - Encrypted connection
https://mirth.example.com:8443/api

BAD - Unencrypted (credentials exposed!)
http://mirth.example.com:8080/api

---

Tips

Create Environment-Specific Presets

Save separate presets for Dev, Test, and Prod environments to ensure you always use the right settings for each environment.

Commit Often

Make small, focused commits with clear messages. This makes it easier to understand changes and roll back if needed.

Review Before Deploying

Always run mirthsync git diff before committing and pushing to production. This catches unintended changes before they go live.

Use Server Execution for Teams

If multiple people manage the same Mirth instance, use Server execution mode so everyone works with the same central repository.

---

Next Steps

Explore CLI Reference

The plugin executes MirthSync CLI commands behind the scenes. Explore the CLI Reference for:

• Complete command documentation
• Advanced flags and options
• Git commands reference
• Troubleshooting and tips

→ View CLI Reference