Developer documentation‎ > ‎HL7 API‎ > ‎

HL7 Message Specifications

Introduction to the HL7 Message Format

All HL7 messages comprise:
  • segments: one per line, starting with the segment name (like MSH or QRD) and followed by fields
  • each segment has fields separated by the | character. Notation example: the third field in the “ORC” segment is “ORC-3” for the MSH segment only, the first field has no field separator; it’s one character that is the field separator
  • each field can be split into components by the ^ character. Notation is similar: the first component of MSH-9 is noted as MSH-9.1
  • each component can be split into subcomponents with the & character
  • within a field that supports repetition, you can separate sets of components with the repetition character: ~
Escape Characters

Please note that we currently only support the following escape characters. These are fixed; they will not dynamically adjust if you try to set an alternative field separator or encoding characters in MSH-1 or MSH-2. For this reason, we strongly recommend that you use the standard characters for these purposes.

Reason Character to be escaped Escaped value Unescaped on input Escaped on output
Field separator | \F\ Yes Yes
Component separator ^ \S\ Yes Yes
Subcomponent separator & \T\ Yes Yes
Repetition separator ~ \R\ Yes Yes
Escape character\\E\YesYes
New line<new line>\.br\YesNo

Specification Conventions

  • The specification for each enabled message type details which segments and fields PKB needs for each message. We will simply ignore any fields or segments that we do not need, so don't worry about stripping them out.
  • The specifications might sometimes include a field that we don't use only where we feel it is worth explaining why this is the case.

Standard Behaviour

Please see our main documentation set for important information about the HL7 API.
  • Unexpected message types will be rejected with an error.
  • PID-2 has been deprecated; all patient identifiers should be listed in PID-3. However, in the interest of backwards compatibility, PKB will treat a value in PID-2 as if it had been given in the PID-3 list.
  • Some messages accept HTML fields. In these instances we will sanitize the content and strip out anything unusual. However, standard formatting and structure tags will be fine.
  • Currently, we neither detect nor reject duplicate messages based on their unique ID (MSH-10).
  • You are welcome to establish multiple HL7 connections, e.g. you might want to split ADT data into a separate feed from lab results.
  • The HL7 null value ("") is treated as follows:
    • The HL7 null value will be treated as the empty string when the value is evaluated for use.
    • The HL7 null value will not be accepted for a field which is marked as mandatory.
    • When performing a partial update (see message details for which support this):
      • The HL7 null value can be used to indicate a blank value should be set, whereas the absence of any value will indicate that the previous value should remain.
      • If an optional value has a default associated with it, the default will be applied only if the HL7 null value is provided.
    • Some fields, even though optional, require a non-null value, and therefore cannot be deleted using the HL7 null value. For example, the death indicator can be Y or N, but null is not meaningful. In addition, some fields are additive only; e.g. email addresses cannot be removed by sending the HL7 null value.

Configurable Behaviour

Some behaviours of the HL7 API are configurable. These are explained in the relevant sections of the main documentation set, and also brought together in the HL7 Configuration Form.

Standard Messages & Segments

Enabled Message Types

Any type of HL7 message is parsed automatically and passed through to the PKB back end, so it's fairly quick to enable processing of other messages types; we will be expanding this in the future.

Beta Message Types

The following message types are available but remain in Beta because they are not yet officially released on our production server: