medOS ultra

HL7v2 Integration

HL7v2 ADT/ORM/ORU parsing for legacy systems: parser, ACK builder, mappers, MLLP listener, frontend service.

1 min read diagramsUpdated 2026-04-15docs-site/docs/integrations/hl7v2.md

HL7v2 message ingress

flowchart LR
  SRC["Lab / ADT feed"] -->|MLLP :2575| LIS["Interoperability service"]
  LIS --> PARSE["hl7v2-parser"]
  PARSE --> MAP["ADT / ORM / ORU mappers"]
  MAP --> M[("MongoDB")]
  LIS -->|ACK / NAK| SRC

medOS supports HL7v2 ADT / ORM / ORU message parsing for legacy system integration: lab instruments, ADT feeds, and pharmacy systems.

Architecture

Lab / ADT Feed ──MLLP(:2575)──▶ Interoperability Service ──▶ Moleculer ──▶ MongoDB
  (external)                     hl7v2-parser → mappers         │
       ▲                              │                    NATS events
       │                         hl7v2-ack.builder              │
       └───── ACK/NAK ◀──────────────┘                  webhookDispatcher

Components

File locations

Component Path
Parser services/interoperability/.../modules/hl7v2/hl7v2-parser.service.ts
ACK builder services/interoperability/.../modules/hl7v2/hl7v2-ack.builder.ts
ADT mapper services/interoperability/.../modules/hl7v2/mappers/adt-to-medos.mapper.ts
ORM mapper services/interoperability/.../modules/hl7v2/mappers/orm-to-medos.mapper.ts
ORU mapper services/interoperability/.../modules/hl7v2/mappers/oru-to-medos.mapper.ts
Controller services/interoperability/.../modules/hl7v2/hl7v2.controller.mixin.ts
MLLP listener services/interoperability/.../modules/hl7v2/mllp.listener.ts
Entity schema packages/platform-api-schema/src/interoperability/hl7Message/
Frontend types web/packages/integration-kit/src/types/hl7.types.ts
Frontend service web/packages/integration-kit/src/services/hl7.service.ts

Feature flags

Flag Default Purpose
HL7V2_MLLP_ENABLED false Enable MLLP TCP listener
HL7V2_MLLP_PORT 2575 TCP port for MLLP connections
HL7V2_MLLP_TIMEOUT 30000 Connection idle timeout (ms)
Ask Anything