Tutorials

Tutorials

This page provides step-by-step tutorials for common workflows using the MirthSync Plugin. Each tutorial includes screenshots and detailed instructions to help you master version control for your Mirth Connect environment.

Tutorial 1: First-Time Setup

Learn how to set up the MirthSync Plugin for the first time and initialize your repository.

Prerequisites

• MirthSync Plugin installed (includes embedded Git - no separate installation needed)
• Administrator access to Mirth Connect or Open Integration Engine

Steps

1. Open the MirthSync Panel

1. Launch Mirth Connect Administrator
2. Log in with your credentials
3. Locate the MirthSync panel in the left sidebar
4. Click to open the panel

2. Configure Git Settings

1. Click the Settings button (gear icon)
2. Enter your Git user information:
   • Name: Your full name
   • Email: Your email address
3. Set the repository path (or accept the default)
4. Click Save

3. Initialize the Repository

1. Click the Initialize Repository button
2. Choose initialization options:
   • Create new repository
   • Connect to existing repository
3. If creating new:
   • Confirm the repository path
   • Set the default branch name (e.g., “main”)
4. Click Initialize

4. Initial Commit

1. The plugin will detect all existing Mirth Connect configuration
2. Review the files to be committed in the File Changes View
3. Enter a commit message: “Initial commit - Mirth Connect configuration”
4. Click Commit

Congratulations! Your repository is now set up and tracking your Mirth Connect configuration.

---

Tutorial 2: Committing Channel Changes

Learn how to commit changes to channels using the MirthSync Plugin.

Scenario

You’ve created a new HL7 receiver channel and want to commit it to version control.

Steps

1. Make Changes in Mirth Connect

1. Create or modify a channel in Mirth Connect
2. Save the channel
3. The MirthSync panel will automatically detect the changes

2. Review Changes

1. Open the MirthSync panel
2. Look at the File Changes View
3. You’ll see the new/modified channel file listed
4. Click on the file to view the diff (what changed)

3. Stage the Changes

1. Check the box next to the changed file(s) to stage them
2. Or click Stage All to stage all changes
3. Staged files are ready to be committed

4. Write a Commit Message

1. In the Commit Message field, write a descriptive message:

   Add HL7 receiver channel for Lab Results
   
   - Configured to receive HL7 v2.5 messages on port 6661
   - Added transformers for lab data normalization
   - Configured destination for database storage

2. Follow commit message best practices:

   • First line: brief summary (50 chars or less)
   • Blank line
   • Additional details explaining what and why

5. Commit the Changes

1. Click the Commit button
2. Wait for confirmation
3. The commit appears in the History Viewer

---

Tutorial 3: Pushing to a Remote Repository

Learn how to push your commits to a remote Git repository (GitHub, GitLab, Bitbucket, etc.).

Prerequisites

• Initialized local repository with commits
• Remote Git repository (GitHub, GitLab, etc.)
• Authentication configured (SSH keys or HTTPS credentials)

Steps

1. Add Remote Repository

1. Open the MirthSync panel
2. Click Settings → Remote Repository
3. Click Add Remote
4. Enter the remote details:
   • Name: origin
   • URL: Your repository URL (SSH or HTTPS)
   • Example SSH: git@github.com:yourorg/mirth-config.git
   • Example HTTPS: https://github.com/yourorg/mirth-config.git
5. Click Save

2. Configure Authentication

For SSH:

1. Ensure your SSH key is added to your Git hosting service
2. Test connection: The plugin will verify SSH access

For HTTPS:

1. You’ll be prompted for username and password when pushing
2. Consider setting up credential caching for convenience

3. Push Commits

1. Click the Push button in the Quick Actions toolbar
2. If this is the first push, you may need to:
   • Set the upstream branch
   • Confirm the push operation
3. Enter credentials if using HTTPS
4. Wait for the push to complete

4. Verify Remote Sync

1. Check the Repository Status section
2. You should see “Up to date with origin/main”
3. Visit your remote repository to verify the files were pushed

---

Tutorial 4: Pulling Changes from Remote

Learn how to pull changes made by other team members.

Scenario

A team member has pushed changes to the remote repository, and you need to pull them into your local Mirth Connect instance.

Steps

1. Check Remote Status

