HL7 Transform Tool

Owned by Jonathan Reis
Last updated: Aug 07, 2021
5 min read

The new HL7 Transform Tool allows users to make bulk modifications to messages within the current tab. While message transformation functionality has been available in HL7Spy since version 1.x, it has required users to write c# code snippets in the Custom Code tool. Now non-programmers can make bulk transformations to HL7 messages without having to write code.


HL7 Transform Tool Features

  • Set fields to constant values. Eg, MSH-4=’FIXEDVALUE’ – sets MSH-4 to FIXEDVALUE
  • Copy fields from one part of the message to another. Eg, MSH-5=MSH-4 – sets MSH-5 to the value in MSH-4
  • Use a table to map one field to another. Eg PV1-2 = Table(PV1-2,’ER’ -> ‘E’, ‘OP’ -> ‘O’, ‘IP’ -> ‘I’) – maps ER to E, OP to O, and IP to I
  • Use conditions to control when a transformation is triggered. Eg, MSH-4=MSH-4+’-INPATIENT’  when  PV1-2=’I’ – appends ‘-INPATIENT’ to MSH-4 if PV1-2 is set to ‘I’
  • Test button runs the transform on the message currently displayed in the editor to test the results of the transform

Expressions

FunctionUse
?Use this to evaluate the truth of an expression and return a value. If the condition evaluates to "true," the true expression is returned, otherwise, the false expression is returned. The specified condition must evaluate to a Boolean value. Example: MSH-3='ADM' ? 'HIS' : 'RIS' means that if the MSH-3 segment is ADM (true), the value returned will be 'RIS'; otherwise, the value returned will be 'RIS'
??This function returns expression 2 if expression 1 is null; otherwise, it returns expression 1. Both expressions must evaluate to string values. Example: OBR-2 ?? OBR-3 ?? 'UNKNOWN' will return "unknown" if OBR-2 and OBR 3 evaluate to null.
AppendSegment(segmentName)

This function allows you to append a segment with the given segment name to the end of a message. Example: AppendSegment("OBR") will append the contents of the OBR segment to the end of the message.

Coalesce(expression1,expression2,...,expressionN)This function returns the first value from the list of expressions. One to N expressions can be included. Example: Coalesce(OBR-2,OBR-3,'UNKNOWN') will return UNKNOWN if OBR-2 and OBR-3 are empty.
Escape(expression)This function encodes a string or expression with the HL7 Escape characters of the message. Example: Escape(MSH-2) will return "\S\\R\\E\\T\".
FilterString(expression,allowedCharacters)This function returns a string containing only those characters specified in allowedCharaters. For example, the source system may provide a value in a field with extra characters. You can use this function to strip out only the characters in the string you are interested in. The expression must evaluate to a string; allowedCharacters specifies what will be passed through the filter. Example: FilterString(AA00BB12345,12345) will return the string "12345".
GetDate(format='yyyyMMddhhmmss')This function will return the current date, as specified by the server machine, in the specified date format. The default format is yyyyMMddhhmmss (year, month day, hour, minute, second), but you can set whatever format you desire. Example: Using GetDate(format=yyyyMMdd) will return the date July 25, 2015 as "20140725".
If(condition,trueExpression,falseExpression)This function evaluates a condition. If it returns True, the specified trueExpression will be used; otherwise, the falseExpression is used. This function is useful if, based on the contents of a particular segment, you want to write certain values to the message. The condition must evaluate to a Boolean value. Example: If(MSH-3='ADM','HIS','RIS') will return the value "HIS" if the MSH-3 segment contains "ADM"; otherwise, the function will return the value "RIS".
In(expression,string1,string2,...,stringN)This function returns "true" if the expression evaluates to one or more values in the list. The expression must evaluate to a string. This is useful in determining if an expression contains a valid string. Example: In(MSH-3='ADM','HIS','RIS') evaluates to true if the MSH-3 segment contains the string ADM, HIS, or RIS.
IndexOf(expression,string)This function returns the one-based index of the string specified in the expression. Otherwise, it returns 0. Example: IndexOf('001234.5600', '.') returns a value of 6.
InTable("InTableName")This function uses the InTable with the specified name as a conditional expression. Example: InTable("Providers") will use the Providers table as a conditional expression.
Left(expression,string)This function returns the string to the left of the specified match. Perhaps your source system always inserts a certain string in a segment, but you only want what immediately precedes the string in your transformed message. Use this function to extract that string. The expression must evaluate to a string and "string" is the characters to match. Example: Left('1234.56','.') will return the value "1234".
Len(expression)This function returns the length (in characters) of the specified expression. The expression must evaluate to a string. Example: Len('123456') returns '6'.
LTrim(expression)This function trims any leading whitespace characters from the specified string. If the source system pads strings with whitespace, this function will allow you to remove it. The expression must evaluate to a string. Example: LTrim(' 1234.56') will return '1234.56'.
LTrim(expression,string)This function trims the specified string of characters from the expression. This is useful if your source system pads values with zeroes. The expression must evaluate to a string. Example: LTrim('0001234.5600','000') returns '1234.5600'.
Remove(expression,string1, string2,...,stringN)This function removes the specified strings from the expression. For example, if you need to strip hyphens from a phone number value. The expression must evaluate to a string. Example: Remove('408-354.7787','-','.') returns "4083547787".
Replace(expression,string,string)Use this function to replace an existing value with a new one. For example, the source system may provide phone numbers using a period as a separator and you need to replace it with a hyphen. The expression must evaluate to a string. Example: Replace(408.354.7787','.','-') returns "408-354-7787".
Right(expression,string)This function returns the string to the right of the specified match. The expression must evaluate to a string. Example: Right('1234.56','.') returns "56".
RTrim(expression)This function allows you to strip any trailing whitespace from a string. For example, the source system may add whitespace and you need to strip it before passing on the message. The expression must evaluate to a string. Example: RTrim('1234.56 ') returns '1234.56'.
RTrim(expression,string)This function allows you to strip specific characters from a string. For example, the source system may pad values with zeroes and you need to strip them before passing on the message. The expression must evaluate to a string. Example: RTrim('0001234.56000','000') returns '0001234.56').
Split(expression,charArray,index)Use this function to split a string. The charArray determines where to make the split. The index is a zero-based index. The expression must evaluate to a string. Example: Split(AAA/AP,'/',1) returns "AAA AP".
SubString(expression,offset,length)Use this function to return a portion of a string. The offset is the starting number of the portion to be returned and length is the length, in characters, of the returned portion. Example: SubString('001234.5600',3,4) returns '1234'.
Table(HL7Path, In1 → Out1, In2 → Out2....)Use this function to map a set of input values to a set of output values. Example: Table(PV1-2,’ER’ -> ‘E’, ‘OP’ -> ‘O’, ‘IP’ -> ‘I’) – maps ER to E, OP to O, and IP to I
Trim(expression)This function trims any whitespace from either end of the expression. The expression must evaluate to a string. Example: Trim(' 1234.56 ') returns '1234.56'.
Trim(expression,string)This function trims the specified characters from either end of the expression. The expression must evaluate to a string. Example: Trim('0001234.56000',0) returns '1234.56'.
TruncateSegment(HL7Path)Truncates a segment to the specified path. Example: TruncateSegment(PID-10) will truncate the PID segments to 10 fields.