The HL7 message mapping script language consists of several functions that facilitate the copying and manipulation of fields in the message. The functions are described in a NameValueCollection object or a configuration file that can be read through a NameValueCollection object.

Each property describes a transformation function for a particular field in a segment in the form:

SEGMENT_NAME[INDEX].X.Y.Z = MAPPING_EXPRESSION

or

PRESCRIPTx = ADD_OR_DEL_FUNC

or

POSTSCRIPTx = DEL_FUNC

where:

• SEGMENT_NAME - is the name of the segment in which the field is located
• INDEX - is the zero based index of the segment with the specified name within the message, if the index is not specified the mapping applies to all segments with that name
• X - is the sequence number of the field in the segment as defined by HL7
• Y - is the component number in the field starting with one as the first component, if the field is of a base type (no components), Y must not be specified.
• Z - is the subcomponent number in the component starting with one as the first subcomponent, if the component is of a base type (no subcomponents), Z must not be specified.
• MAPPING_EXPRESSION - is an expression that describes how the field value should be replaced. It can be either a string value between quotation marks or a function as described below.
• PRESCRIPTx - marks a function to be executed before field mappings. PRESCRIPTS can be used to add or remove segments before processing. x is the number of the pre-script and establishes execution sequence of the PRESCRIPT lines in which PRESCRIPTS should be executed.
• POSTSCRIPTx - marks a function to be executed after field mappings. POSTSCRIPTS can be used to remove segments after processing. x is the number of the post-script and establishes execution sequence of the POSTSCRIPTS lines.

Example 1: MSH.4.1 = VALUEMAP( "A,B,C", "A", "D:A,E:B,F:C" ) causes the result of the VALUEMAP function to replace the the value of MSH.4.1 field.

Example 2: ORC[3].8.1.3 = FIRST( FIELD( "OBR.1.2" ), 5 ) causes the result of the FIRST function to replace the ORC.8.1.3 field in the fourth ORC segment of the message

Property values can contain macros defined in the form '@@MACRO_NAME', that will be replaced before the function is parsed. The values of each macro must be defined as another property with the name '@@MACRO_NAME'. Each macro can contain another macro.

The following functions are currently supported:

VALUEMAP( acceptableValues, defaultValue [, valueMappings ] )

This function maps coded field values to application defined values. 'acceptableValues' is the comma separated list of mapped output values. 'defaultValue' is the value to be used in case a mapping cannot be found. 'valueMappings' is a comma separated list of raw/mapped value pairs in the form 'rawValue:mappedValue'.

If the acceptable value list contains the string "##ANY-NON-BLANK-VALUE##", any string value with at least one character will be accepted as the mapped output.

Example: PID.3.6.2 = VALUEMAP( "XYZHOSP,ABCHOSP", "ABCHOSP", "ABC:ABCHOSP,XYZ:XYZHOS" ) If the PID.3.6.2 field value is 'ABC', the result is "ABCHOSP". If the field value is 'CDE' the result is 'ABCHOSP'.

EQUAL( a, b, trueVal [, falseVal ] )

This function compares the results of statement 'a' and statement 'b'. If the comparison is true, then the result of statement 'trueVal' is returned. If the comparison is false the result of the 'falseVal' statement is returned. If the 'falseVal' argument is not specified and the comparison is false the return value is the current value of the field.

Both parameters can be other functions.

Example: OBR.25.1 = EQUAL( FIELD( "OBR.25.1" ), "I", "S", FIELD( "OBR.25.1" ) ) If the value of OBR.25.1 is 'I', then 'S' is returned. However, if 'I' is not the value in OBR.25.1, then the contents of OBR.25.1 is returned.

FIRST( [value, ] length [, pad] )

This function returns the first 'length' number of characters of the target field or of 'value' if provided. If the 'pad' parameter is provided the return value is left padded with 'pad' if necessary, so that the returned string is always 'length' characters long.

The 'value' parameter can be a function.

Example1: OBR.36.1 = FIRST( 8 ) If OBR.36.1 is |20031214083000|, then the function returns the date portion of the scheduled date/time (YYYYMMDD) of an exam. The scheduled start date = 20031214.

Example2: PID.2.1 = FIRST( 8, 0 ) This example returns the patient ID with leading zeros added, so that the total string length is equal to 8. If PID.2.1 is |123456|, then it will become |00123456|.

LAST( [value, ] length [, pad] )

This function returns the last 'length' number of characters of the target field or of 'value' if provided. If the 'pad' parameter is provided the return value is right padded with 'pad' if necessary, so that the returned string is always 'length' characters long.

The 'value' parameter can be a function.

Example: OBR.36.1 = LAST( 6 ) If OBR.36.1 is |20031214083000|, then the function returns the time portion of the scheduled date/time (YYYYMMDD) of an exam. The scheduled start time = 083000.

APPEND( [value,] suffix ) PREPEND( [value,] prefix )

These functions return the concatenation of the 'suffix'/'prefix' and the value of the target field or 'value' if provided. APPEND add the suffix to the end of the value while PREPEND adds the prefix to the beginning of the value.

