Get in Touch
Documentation / Mirth Connect Integration
Back to Documentation

Mirth Connect Integration Guide

Learn how to set up and configure Mirth Connect for healthcare data integration. This guide covers HL7 v2 message processing, FHIR resource handling, channel creation, and data transformation.

Introduction to Mirth Connect

Mirth Connect is an open-source healthcare integration engine that enables organizations to send, receive, and transform healthcare data between systems. It acts as a central hub for healthcare data exchange, supporting multiple standards including HL7 v2, HL7 v3, FHIR, X12, NCPDP, DICOM, and custom formats.

What is Mirth Connect?

Mirth Connect (formerly known as Mirth) provides a graphical interface for building integration workflows called "channels." Each channel receives data from a source, transforms it as needed, and sends it to one or more destinations. This makes it ideal for connecting disparate healthcare systems like EHRs, lab systems, billing applications, and clinical databases.

Key Features

  • Multi-Protocol Support: HL7 v2, FHIR, DICOM, X12, databases, files, web services
  • Visual Channel Builder: Drag-and-drop interface for creating integration workflows
  • Data Transformation: JavaScript-based message transformation and mapping
  • Message Filtering: Route messages based on content or metadata
  • Error Handling: Comprehensive error queues and retry mechanisms
  • Monitoring: Real-time dashboard and detailed message tracking
  • Extensible: Custom connectors and plugins

How Mirth Works with Healthcare Standards

HL7 v2 (Legacy Standard)

HL7 v2 is the most widely used healthcare messaging standard globally. Mirth Connect excels at:

  • Receiving HL7 messages via MLLP (Minimal Lower Layer Protocol)
  • Parsing HL7 segments, fields, and components
  • Transforming HL7 messages between different versions (v2.3, v2.4, v2.5, etc.)
  • Routing messages based on message type (ADT, ORU, ORM, etc.)
  • Sending acknowledgments (ACK messages)

FHIR (Modern Standard)

FHIR is the modern healthcare interoperability standard. Mirth Connect supports:

  • RESTful FHIR API endpoints (Patient, Observation, Medication, etc.)
  • Converting HL7 v2 messages to FHIR resources
  • Converting FHIR resources to HL7 v2 messages
  • FHIR resource validation and transformation
  • FHIR Bundle processing

Database Integration

Mirth can directly read from and write to databases:

  • SQL queries for data extraction
  • Insert, update, delete operations
  • Support for MySQL, PostgreSQL, SQL Server, Oracle, and more

Common Use Cases

  • ADT (Admit, Discharge, Transfer) message routing between EHR and ancillary systems
  • Lab result (ORU) distribution to multiple systems
  • Converting legacy HL7 v2 to modern FHIR APIs
  • Patient demographic synchronization across systems
  • Clinical data warehouse integration
  • Insurance eligibility checks and claim submissions
  • Medical device data collection and forwarding

Prerequisites

System Requirements

  • Operating System: Windows, Linux, or macOS
  • Java: JDK 11 or higher (OpenJDK 11+ recommended)
  • Memory: Minimum 2GB RAM (4GB+ recommended for production)
  • Storage: 500MB for application, additional space for message storage
  • Database (optional): PostgreSQL, MySQL, or SQL Server for production deployments

Network Requirements

  • Port 8080: Mirth Administrator web interface
  • Port 8443: Mirth Administrator HTTPS (optional)
  • Ports for channels: Configurable (e.g., 6661 for HL7 MLLP)

Required Knowledge

  • Basic understanding of HL7 v2 or FHIR (helpful but not required)
  • JavaScript basics for data transformation
  • Understanding of healthcare data workflows

Installation

Method 1: Docker Installation (Recommended)

The easiest way to get started with Mirth Connect is using Docker:

Quick Start

# Pull the official Mirth Connect image
docker pull nextgenhealthcare/connect

# Run Mirth Connect
docker run -d \
  --name mirth-connect \
  -p 8080:8080 \
  -p 8443:8443 \
  -v mirth-data:/opt/connect/appdata \
  nextgenhealthcare/connect

Access the Administrator interface at http://localhost:8080

Docker Compose Setup

