> ## Documentation Index
> Fetch the complete documentation index at: https://hmis-docs.derrickmugabwa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Optional integrations

> Enable OIE, laboratory, Orthanc, and OHIF services without exposing simulators or clinical credentials.

Deploy core HMIS first. Enable integration traffic only after the application, backup, security, and operational checks pass.

<Warning>
  The current production Compose file creates OIE, Orthanc, OHIF, the mock analyzer, and the mock modality by default. This documentation cannot make those services optional at the Compose level. Keep unused services unrouted, stop both mocks after every deployment, and verify firewall state.
</Warning>

## OIE foundation

<Steps>
  <Step title="Protect administration">
    Keep OIE browser administration behind a VPN, IP allow-list, or identity-aware access. Use an SSH tunnel or VPN for the desktop Administrator client on port `8443`.
  </Step>

  <Step title="Create least-privilege HMIS tokens">
    Create separate Sanctum tokens for laboratory results, laboratory worklists, radiology worklists, and study events as required. Grant only the documented abilities and store the raw token once in the target connector's secret configuration.
  </Step>

  <Step title="Import sanitized channels">
    Import the channel exports from `infrastructure/oie/channels`, replace placeholders through the secret process, validate every connector, and export a sanitized post-change copy for backup.
  </Step>

  <Step title="Restrict listeners">
    Bind analyzer, ASTM, MLLP, and DICOM listeners only to approved private interfaces and firewall sources. Never use a public bind merely to reach administration.
  </Step>
</Steps>

## Laboratory integration

Use these guides in order:

1. [Integration context](/laboratory-integration/integration-context)
2. [HMIS configuration](/laboratory-integration/hmis-configuration)
3. [OIE deployment](/laboratory-integration/oie-deployment)
4. [OIE channels](/laboratory-integration/oie-channels)
5. [Testing and validation](/laboratory-integration/testing-and-validation)
6. [Production readiness](/laboratory-integration/production-readiness)

Before enabling a device, approve its test-code mappings, units, flags, specimen identifiers, transport, acknowledgements, duplicate handling, reconciliation process, and downtime workflow.

## Radiology integration

<Steps>
  <Step title="Secure Orthanc">
    The supplied demonstration configuration is not sufficient for production. Apply authentication, network segmentation, access control, retention, audit, and backup requirements before storing real studies.
  </Step>

  <Step title="Configure OHIF">
    Route the protected `{{OHIF_DOMAIN}}` to the `ohif` service and set `PACS_VIEWER_URL_TEMPLATE` to its HTTPS viewer path.
  </Step>

  <Step title="Create the PACS endpoint">
    After setting the viewer URL and PACS code, run the targeted idempotent seeder if the deployment uses the supplied endpoint definition:

    ```bash theme={null}
    php artisan db:seed --class=PacsDemoSeeder --force
    ```

    Review the created endpoint and replace demonstration assumptions before clinical use.
  </Step>

  <Step title="Validate the workflow">
    Complete worklist lookup, modality acquisition, DICOM store, stable-study event, HMIS reconciliation, and viewer launch with synthetic studies.
  </Step>
</Steps>

Use the [Radiology architecture](/radiology-integration/architecture), [Demo PACS and viewer](/radiology-integration/demo-stack), and [End-to-end testing](/radiology-integration/end-to-end-testing) guides for implementation details.

## Simulator policy

| Environment | Mock analyzer                           | Mock modality                           |
| ----------- | --------------------------------------- | --------------------------------------- |
| Local       | Allowed with synthetic data             | Allowed with synthetic DICOM            |
| Staging     | Allowed during controlled acceptance    | Allowed during controlled acceptance    |
| Production  | Stopped, unrouted, and firewall-blocked | Stopped, unrouted, and firewall-blocked |

Record simulator state in every release checklist because a Compose redeployment can start the services again.

## Integration go-live evidence

* Approved network and firewall rules
* Vendor interface and mapping sign-off
* Token owner, abilities, creation date, and rotation record
* Sanitized OIE channel export
* Successful normal, abnormal, duplicate, unknown, and downtime cases
* Backup coverage for OIE, Orthanc metadata, DICOM studies, extensions, and channel exports
* Named reconciliation and incident owners