Skip to main content

medOS Interoperability

The integration hub for legacy and standards-based healthcare protocols — internal scope.

The Interoperability service is where external clinical and administrative messages enter and leave medOS. It owns HL7v2 parsing and acknowledgement (with a built-in MLLP TCP listener for direct connections from lab instruments, ADT feeds, and pharmacy systems), C-CDA document generation and ingestion, IHE integration profiles, Health Information Network (HIN) querying, EHI bulk export, and X12 EDI claim/eligibility parsing. Each protocol is implemented as a self-contained module with its own mappers that translate the wire format to and from the canonical medOS domain model, and every inbound and outbound message is recorded in an integration audit trail.

8
Modules
2575
Default MLLP port
ADT/ORM/ORU
HL7v2 message types
internal
Scope

Responsibilities​

  • Inbound HL7v2 — accept pipe-delimited messages over MLLP (0x0B … 0x1C 0x0D framing) or REST, auto-detect message type, parse segments (MSH, PID, PV1, ORC, OBR, OBX), map to medOS domain operations, and return a conformant ACK or NAK.
  • Document exchange — generate and ingest C-CDA Continuity of Care Documents via per-section mappers (problems, medications, allergies, results, vitals, immunizations, procedures, encounters, patient).
  • IHE profiles — provide PIX, PDQ, and XDS-style behaviors that define how the underlying standards are used for specific clinical workflows.
  • Network connectors — query patient documents from external Health Information Networks through pluggable adapters.
  • Compliance exports — package a patient's electronic health information (EHI) for portability requests.
  • EDI parsing — read X12 healthcare transactions for claims, remittance, and eligibility.
  • Audit of record — log every integration message with type, direction, and status for traceability.

Major modules​

ModulePurpose
hl7v2HL7v2 parser, ACK/NAK builder, ADT/ORM/ORU mappers, and the MLLP TCP listener
ccdaC-CDA document generation and ingestion with per-section bidirectional mappers
iheIHE integration profiles (PIX, PDQ, XDS, ATNA) for cross-enterprise workflows
hinHealth Information Network connector with pluggable network adapters
ehi-exportPatient EHI bulk export (C-CDA, FHIR Bundle, or NDJSON output)
x12X12 EDI parsing for claims (837P/837I), remittance (835), and eligibility (270/271)
auditIntegration audit log of all inbound and outbound messages
_settingPer-deployment interoperability settings and configuration

HL7v2 message flow​

The HL7v2 module is the primary inbound path. Messages arrive either over the MLLP socket or via REST, are parsed and mapped, and a synchronous acknowledgement is returned to the sender.

  Lab / ADT feed                       Interoperability service
  ───────────────                      ─────────────────────────
        │  MLLP (:2575)                        │
        │  <0x0B> HL7 message <0x1C><0x0D>     │
        ├─────────────────────────────────────▶  mllp.listener
        │                                      │      │ detect type
        │                                      │      ▼
        │                                      │  hl7v2-parser  (MSH/PID/PV1/ORC/OBR/OBX)
        │                                      │      │
        │                                      │      ▼
        │                                      │  ADT / ORM / ORU mapper → medOS ops
        │                                      │      │
        │                                      │      ▼
        │  <0x0B> ACK <0x1C><0x0D>             │  hl7v2-ack.builder + audit record
        ◀─────────────────────────────────────┤

REST callers reach the same pipeline through POST /hl7/raw (auto-detect) or the typed POST /hl7/adt, /hl7/orm, and /hl7/oru endpoints, and can review the recorded messages via GET /hl7/messages.

Config flags​

FlagDefaultPurpose
HL7V2_MLLP_ENABLEDfalseEnable the MLLP TCP listener
HL7V2_MLLP_PORT2575TCP port for MLLP connections
HL7V2_MLLP_TIMEOUT30000Connection idle timeout in milliseconds
HL7V2_MLLP_ALLOWED_IPS(empty)Optional comma-separated source-IP allowlist; empty allows any
Inbound

HL7v2 over MLLP

Lab instruments, ADT feeds, and pharmacy systems connect directly over the framed TCP transport, with an optional source-IP allowlist.

Documents

C-CDA exchange

Section-level mappers convert clinical summaries to and from the canonical medOS model for both generation and ingestion.

Networks

HIN + IHE

Pluggable network adapters and IHE profiles (PIX/PDQ/XDS) cover cross-enterprise patient lookup and document sharing.

Standards coverage​

HL7v2 ADTHL7v2 ORMHL7v2 ORUMLLPC-CDAIHE PIX/PDQ/XDSX12 837/835/270/271EHI Export
  • INT-4 … INT-7 — HL7v2 ADT / ORM / ORU / MLLP
  • INT-8 — C-CDA generation
  • INT-9 — EHI export
  • INT-11 — EDI X12 claims
  • INT-20 — IHE profiles