For a production-ready setup with PostgreSQL, create docker-compose.yml:

version: '3.8'

services:
  postgres:
    image: postgres:15
    restart: unless-stopped
    environment:
      POSTGRES_DB: mirthdb
      POSTGRES_USER: mirth
      POSTGRES_PASSWORD: changeme
    volumes:
      - postgres_data:/var/lib/postgresql/data

  mirth-connect:
    image: nextgenhealthcare/connect
    restart: unless-stopped
    ports:
      - "8080:8080"
      - "8443:8443"
      - "6661:6661"  # HL7 MLLP listener
    environment:
      DATABASE: postgres
      DATABASE_URL: jdbc:postgresql://postgres:5432/mirthdb
      DATABASE_USERNAME: mirth
      DATABASE_PASSWORD: changeme
      DATABASE_MAX_CONNECTIONS: 20
    volumes:
      - mirth_data:/opt/connect/appdata
    depends_on:
      - postgres

volumes:
  postgres_data:
  mirth_data:

Start the services:

docker compose up -d

Note: Default credentials are admin / admin. Change these immediately after first login.

Method 2: Manual Installation

Step 1: Install Java

Verify Java is installed:

java -version

If not installed, download OpenJDK 11+ from Adoptium.

Step 2: Download Mirth Connect

  1. Visit NextGen Mirth Connect Downloads
  2. Download the installer for your operating system
  3. Run the installer and follow the prompts

Step 3: Start Mirth Connect

Linux/macOS:

cd /opt/mirthconnect
sudo ./mcservice start

Windows:

# Start from Windows Services or:
cd "C:\Program Files\Mirth Connect"
mirth-service.bat start

Step 4: Download Mirth Administrator

The Administrator application is a separate download. Get it from the same download page and install it on your workstation.

First Login

  1. Open Mirth Administrator application
  2. Connect to https://localhost:8443
  3. Login with default credentials: admin / admin
  4. Change the password immediately

Creating Your First Channel

Channels are the core building blocks in Mirth Connect. Let's create a simple file-to-database channel.

Example: HL7 File Processor

Step 1: Create New Channel

  1. In Mirth Administrator, click "Channels" in the left panel
  2. Click "New Channel" button
  3. Enter channel name: "HL7 File Processor"

Step 2: Configure Source

  1. In the Source tab, select "File Reader" as connector type
  2. Set directory to monitor: /data/hl7/inbound
  3. Set file pattern: *.hl7
  4. Enable "Process Batch Files": No
  5. Set "After Processing": Move to /data/hl7/processed

Step 3: Add Transformer

  1. Click the "Transformer" tab
  2. Add a JavaScript step
  3. Extract patient information:
// Extract patient demographics from HL7
var patientId = msg['PID']['PID.3']['PID.3.1'].toString();
var lastName = msg['PID']['PID.5']['PID.5.1'].toString();
var firstName = msg['PID']['PID.5']['PID.5.2'].toString();
var dob = msg['PID']['PID.7']['PID.7.1'].toString();

// Store in channel map for use in destination
channelMap.put('patientId', patientId);
channelMap.put('lastName', lastName);
channelMap.put('firstName', firstName);
channelMap.put('dob', dob);

Step 4: Configure Destination

  1. Click "Destinations" tab
  2. Click "Add New Destination"
  3. Select "Database Writer" as connector type
  4. Configure database connection
  5. Add SQL query:
INSERT INTO patients (patient_id, last_name, first_name, date_of_birth)
VALUES (
  '${patientId}',
  '${lastName}',
  '${firstName}',
  '${dob}'
)

Step 5: Deploy and Test

  1. Click "Save" to save the channel
  2. Click "Deploy" to activate the channel
  3. Place an HL7 file in the inbound directory
  4. Check the dashboard for message status

HL7 v2 Message Processing

Understanding HL7 v2 Structure

HL7 v2 messages consist of:

  • Segments: Lines starting with a 3-character code (e.g., MSH, PID, PV1)
  • Fields: Separated by pipes (|)
  • Components: Separated by carets (^)
  • Subcomponents: Separated by ampersands (&)

Example HL7 ADT message:

