Using PKB's HL7 APIs

Owned by Andrew Turner (Unlicensed)
Last updated: Oct 18, 2024 by Andy Clowe
3 min read

Quick start

Documentation

Getting started

API documentation

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\

Yes

Yes

New line

<new line>

\.br\

Yes

No

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

  • 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 subpages, and also brought together in the HL7 Configuration Form.