HL7 Parser

HL7 Parser Javascript API

The HL7 Parser allows you to transform an HL7v2 message string into a queryable object, Message.

var message = HL7.parse(`
MSH|^~\&|GHH LAB, INC.|GOOD HEALTH HOSPITAL|ADT1|GOOD HEALTH HOSPITAL|20210305104622||ACK^A01^ACK|ACK-MSG00001|T|2.5.1
MSA|AA|MSG00001`);

The HL7.parse(`MSH|…`) returns a Message object, which is defined as follows.

 

Message

The Message object allows you to fetch the underlying elements (segments, fields, components, sub-components) and properties.

Properties

sendingApplication: string

Get the MSH.3 – Sending Application field value

receivingApplication: string

Get the MSH.5 – Receiving Application field value

messageType: string

Get the MSH.9.1 – Message Code and MSH.9.2 – Trigger Event (ADT_A04), or the MSH.9 – Message Type field value if MSH.9.1 or MSH.9.2 is not specified.

Methods

get(position: string) : segment | field | component | sub-component

Returns the first segment, field, component, or sub-component object matching the given position. See the position definition.

getAll(position: string) : segment[] | field[] | component[] | sub-component[]

Returns an array with all segment, field, component, or sub-component objects matching the given position. See the position definition.

toString()

Returns a string representation of the message.

 

Segment

The segment object allows you to fetch the underlying elements (fields, components, sub-components) of the segment.

Methods

get(position: string) : field | component | sub-component

Returns the first field, component, or sub-component object matching to the given position. See the position definition.

getAll(position: string) : field[] | component[] | sub-component[]

Returns an array with all field, component, or sub-component objects matching the given position. See the position definition.

toString()

Returns a string representation of the segment.

 

Field

The Field object allows you to fetch underlying elements (components, sub-components) of the field.

Properties

position: string

Get the absolute position of the field.

var pid_8 = message.get('PID.8');
log('Position: ' + pid_8.position);
// Position: PID.8

Methods

get(position: string) : component | sub-component

Returns the component or sub-component object matching the given position. See the position definition.

toString()

Returns a string representation of the field. If the field contains components or sub-components, the toString() method will include component and sub-component values and delimiters.

*Type Coercion: The field object can be converted to a string automatically (implicit conversion).

var pid_8 = message.get('PID.8');
log('Value: ' + pid_8);
log('With conversion: ' + pid_8 == 'M');
log('Without conversion: ' + pid_8 === 'M');
// Value: M
// With conversion: true
// Without conversion: false

 

Component

The Component object allows you to fetch underlying sub-components of the component.

Properties

position: string

Get the absolute position of the component.

var pid_5_2 = message.get(‘PID.5.2’);
log(‘Position: ‘ + pid_5_2.position);
// Position: PID.5.2

Methods

get(position: string) : sub-component

Returns the sub-component object matching the given position. See the position definition.

toString()

Returns a string representation of the component. If the component contains sub-components, the toString() will include sub-component values and delimiters.

*Type Coercion: The component object can be converted to a string automatically (implicit conversion).

var pid_5_2 = message.get('PID.5.2');
log('Value: ' + pid_5_2);
log('With conversion: ' + pid_5_2 == 'John');
log('Without conversion: ' + pid_5_2 === 'John');
// Value: John
// With conversion: true
// Without conversion: false

 

SubComponent

The SubComponent object allows you to get its value.

Properties

Position: string

Get the absolute position of the sub-component.

var pid_5_1_1 = message.get('PID.5.1.1');
log('Position: ' + pid_5_1_1.position);
// Position: PID.5.1.1

Methods

toString()

Returns a string value of the sub-component.

*Type Coercion: The sub-component object can be converted to a string automatically (implicit conversion).

var pid_5_1_1 = message.get('PID.5.1.1');
log('Value: ' + pid_5_1_1);
log('With conversion: ' + pid_5_1_1 == 'Doe');
log('Without conversion: ' + pid_5_1_1 === 'Doe');
// Value: Doe
// With conversion: true
// Without conversion: false

 

Position

The position is a string that allows you to target one or many elements inside a message. The position should be expressed using the following structure:

segment-id[segment-repetition*].field-position[field-repetition*].component-position.sub-component-position

(*those fields are optional, they indicate if the user is targeting a single element. If not specified, every element inside the message corresponding to the position will be targeted)

 

Here are some examples:

Segment:

  • OBX” -> corresponds to any repetition of the OBX segment

MSH||||||
OBX||||||
OBX||||||
OBX||||||

  • OBX[2]” -> corresponds to the second repetition of the OBX segment

MSH||||||
OBX||||||
OBX||||||
OBX||||||

 

Field:

  • 5” -> corresponds to any repetition of the OBX.5 field

MSH||||||
OBX|||||OBX.5~OBX.5|
OBX|||||OBX.5~OBX.5|
OBX|||||OBX.5~OBX.5|

  • OXB[2].5” -> corresponds to any repetition of the OBX.5 field, in the second repetition of the OBX segment

