> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/appertafoundation/openeyes/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CardGroup cols={2}>
  <Card title="PASAPI" icon="hospital">
    Patient Administration System integration for demographic synchronization
  </Card>

  <Card title="HL7/Mirth" icon="message">
    Health Level 7 messaging for clinical data exchange
  </Card>

  <Card title="DICOM" icon="image">
    Medical imaging integration for biometry and diagnostics
  </Card>

  <Card title="HIE" icon="share-nodes">
    Health Information Exchange for viewing remote patient records
  </Card>
</CardGroup>

## PASAPI Integration

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

### Configuration

Configure PASAPI via environment variables:

```bash theme={null}
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:

```php theme={null}
// 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

<Accordion title="ADT Messages (Administrative)">
  * **ADT^A01** - Patient admit
  * **ADT^A02** - Patient transfer
  * **ADT^A03** - Patient discharge
  * **ADT^A04** - Patient registration
  * **ADT^A08** - Patient update
</Accordion>

<Accordion title="ORM Messages (Orders)">
  * Order placement
  * Order status updates
  * Result reporting
</Accordion>

### Configuration

```yaml theme={null}
# 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:

```php theme={null}
// 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:

```php theme={null}
'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:

```bash theme={null}
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:

```php theme={null}
// 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

```php theme={null}
'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`:

<Steps>
  <Step title="Configure Export Criteria">
    Select date ranges and data sets
  </Step>

  <Step title="Select Anonymization Level">
    Choose patient identifier handling
  </Step>

  <Step title="Generate Export">
    Create CSV/XML export file
  </Step>

  <Step title="Submit to NOD">
    Upload to national database portal
  </Step>
</Steps>

## 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](/api/overview) for details.

### Key Integration Points

<CardGroup cols={2}>
  <Card title="Patient API" icon="user" href="/api/patients">
    Patient search and demographic access
  </Card>

  <Card title="Events API" icon="calendar" href="/api/events">
    Clinical event data and attachments
  </Card>

  <Card title="Authentication" icon="key" href="/api/authentication">
    API authentication and security
  </Card>

  <Card title="Request Queue" icon="inbox" href="/api/events">
    External device data queue
  </Card>
</CardGroup>

## Integration Security

### Authentication Methods

<Tabs>
  <Tab title="API Keys">
    Basic authentication with username/password for API access
  </Tab>

  <Tab title="OAuth 2.0">
    Token-based authentication for OIDC integrations
  </Tab>

  <Tab title="SAML">
    Certificate-based authentication for SSO
  </Tab>

  <Tab title="Mutual TLS">
    Certificate exchange for high-security integrations
  </Tab>
</Tabs>

### 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:

```php theme={null}
// Access audit logs
/audit/search?action=integration
```

### Health Check Endpoints

Monitor integration status:

```bash theme={null}
# Check PASAPI connectivity
curl http://localhost/PASAPI/health

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

### Common Issues

<AccordionGroup>
  <Accordion title="PASAPI connection failures" icon="triangle-exclamation">
    **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
  </Accordion>

  <Accordion title="DICOM import not processing" icon="image">
    **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
  </Accordion>

  <Accordion title="HL7 message errors" icon="message">
    **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
  </Accordion>

  <Accordion title="HIE iframe not loading" icon="share-nodes">
    **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
  </Accordion>
</AccordionGroup>

## Best Practices

<Card title="Integration Design Principles" icon="lightbulb">
  * **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
</Card>

## See Also

* [API Documentation](/api/overview)
* [System Configuration](/admin/configuration)
* [System Settings](/admin/system-settings)