System Integrations

External system integrations and data exchange in OpenEyes

OpenEyes supports integration with various external healthcare systems through multiple mechanisms including APIs, HL7 messaging, DICOM, and direct database connections.

Integration Overview

PASAPI

Patient Administration System integration for demographic synchronization

HL7/Mirth

Health Level 7 messaging for clinical data exchange

DICOM

Medical imaging integration for biometry and diagnostics

HIE

Health Information Exchange for viewing remote patient records

PASAPI Integration

The PASAPI module (protected/modules/PASAPI/) provides integration with Patient Administration Systems for demographic synchronization.

Configuration

Configure PASAPI via environment variables:

OE_PASAPI_ENABLE=TRUE
OE_PASAPI_URL=http://pas-server:4200

Features

• Patient demographic synchronization
• Real-time updates from PAS
• Bidirectional data exchange
• Automatic patient matching

API Endpoints

The PASAPI V1Controller provides:

// Endpoint structure
/PASAPI/V1/Patient/{action}

Actions include patient create, update, and search operations synchronized with the external PAS.

HL7/Mirth Integration

The Mirth module (protected/modules/Mirth/) enables HL7 messaging for clinical data exchange.

HL7 Message Types Supported

ADT Messages (Administrative)

• ADT^A01 - Patient admit
• ADT^A02 - Patient transfer
• ADT^A03 - Patient discharge
• ADT^A04 - Patient registration
• ADT^A08 - Patient update

ORM Messages (Orders)

• Order placement
• Order status updates
• Result reporting

Configuration

# Mirth Connect Channel Configuration
- Source: OpenEyes Database
- Destination: HL7 Listener
- Message Format: HL7 v2.x

Admin Interface

Access the Mirth admin interface at /Mirth/admin to:

• View message queues
• Monitor integration status
• Configure message mappings
• Troubleshoot failed messages

DICOM Integration

DICOM (Digital Imaging and Communications in Medicine) integration supports medical imaging import and device connectivity.

Biometry DICOM

The biometry module includes DICOM file watching capabilities for automatic import of biometry measurements:

// DICOM file watcher configuration
protected/modules/OphInBiometry/components/DicomFileWatcher.php

Features

• Automatic DICOM file import
• Device integration (IOLMaster, Lenstar, Argos)
• DICOM tag parsing
• Patient matching by identifiers
• Measurement validation

Supported DICOM Tags

(0010,0020) - Patient ID
(0010,0010) - Patient Name
(0010,0030) - Patient Birth Date
(0008,0020) - Study Date
(0008,0090) - Referring Physician
(Custom tags for biometry measurements)

Configuration

Set the DICOM watch directory in system settings:

'biometry_dicom_watch_dir' => '/path/to/dicom/import'

Health Information Exchange (HIE)

HIE integration enables viewing of patient records from external healthcare systems.

Configuration

Configure HIE via environment variables:

OE_PORTAL_ENABLED=TRUE
OE_PORTAL_URI=https://hie.example.com
OE_PORTAL_EXTERNAL_URI=https://hie-external.example.com
OE_PORTAL_USERNAME=openeyes_user
OE_PORTAL_PASSWORD=secure_password
OE_PORTAL_CLIENT_ID=openeyes-client
OE_PORTAL_CLIENT_SECRET=client_secret_value

Features

• Remote record viewing via iframe
• Single sign-on integration
• Patient context passing
• Secure authentication

Implementation

HIE integration in patient summary:

// protected/controllers/PatientController.php
// Displays HIE iframe when configured
if (SettingMetadata::model()->getSetting('hie_enabled')) {
    $hieUrl = Yii::app()->params['hie_portal_url'];
    // Render iframe with patient context
}

Docman Integration

Document management integration for scanning and importing correspondence.

Features

• Document import from scanning systems
• Automatic patient matching
• OCR text extraction
• Document categorization
• Attachment to patient records

Configuration

'docman' => [
    'enabled' => true,
    'import_path' => '/var/docman/import',
    'archive_path' => '/var/docman/archive'
]

Imagenet Integration

Integration with ophthalmology imaging systems.

Controller

protected/controllers/ImagenetController.php handles:

• Image import
• Patient matching
• Image categorization
• Storage management

NOD Export

National Ophthalmic Database export for clinical audit and research.

Features

• Automated data extraction
• Anonymization options
• Scheduled exports
• Compliance reporting

Configuration

Access NOD export at /NodExport/admin:

1. Configure Export Criteria

   Select date ranges and data sets

2. Select Anonymization Level

   Choose patient identifier handling

3. Generate Export

   Create CSV/XML export file

4. Submit to NOD

   Upload to national database portal

CXL Dataset Export

Clinical dataset exports for research and audit.

Controller

protected/controllers/CxlDatasetController.php provides:

• Custom dataset definitions
• Flexible query builder
• Multiple export formats
• Scheduled exports

API Integration

For custom integrations, use the OpenEyes API module. See API Documentation for details.

Key Integration Points

Patient API

Patient search and demographic access

Events API

Clinical event data and attachments

Authentication

API authentication and security

Request Queue

External device data queue

Integration Security

Authentication Methods

API Keys

Basic authentication with username/password for API access

OAuth 2.0

Token-based authentication for OIDC integrations

SAML

Certificate-based authentication for SSO

Mutual TLS

Certificate exchange for high-security integrations

Network Security

• Firewall rules - Restrict integration traffic to specific IP ranges
• VPN tunnels - Secure communication over public networks
• SSL/TLS encryption - All API communication encrypted
• IP whitelisting - Limit API access to known systems

Monitoring Integration Health

Integration Audit Trail

All integration activity is logged:

// Access audit logs
/audit/search?action=integration

Health Check Endpoints

Monitor integration status:

# Check PASAPI connectivity
curl http://localhost/PASAPI/health

# Check API availability
curl http://localhost/api/v1/health

Common Issues

PASAPI connection failures

Symptoms: Patient demographic sync not working

Solutions:

• Verify OE_PASAPI_URL is correct
• Check network connectivity to PAS
• Review PASAPI logs in /protected/runtime/application.log
• Confirm PAS API credentials are valid

DICOM import not processing

Symptoms: DICOM files not appearing in biometry

Solutions:

• Check DICOM watch directory permissions
• Verify DICOM file format compliance
• Review patient ID matching configuration
• Check DICOM file watcher cron job status

HL7 message errors

Symptoms: Messages stuck in Mirth queue

Solutions:

• Review Mirth Connect channel status
• Check HL7 message format compliance
• Verify patient matching rules
• Clear and retry failed messages

HIE iframe not loading

Symptoms: External record viewer shows error

Solutions:

• Verify OE_PORTAL_URI configuration
• Check HIE authentication credentials
• Review browser console for CORS errors
• Confirm patient ID is being passed correctly

Best Practices

Integration Design Principles

• Idempotency - Design integrations to handle duplicate messages safely
• Error handling - Implement robust retry logic with exponential backoff
• Logging - Comprehensive integration activity logging for troubleshooting
• Monitoring - Active health checks and alerting on integration failures
• Security - Principle of least privilege for integration accounts
• Testing - Dedicated test environment for integration development

See Also

• API Documentation
• System Configuration
• System Settings