Both parameters can be functions.

REPLACE( [value,] original, new )

This function replaces all occurrences of 'original' with 'new' in the target field or 'value' if provided. The 'original' string is a regular expression, which means that [\^$.|?*+() characters should be avoided.

All parameters can be other functions.

REMOVE( [value ,] toRemove )

This function removes all occurrences of 'toRemove' from the target field of from 'value' if specified.

Both parameters can be other functions.

Example1: PID.11.1 = REMOVE( "'" ) If PID.11.1 is "15 PRINCES'S", then the function returns "15 PRINCESS".

Example2: PID.11.1 = REMOVE( FIELD( "PID.11.2" ), "," ) If PID.11.2 is "Some,thing", then the function returns "Something". PRINCESS^^ST. LOUIS^MO^63130.

STRIPL( [value ,] lead ) STRIPT( [value ,] trail )

STRIPL removes the leading occurrences of 'lead' from the target field or from 'value' if specified. STRIPT removes the trailing occurrences of 'trail' from the target field or from 'value' if specified.

For both functions, all parameters can be functions.

Example1: ORC.2.1 = STRIPL( "0" ) If ORC.2.1 is |00025487|, then 25487 is returned.

Example2: ORC.2.1 = STRIPT( "0" ) If ORC.2.1 is |25487000|, then 25487 is returned.

SUBSTR( [value,] offset, length [, pad] )

This function returns 'length' characters, starting at 'offset'-th character of the target field or the first parameter if specified. The 'offset' parameter is zero based so that the first character has offset 0, the second character has offset 1 and so on. If the 'pad' parameter is specified the returned value is padded at the end with 'pad' so that the returned string is always 'length' characters long.

The 'value' and the 'pad' parameters can be functions.

Example: OBR.36.1 = SUBSTR( 8, 6 ) If OBR.36.1 is |20031222074500|, then the function returns 074500.

STRTOK( [value,] tokenIndex, separator )

This function separates the 'value' into pieces separated by 'separator' string and returns the piece at the index 'tokenIndex'. The index of the first piece is zero. If the 'value' parameter is missing this function operates on the value of the current field, i.e. the unmapped value of the field being set.

If the index is greater than the number of pieces this function returns an empty string.

The 'value' parameter can be another function.

Example: OBR.3.1 = STRTOK( 0, "R" ) If OBR.3.1 is |4525105R10245|, then the function returns 4525105.

FIELD( fieldLocation )

Returns the original value (before any mapping) of the field specified by fieldLocation. This statement is useful for copying data from one HL7 field to another.

E.g. PID.5.1 = FIELD( "NK1.1.2" ) The value of PID.5.1 will be replaced with the value of NK1.1.2 of the first NK1 segment in the message.

The statement supports specifying the relative position if the current segment is in a segment group. Prepending "P." before the segment name indicates this is a "parent" segment in the group. Prepending "C." before the segment name indicates this is a "child" segment in the group.

E.g. ORC.2=FIELD( "C.OBX[1].3.1" ) The value of ORC.2 will be replaced with the value of OBX.3.1 of this ORC's second child segment OBX.2=FIELD("P.ORC.3.1") The value of OBX.2 will be replaced with the value of ORC.3.1 of this OBX's parent segment

The segment name in the field location specifier can contain a segment index, e.g. FIELD( "PID[1].5.2" ) refers to the Given Name component of the Patient Name field in the second PID segment of the message. If a segment index is not specified and the segment name in the field locator is the same as the segment name of the field being set (current segment) the value is read from the current segment. NOTE: If the fieldLocation specifies the segment is a "child" in a segment group, the segment index means the child index in the group. e.g. ORC.2 = FIELD( "C.OBX[1].3.1" ) refers to the second child OBX segment of the ORC segment group.

If the specified segment does not exist in the message the field value remains unchanged.

If the field location parameter points to a field that has more components, the value assigned will be the value of the first component. E.g. FIELD( "PID.5" ) is equivalent to FIELD( "PID.5.1" ) and FIELD( "PID.5.1.1" ).

ADDSEG( segmentName, index )

Adds an empty 'segmentName' type segment at position 'index' to the message. The index is 0 based, e.g. ADDSEG( "MSH", 0 ) adds an MSH segment at the beginning of the message.

Because adding segments will change the index numbers of the segments that follow, segments should be added in reverse order (i.e. highest-numbered segments first).

DELSEG function has three forms:

DELSEG( segmentName ) - deletes all segments of the specified type

DELSEG( segmentName[n] ) - deletes the n-th segment of the specified type, segment numbering starts with 0, e.g. DELSEG( "OBX[0]" ) deletes the first OBX segment.

DELSEG( fromIndex [, toIndex] ) - deletes all segments starting with the segment at index 'fromIndex' up to and including the segment 'toIndex'. If the second argument is missing only the segment at 'fromIndex' is deleted. Indexes are zero based, e.g. MSH segment has index 0.

Because removing segments will change the index numbers of the segments that follow, segments should be removed in reverse order (i.e. highest-numbered segments first).