TCP / MLLP Source

The TCP source opens a socket listener that accepts raw TCP connections or HL7v2 MLLP (Minimal Lower Layer Protocol) framed connections. MLLP is the standard transport for HL7v2 messages in healthcare and is supported by virtually every hospital information system.

MLLP Framing

MLLP wraps each HL7v2 message in a simple byte envelope:

Byte	Hex	Purpose
Start Block	`0x0B`	Signals the beginning of a message.
message	—	The HL7v2 payload.
End Block	`0x1C`	Signals the end of the message body.
Carriage Return	`0x0D`	Terminates the frame.

In raw mode these framing bytes are not expected; the source reads until the connection closes or a timeout is reached.

Configuration

source:
  type: tcp
  port: 2575
  mode: mllp
  max_connections: 50
  timeout_ms: 30000
  tls:
    cert_file: ./certs/server.crt
    key_file: ./certs/server.key
  ack:
    auto: true
    success_code: AA
    error_code: AE
    reject_code: AR

Properties

Property	Type	Required	Default	Description
`port`	`int`	Yes	—	TCP port to listen on. `2575` is the standard MLLP port.
`mode`	`string`	No	`raw`	`raw` for plain TCP, `mllp` for HL7v2 MLLP framing.
`max_connections`	`int`	No	`100`	Maximum concurrent client connections.
`timeout_ms`	`int`	No	`30000`	Idle timeout in milliseconds before a connection is closed.
`tls`	`object`	No	—	TLS certificate and key for encrypted connections.
`ack`	`object`	No	—	Acknowledgment settings (primarily used with MLLP).

ACK Properties

When mode is mllp, acknowledgments are sent back to the sender after each message.

Property	Type	Required	Default	Description
`auto`	`bool`	No	`true` (mllp)	Automatically generate and return an ACK.
`success_code`	`string`	No	`AA`	MSA acknowledgment code for successful processing.
`error_code`	`string`	No	`AE`	MSA code when processing encounters an error.
`reject_code`	`string`	No	`AR`	MSA code when the message is rejected outright.

Complete Example

channel:
  name: adt-mllp-listener
  description: Receive ADT messages from HIS over MLLP

source:
  type: tcp
  port: 2575
  mode: mllp
  max_connections: 50
  timeout_ms: 30000
  ack:
    auto: true
    success_code: AA
    error_code: AE

transformer:
  type: typescript
  file: ./transforms/parse-adt.ts

destination:
  type: kafka
  topic: hospital.adt.events

Transformer Example

Parse the PID segment from an incoming HL7v2 ADT message:

export default function transform(msg: IntuMessage): IntuMessage {
  const segments = msg.payload.split("\r");
  const pid = segments.find((s: string) => s.startsWith("PID"));

  if (!pid) {
    throw new Error("PID segment not found in message");
  }

  const fields = pid.split("|");

  const patient = {
    id: fields[3],
    last_name: fields[5]?.split("^")[0],
    first_name: fields[5]?.split("^")[1],
    dob: fields[7],
    sex: fields[8],
  };

  msg.payload = JSON.stringify(patient);
  return msg;
}