MSH||||||
OBX|||||OBX.5~OBX.5|
OBX|||||OBX.5~OBX.5|
OBX|||||OBX.5~OBX.5|

  • 5[2]” -> corresponds to the second repetition of the OBX.5 field, in any repetition of the OBX segment

MSH||||||
OBX|||||OBX.5~OBX.5|
OBX|||||OBX.5~OBX.5|
OBX|||||OBX.5~OBX.5|

  • OXB[2].5[2]” -> corresponds to the second repetition of the OBX.5 field, in the second repetition of the OBX segment

MSH||||||
OBX|||||OBX.5~OBX.5|
OBX|||||OBX.5~OBX.5|
OBX|||||OBX.5~OBX.5|

 

Component:

  • 5.2” -> corresponds to any repetition of the OBX.5.2 component

MSH||||||
OBX|||||OBX.5.1^OBX.5.2~OBX.5.1^OBX.5.2|
OBX|||||OBX.5.1^OBX.5.2~OBX.5.1^OBX.5.2|
OBX|||||OBX.5.1^OBX.5.2~OBX.5.1^OBX.5.2|

  • OXB[2].5.2” -> corresponds to any repetition of the OBX.5.2 component, in the second repetition of the OBX segment

MSH||||||
OBX|||||OBX.5.1^OBX.5.2~OBX.5.1^OBX.5.2|
OBX|||||OBX.5.1^OBX.5.2~OBX.5.1^OBX.5.2|
OBX|||||OBX.5.1^OBX.5.2~OBX.5.1^OBX.5.2|

  • 5[2].2” -> corresponds to the second repetition of the OBX.5.2 component, in any repetition of the OBX segment

MSH||||||
OBX|||||OBX.5.1^OBX.5.2~OBX.5.1^OBX.5.2|
OBX|||||OBX.5.1^OBX.5.2~OBX.5.1^OBX.5.2|
OBX|||||OBX.5.1^OBX.5.2~OBX.5.1^OBX.5.2|

  • OXB[2].5[2]” -> corresponds to the second repetition of the OBX.5.2 component, in the second repetition of the OBX segment

MSH||||||
OBX|||||OBX.5.1^OBX.5.2~OBX.5.1^OBX.5.2|
OBX|||||OBX.5.1^OBX.5.2~OBX.5.1^OBX.5.2|
OBX|||||OBX.5.1^OBX.5.2~OBX.5.1^OBX.5.2|

 

Sub-Component:

  • 5.1.2” -> corresponds to any repetition of the OBX.5.1.2 sub-component

MSH||||||
OBX|||||OBX.5.1.1&OBX.5.1.2^OBX.5.2~OBX.5.1.1&OBX.5.1.2^OBX.5.2|
OBX|||||OBX.5.1.1&OBX.5.1.2^OBX.5.2~OBX.5.1.1&OBX.5.1.2^OBX.5.2|
OBX|||||OBX.5.1.1&OBX.5.1.2^OBX.5.2~OBX.5.1.1&OBX.5.1.2^OBX.5.2|

  • OXB[2].5.1.2” -> corresponds to any repetition of the OBX.5.1.2 sub-component, in the second repetition of the OBX segment

MSH||||||
OBX|||||OBX.5.1.1&OBX.5.1.2^OBX.5.2~OBX.5.1.1&OBX.5.1.2^OBX.5.2|
OBX|||||OBX.5.1.1&OBX.5.1.2^OBX.5.2~OBX.5.1.1&OBX.5.1.2^OBX.5.2|
OBX|||||OBX.5.1.1&OBX.5.1.2^OBX.5.2~OBX.5.1.1&OBX.5.1.2^OBX.5.2|

  • 5[2].1.2” -> corresponds to the second repetition of the OBX.5.1.2 sub-component, in any repetition of the OBX segment

MSH||||||
OBX|||||OBX.5.1.1&OBX.5.1.2^OBX.5.2~OBX.5.1.1&OBX.5.1.2^OBX.5.2|
OBX|||||OBX.5.1.1&OBX.5.1.2^OBX.5.2~OBX.5.1.1&OBX.5.1.2^OBX.5.2|
OBX|||||OBX.5.1.1&OBX.5.1.2^OBX.5.2~OBX.5.1.1&OBX.5.1.2^OBX.5.2|

  • OXB[2].5[2].1.2” -> corresponds to the second repetition of the OBX.5.1.2 sub-component, in the second repetition of the OBX segment

MSH||||||
OBX|||||OBX.5.1.1&OBX.5.1.2^OBX.5.2~OBX.5.1.1&OBX.5.1.2^OBX.5.2|
OBX|||||OBX.5.1.1&OBX.5.1.2^OBX.5.2~OBX.5.1.1&OBX.5.1.2^OBX.5.2|
OBX|||||OBX.5.1.1&OBX.5.1.2^OBX.5.2~OBX.5.1.1&OBX.5.1.2^OBX.5.2|