MSH|^~\&|SENDING_APP|SENDING_FAC|RECEIVING_APP|RECEIVING_FAC|20231115120000||ADT^A01|MSG001|P|2.5
EVN|A01|20231115120000
PID|1||12345^^^MRN||Doe^John^M||19800101|M|||123 Main St^^Springfield^IL^62701
PV1|1|I|ICU^201^A|||1234^Smith^Jane^MD|||||||||ADM|1234

Creating an HL7 MLLP Listener

Source Configuration

  1. Create a new channel
  2. Select "HL7 v2.x" as source connector
  3. Set listener port (e.g., 6661)
  4. Configure HL7 settings:
    • ACK mode: Always
    • Response: Auto-generate (ACK)
    • HL7 version: 2.5 (or your version)

HL7 Message Transformation

Common transformations in JavaScript:

// Access HL7 segments and fields
var messageType = msg['MSH']['MSH.9']['MSH.9.1'].toString();
var patientId = msg['PID']['PID.3']['PID.3.1'].toString();
var patientName = msg['PID']['PID.5']['PID.5.1'].toString() + ', ' + 
                  msg['PID']['PID.5']['PID.5.2'].toString();

// Check if segment exists
if (msg['PV1'] != undefined) {
  var visitNumber = msg['PV1']['PV1.19']['PV1.19.1'].toString();
}

// Create new message
var newMsg = createHL7Message('ADT', 'A08', '2.5');
newMsg['PID']['PID.3']['PID.3.1'] = patientId;
newMsg['PID']['PID.5']['PID.5.1'] = lastName;
newMsg['PID']['PID.5']['PID.5.2'] = firstName;

// Return transformed message
return newMsg;

Testing HL7 Messages

Use the built-in testing tool:

  1. Right-click on channel → Send Message
  2. Paste HL7 message
  3. Click "Send" to test
  4. View transformation results in dashboard

FHIR Integration

Creating a FHIR Listener

Step 1: Configure FHIR Source

  1. Create new channel
  2. Select "HTTP Listener" as source
  3. Set listener port: 8081
  4. Set base path: /fhir
  5. Enable HTTPS (optional, recommended)

Step 2: Parse FHIR Resources

// Parse incoming FHIR JSON
var fhirResource = JSON.parse(message);

// Extract patient data
if (fhirResource.resourceType === 'Patient') {
  var patientId = fhirResource.id;
  var givenName = fhirResource.name[0].given[0];
  var familyName = fhirResource.name[0].family;
  var birthDate = fhirResource.birthDate;
  
  // Store in channel map
  channelMap.put('patientId', patientId);
  channelMap.put('givenName', givenName);
  channelMap.put('familyName', familyName);
  channelMap.put('birthDate', birthDate);
}

Converting HL7 to FHIR

Transform HL7 v2 ADT message to FHIR Patient resource:

// Extract HL7 data
var patientId = msg['PID']['PID.3']['PID.3.1'].toString();
var familyName = msg['PID']['PID.5']['PID.5.1'].toString();
var givenName = msg['PID']['PID.5']['PID.5.2'].toString();
var birthDate = msg['PID']['PID.7']['PID.7.1'].toString();
var gender = msg['PID']['PID.8'].toString().toLowerCase();

// Create FHIR Patient resource
var fhirPatient = {
  "resourceType": "Patient",
  "id": patientId,
  "identifier": [{
    "system": "http://hospital.example.org",
    "value": patientId
  }],
  "name": [{
    "family": familyName,
    "given": [givenName]
  }],
  "gender": gender === 'M' ? 'male' : (gender === 'F' ? 'female' : 'unknown'),
  "birthDate": birthDate.substring(0, 4) + '-' + 
               birthDate.substring(4, 6) + '-' + 
               birthDate.substring(6, 8)
};

// Return as JSON string
return JSON.stringify(fhirPatient, null, 2);

Sending to FHIR Server

Configure HTTP Sender destination:

  1. Add destination → HTTP Sender
  2. URL: http://fhir-server:8080/fhir/Patient
  3. Method: POST
  4. Content-Type: application/fhir+json
  5. Response: Check status code

Data Transformations