1. Open the MirthSync panel
2. Click the Refresh button
3. The Repository Status shows “Behind origin/main by 3 commits”

2. Review Remote Changes (Optional)

1. Click View Remote Changes
2. See what commits were made remotely
3. Review the changes that will be pulled

3. Pull Changes

1. Click the Pull button
2. The plugin will:
   • Fetch changes from remote
   • Merge them into your local branch
   • Update Mirth Connect configuration
3. Wait for the operation to complete

4. Verify Changes in Mirth Connect

1. Return to the Mirth Connect Administrator
2. Refresh the channel list
3. You should see the updated channels and configuration
4. The MirthSync panel shows “Up to date with origin/main”

---

Tutorial 5: Resolving Merge Conflicts

Learn how to handle conflicts when your changes overlap with remote changes.

Scenario

You and a team member modified the same channel. When you try to pull, a merge conflict occurs.

Steps

1. Encounter Conflict

1. Click Pull to get remote changes
2. A conflict is detected
3. The Repository Status shows “Conflicts: 1 file”

2. Open Conflict Resolution

1. The Conflict Resolution panel opens automatically
2. See the list of conflicted files
3. Click on the conflicted file to view details

3. Review Conflicting Changes

1. The diff view shows:
   • Your changes (local)
   • Their changes (remote)
   • Conflict markers highlighting differences
2. Review both sets of changes to understand the conflict

4. Resolve the Conflict

Option A: Keep Your Version

1. Click Keep Local Version
2. Your changes will be preserved

Option B: Accept Their Version

1. Click Accept Remote Version
2. The remote changes will be used

Option C: Manual Resolution

1. Click Edit Manually
2. The file opens in an editor
3. Combine changes as needed
4. Remove conflict markers
5. Save the file

5. Mark as Resolved

1. After resolving, click Mark as Resolved
2. The file moves from conflicted to staged
3. Repeat for any additional conflicts

6. Complete the Merge

1. All conflicts are now resolved
2. Enter a merge commit message
3. Click Commit to complete the merge
4. The merge is complete, and your repository is up to date

---

Tutorial 6: Working with Branches

Learn how to create and manage branches for feature development.

Scenario

You want to develop a new feature without affecting the main branch.

Steps

1. Create a New Branch

1. Open the MirthSync panel
2. Click Branches → Create New Branch
3. Enter branch details:
   • Name: feature/enhanced-logging
   • Base: main
4. Click Create and Switch

2. Make Changes on the Branch

1. Develop your feature in Mirth Connect
2. Commit changes to the feature branch
3. The Repository Status shows “On branch feature/enhanced-logging”

3. Push the Feature Branch

1. Click Push
2. Set upstream for the new branch if prompted
3. Your feature branch is now on the remote repository

4. Merge Feature into Main

When feature is complete:

1. Switch back to the main branch:
   • Click Branches → Switch
   • Select “main”
2. Click Merge → Select Branch
3. Choose feature/enhanced-logging
4. Click Merge
5. Resolve any conflicts if necessary
6. Push the updated main branch

5. Delete the Feature Branch (Optional)

1. After merging, you can delete the feature branch
2. Click Branches → Delete
3. Select feature/enhanced-logging
4. Confirm deletion

---

Tutorial 7: Rolling Back Changes

Learn how to revert to a previous version of your configuration.

Scenario

You need to undo recent changes and return to a previous stable state.

Steps

1. Open Commit History

1. Open the MirthSync panel
2. Click History to view all commits
3. Find the commit you want to revert to

2. View Commit Details

1. Click on the desired commit
2. Review what changes were made
3. Confirm this is the version you want

3. Revert to Previous Commit

Option A: Revert Specific Commit

1. Right-click on the commit
2. Select Revert This Commit
3. A new commit is created that undoes the changes
4. Your history is preserved

Option B: Reset to Commit

1. Right-click on the commit
2. Select Reset to This Commit
3. Choose reset type:
   • Soft: Keep changes in working directory
   • Hard: Discard all changes (caution!)
4. Confirm the reset

4. Update Mirth Connect

1. The plugin updates the Mirth Connect configuration
2. Restart channels if necessary
3. Verify the configuration is as expected

5. Push Changes (if needed)

1. If you’re working with a remote repository
2. You may need to force push (use with caution!)
3. Better practice: Use revert instead of reset for shared branches

---