HL7 Outbound Overview

Outbound HL7 integrations generate billing, order, patient, specimen, and result messages from LiveHealth/Crelio data. The detailed configuration for each message family now lives in its own page.

Scope

This section documents the legacy outbound HL7 APIs implemented in livehealthapp/labs/views.py. The APIs are used by SFTP/webhook-style integrations where LiveHealth prepares an HL7 message and optionally pushes it to a downstream listener such as Mirth over TCP.

The documentation focuses on two high-use endpoints:

These endpoints are legacy in naming, but still contain the active compatibility behavior for multiple vendor integrations. They combine HL7 generation, vendor-specific mapping, socket delivery, activity logging, and response rendering in one flow.

Mental Model

A request to these APIs is not a raw HL7 payload. It is a JSON request that identifies a report or bill, includes the serialized report/result data, and supplies integrationDetails flags. The API then reloads canonical database records, builds the HL7 segments, normalizes the message, and either returns it or sends it to the configured TCP destination.

Data Sources Used During Generation

The API reloads most business context from the database even when similar values are present in the request. The request is primarily used to choose the flow, supply result arrays/base64 payloads, and override integration behavior.

Runtime Contract

Report-Wise vs Bill-Wise Behavior

Response Shape

Successful generation returns JSON similar to:

{
  "status": 200,
  "message": "MSH|^~\\&|...",
  "file Name": "",
  "sent_to_mirth": true
}

For report-wise generation the response may also include MSH_1 and MSH_2. Bill-wise DFT forwarding returns the generated forwarding payload instead of the final HL7 text:

{
  "status": 200,
  "message": "DFT HL7 sent successfully",
  "sent_to_mirth": false,
  "payload": {
    "Status": "Bill Generation HL7 for SFTP",
    "bill_id": 12345,
    "payloadType": "DFT"
  }
}

Operational Cautions

• The DFT branch in the report-wise SFTP endpoint reads host and port from the root request, while most other branches read them from integrationDetails.
• integration_name is case-normalized in many branches and activates destination-specific behavior. Treat it as a behavior switch, not only a label.
• segments is an allow-list for optional segment groups. Some base segments are always produced even if the list is empty.
• Some branches return status 200 for business skips, for example no insurance in the DFT SFTP branch. Consumers should inspect both HTTP status and response body.
• Because socket delivery happens synchronously in the request, an unreachable host or port can raise an exception and return status 500.

Integration Name Specifications

The outbound generators use integration_name as a compatibility switch for receiver-specific HL7 structure. ORU flows may also derive an integration_identifier from the order number with integration_differentiator; that identifier is mainly used for dynamic port selection and a few receiver-specific ORU layouts.

Configuration Guidance

Message Type Pages

Outbound Routing Flow

Purpose

This document describes the outbound HL7 generation APIs used by the livehealthapp repository for billing, order, patient, specimen, and result transmission.

It covers the following implementation entry points:

Message Types

Request Shape

Most outbound calls expect JSON in the request body. The common structure is:

{
  "payloadType": "ORUR01",
  "labReportId": 123456,
  "labReportDetails": [],
  "reportDetails": [],
  "dictionaryId": 0,
  "integrationDetails": {
    "host": "127.0.0.1",
    "port": 5000,
    "versionId": "2.4"
  }
}

Bill-wise ORU/DFT uses bill_id as the primary identifier:

{
  "payloadType": "ORUR01",
  "bill_id": 12345,
  "billId": 1001,
  "reportDetails": [],
  "integrationDetails": {
    "host": "127.0.0.1",
    "port": 5000
  }
}

Common Runtime Behavior

• If port is configured and non-zero, the generated HL7 is sent over TCP socket to host:port.
• If port is missing or zero, the API can still return the generated HL7 message without sending it to Mirth or another TCP listener.
• update_message_with_ids(jsonData, message, "HL7") is applied before final return/send in the main outbound paths.
• HTML line break tags and some report formatting tokens are normalized before sending.
• integrationDetails is the main configuration object for flags.
• Some functions read host and port from the root payload, while others read them from integrationDetails. See the API-specific notes below.

API-Specific Notes

/integration/sftp/hl7/2_3/send_hl7_data/

Function: sftp_HL7_payload_generation_function

Supported payloadType values:

• DFT
• ORM
• OUL
• ADT
• ORUR01

Identifier rules:

• ORUR01 and OUL read labReportId from the root payload.
• Other payloads read the first labReportId from labReportDetails; if empty, testDetails is used as a fallback.
• If no report id can be resolved, the API returns 400 with labReportId is not valid.

Transport rules:

• ORM, OUL, ADT, and ORUR01 primarily read host and port from integrationDetails.
• The DFT branch in this function reads host and port from the root payload.

/integration/sftp/hl7/2_3/send_billwise_hl7_data/

Function: sftp_billwise_HL7_payload_generation_function

Supported bill-wise behavior:

• ORUR01: Generates one bill-wise ORU message using all synced, non-dismissed reports for the bill.
• DFT: Builds a bill-wise payload and forwards it to a configured URL, defaulting to /integration/hl7/send_dft_hl7_data/.

Identifier rules:

• Requires bill_id.
• If bill_id is missing, the API returns 400 with bill_id is not valid.

DFT forwarding rules:

• Reads host, port, and optional url from integrationDetails.
• Sends a webhook payload containing patient, billing, order, report, and integration details to the configured DFT URL.

/integration/hl7/send_dft_hl7_data/

Function: DFT_HL7_payload_generation_function

Supported payload:

• payloadType: "DFT"

Behavior:

• Generates DFT^P03.
• Uses HL7 version 2.3.1 by default.
• Supports insurance validation, bill-level insurance, timezone conversion, and NextGen-specific segment ordering/formatting.
• Reads host and port from the root payload.

/integration/hl7/2_4/send_dft_hl7_data/

Function: DFT_HL7_2_4_payload_generation_function

Supported payload:

• payloadType: "DFT"

Behavior:

• Generates DFT^P03.
• Supports vendor-specific DFT behavior for integrations such as PGM, ATHENA, CERMAK, and custom dynamic segment sequencing.
• Reads host, port, and dynamic integration-specific port keys from integrationDetails.
• Supports additional DFT options such as outsource mapping, custom segment order, base64 result attachment, profile ICD mapping, and drug-wise FT1 generation.

Configuration Key Naming

Different branches expect different key styles.

If the wrong key style is sent, the code usually falls back to blank/default values.

Common Configuration Keys

Recommended Segment Configuration

Use the smallest segment list required by the receiving system.

Validation and Failure Cases