Skip to main content

HL7 Parse

Category: Healthcare Standards
Node id: hl7-parse

Standards: HIPAA, GDPR, SOC2

Parses HL7v2 messages into structured segments and fields, with optional field extraction and validation

What it does​

  • Parses HL7v2 messages into structured segments and fields
  • Extracts common clinical fields: patient (PID), visit (PV1), orders (OBR), observations (OBX)
  • Message type detection from MSH segment
  • Optional structural validation before parsing
  • Version detection from MSH-12

Use cases​

  • Parse ADT messages from hospital interfaces for patient tracking
  • Extract lab results from ORU messages for clinical dashboards
  • Feed parsed HL7 data into HL7-to-FHIR transformation pipelines

Runtime​

  • Performance tier: fast

Input ports​

NameTypeRequiredDescription
messagetextYesRaw HL7v2 message string (an array is parsed as a batch, like messages)
messagesjsonNoBatch of HL7v2 messages: strings, or objects with content (or hl7_message) and path — e.g. file read_all content

Output ports​

NameTypeRequiredDescription
resultjsonNoParse result (raw, segment_count, segments, extracted, message_type)
successbooleanNoWhether the parse succeeded; for a batch, whether every message parsed
resultsjsonNoBatch only: one entry per message, in input order: {index, path?, success, result | error}
errorsjsonNoBatch only: the messages that failed: {index, path?, error}

Settings​

Basic​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Extract Fieldsextract_fieldsbooleanNofalseExtract common HL7 fields (patient, visit, order, observations)
Validate MessagevalidatebooleanNotrueValidate the HL7 message structure before parsing

Advanced​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Max Messagesmax_messagesnumberNo10000Batch only: a larger batch is refused

Errors​

CodeDescription
MESSAGE_REQUIREDHL7 message input is missing
PARSE_FAILEDHL7 message could not be parsed
MISSING_MSHMessage is missing the required MSH segment
INSUFFICIENT_MSH_FIELDSMSH segment has fewer than 9 fields

Runtime notes​

  • result.segments is always present — it is an array of {id, fields} objects. result.extracted only appears when extract_fields=true in config.
  • Extracted patient data uses HL7 field positions: PID-3 (id), PID-5 (name), PID-7 (dob), PID-8 (sex). Names are in HL7 format (Last^First).
  • result.message_type is extracted from MSH-9 and MSH-12; use it to route different message types (ADT, ORU, ORM) in condition nodes.
  • Multiple OBX segments are collected into result.extracted.observations as an array — one entry per OBX segment.
  • Batch: an array on messages (or message) — strings, or objects with content/hl7_message and path such as file read_all output — is parsed message by message; results holds one entry per message, a failed message carries its error and path without stopping the others, result is {count, parsed, failed, messages} and success is false if any message failed.

See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.

Something unclear? Send documentation feedback by email.