JavaScript Transformation

Mirth uses Mozilla Rhino JavaScript engine. Common operations:

String Manipulation

// Trim whitespace
var cleanName = msg['PID']['PID.5']['PID.5.1'].toString().trim();

// Convert to uppercase
var upperName = cleanName.toUpperCase();

// Format date
var rawDate = '20231115';
var formattedDate = rawDate.substring(0, 4) + '-' + 
                    rawDate.substring(4, 6) + '-' + 
                    rawDate.substring(6, 8);

Conditional Logic

// Route based on message type
var messageType = msg['MSH']['MSH.9']['MSH.9.1'].toString();

if (messageType === 'ADT') {
  channelMap.put('destination', 'patient-system');
} else if (messageType === 'ORU') {
  channelMap.put('destination', 'lab-system');
} else {
  channelMap.put('destination', 'archive');
}

Loops and Arrays

// Process multiple patient IDs
var pidSegment = msg['PID'];
var identifiers = pidSegment['PID.3'];

for (var i = 0; i < identifiers.length(); i++) {
  var id = identifiers[i]['PID.3.1'].toString();
  logger.info('Processing ID: ' + id);
}

Using Channel Map

Store and retrieve data across transformers and destinations:

// In Transformer
channelMap.put('processedTime', new Date().toString());
channelMap.put('messageCount', channelMap.get('messageCount') || 0 + 1);

// In Destination
var timestamp = channelMap.get('processedTime');
logger.info('Message processed at: ' + timestamp);

Best Practices

Channel Design

  • Keep channels focused on a single integration task
  • Use descriptive channel names and add descriptions
  • Document transformations with comments
  • Use channel tags for organization
  • Implement proper error handling

Performance

  • Use connection pooling for database destinations
  • Implement message queuing for high-volume channels
  • Limit message retention (configure pruning)
  • Monitor memory usage and tune JVM settings
  • Use batch processing for large datasets

Security

  • Change default admin password immediately
  • Use HTTPS for web interface and APIs
  • Implement authentication for HL7 MLLP connections
  • Encrypt database connections
  • Regularly update Mirth Connect to latest version
  • Follow HIPAA guidelines for healthcare data

Error Handling

  • Configure error destinations for failed messages
  • Set up email alerts for channel failures
  • Use try-catch blocks in JavaScript transformers
  • Implement retry logic with exponential backoff
  • Log errors with sufficient context for debugging

Important: Always test channels in a development environment before deploying to production. Healthcare data is sensitive and errors can have serious consequences.

Monitoring

  • Use the dashboard to monitor channel status
  • Set up alerts for channel errors
  • Regularly review message statistics
  • Monitor system resources (CPU, memory, disk)
  • Enable detailed logging for troubleshooting

Troubleshooting

Channel Won't Deploy

If a channel fails to deploy:

  • Check the event logs for error messages
  • Verify all required fields are filled
  • Test database connections separately
  • Ensure ports aren't already in use
  • Validate JavaScript syntax in transformers

Messages Not Processing

Common issues and solutions:

Source Not Receiving Messages

  • Verify the source is enabled and deployed
  • Check firewall rules for incoming connections
  • Confirm sender is connecting to correct host/port
  • Review source connector logs

Transformation Errors

// Add error handling in JavaScript
try {
  var patientId = msg['PID']['PID.3']['PID.3.1'].toString();
} catch (e) {
  logger.error('Error extracting patient ID: ' + e);
  // Set default or handle gracefully
  var patientId = 'UNKNOWN';
}

Destination Failures

  • Check destination system is reachable
  • Verify credentials for authenticated connections
  • Review destination logs for errors
  • Test connectivity outside of Mirth

Performance Issues

If Mirth is running slowly:

Increase JVM Memory

Edit mirth.properties or startup script:

# Increase heap size
-Xms512m
-Xmx2048m

Configure Message Pruning

  1. Settings → Message Storage
  2. Set retention policy (e.g., 7 days)
  3. Enable automatic pruning

Optimize Database

  • Add indexes to message storage tables
  • Use PostgreSQL or MySQL instead of embedded Derby
  • Configure connection pooling

Getting Help

For additional support: