HL7 Message Generator

The Shape of a Real HL7 v2.x Message

An HL7 v2.x message is a plain-text, pipe-delimited document split into segments separated by carriage returns. The MSH header sets the encoding characters and identifies sending and receiving systems. Following segments (PID, PV1, OBR, OBX, ORC, EVN, SCH, RXA, TXA, FT1, and others) carry the clinical and administrative payload. Each segment has a rigid field order, each field a specific data type, and each trigger event (like ADT^A01) a defined set of required segments.

Why Test Data Is Hard to Source

Real HL7 messages contain Protected Health Information (PHI) — patient names, medical record numbers, birthdates — and cannot be shared outside the HIPAA-covered environment they originated in. Integration engineers routinely hand-craft messages when building or debugging interfaces, which is error-prone: one miscounted pipe, a missing required field, an invalid MSH-9 format, and the receiving system rejects the entire message.

How a Generator Fits the Workflow

A good generator gives you a well-formed scaffold with every required segment and field populated by valid sample data. From there you override only what your test case needs — a specific patient ID pattern, an abnormal lab result flag, an unusual bed location. The generator's output is guaranteed to parse, so any failure the downstream system reports is about your test case, not your typing.

ADT (Admit, Discharge, Transfer) Messages

The ADT family is the most common reason an interface exists. ADT^A01 announces a new inpatient admission; ADT^A03 signals discharge; ADT^A04 registers an outpatient. ADT^A08 updates demographic or visit data — it is the workhorse event that hospitals use when a name is corrected, a guarantor changes, or an insurance update lands. Downstream systems, from lab to billing to radiology, subscribe to ADT feeds to keep their own patient rosters in sync.

Orders and Results (ORM, ORU)

ORM^O01 carries a new order — a lab test, an imaging study, a medication — from the ordering system to the performing system. ORU^R01 carries the observation result back, typically with one OBX segment per individual measurement (one for white blood cell count, another for hemoglobin, and so on). The pairing is the backbone of clinical messaging.

Scheduling, Documents, and Finance

SIU^S12 announces a new appointment; MDM^T02 transmits a clinical document (discharge summary, radiology report) with or without attached content; BAR^P01 creates a patient financial account; DFT^P03 posts a charge or adjustment. VXU^V04 carries immunization records — critical for population-health and public-reporting interfaces. Each of these has distinct required segments that the generator enforces.

Using Generated Messages Responsibly

Generated messages should be clearly marked as test data. Most HL7 engines let you set MSH-11 (Processing ID) to "T" for training or "D" for debug, which downstream systems use to route test data away from production workflows. This generator defaults to "P" (production) because the generated message is meant to be a structural scaffold; consider flipping it to "T" before piping into a real integration engine connected to downstream systems.

Cross-Tool Verification

Once you generate a message, open it in the HL7 Viewer to inspect segments with color-highlighting and field decoding, or send it through the ACK Generator to simulate a receiving system's response. The combined workflow — generate, view, acknowledge — lets you exercise both sides of an interface before a single real message flows.

HL7 v2.x vs FHIR: When to Use This Generator

FHIR (Fast Healthcare Interoperability Resources) has captured most of the new greenfield healthcare integration work in the last five years, but HL7 v2.x remains dominant for existing hospital interfaces. A typical US health system today runs hundreds of HL7 v2.x feeds between EHR, lab, radiology, pharmacy, billing, and ancillary systems — and will continue to do so for years. This generator is the right tool when you are building or debugging against that v2.x backbone. For greenfield projects, mobile apps, population-health analytics, or external partner APIs, FHIR is typically a better target and this generator will not help you there — use a FHIR resource builder instead. The practical test: if the receiving system expects a pipe-delimited message starting with MSH|^~\\&|, you need v2.x; if it expects JSON or XML resources with OAuth 2.0 auth, you need FHIR.

Segment Order and Conditional Segments

A message's segment order matters. The HL7 specification defines strict segment sequences per trigger event: ADT^A01 is MSH → EVN → PID → PV1 (with optional segments like AL1, DG1 inserted in specific positions); ORU^R01 is MSH → PID → OBR → OBX (with OBX potentially repeating for multi-result panels). Receivers enforce this ordering — an out-of-place segment breaks parsing even when all required fields are present. Our generator emits segments in the canonical order defined by the spec, so the output works against strict parsers. When you hand-modify a message, preserve the original sequence; do not rearrange segments to "look cleaner."

Conditional and Repeating Segments

Some segments are conditional: PV2 appears only when extended visit information is relevant; DG1 repeats once per diagnosis; IN1 repeats per insurance plan; AL1 repeats per allergy. Trigger events define both required and optional segments, and the order in which repeats appear. This generator currently emits the required segments for each trigger event with sample data; conditional extensions like multiple AL1 allergies or a sequence of DG1 diagnoses can be added by editing the generated message before copying. If your test case depends on conditional repeats, add them manually after generation and run the result through the HL7 Viewer to verify the receiver can still parse it.

Encoding and Character Set Considerations

HL7 v2.x defaults to ASCII, which is fine for English-language systems but breaks for European language text containing accented characters, or any Asian language content. To emit a message with non-ASCII text, set MSH-18 to UTF-8 explicitly and ensure every downstream system supports UTF-8 on the interface. In practice many older systems do not — a patient name with a tilde silently arrives as "garbage bytes" on the receiving end. If you are adding international characters to a generated message, test the full round trip with the target system before committing to UTF-8 over an older v2.3 interface. Our generator emits ASCII-safe sample data by default so this problem doesn't surface in test scaffolding.

Typical Integration Engine Workflows Where This Fits

Interface engines — Mirth Connect, Rhapsody, Ensemble, Infor Cloverleaf, Corepoint — consume HL7 v2.x messages, transform them with channels (scripted routing rules), and forward them to downstream systems. Test messages are the raw material of every engine's QA cycle. Generate a message here, paste it into Mirth's "Send Message" dialog against a test channel, and inspect the transformed output. For ADT → HL7-to-FHIR conversion channels (a common modernization pattern), generate the v2.x source with this tool and verify the resulting FHIR bundle against the expected resource shape. For channels that enrich messages by looking up external master data (patient indexes, code tables), generate a message with a patient ID that intentionally doesn't match any record to verify the engine handles the miss gracefully — a common source of production incidents when MDM systems are updated.