The HL7 Transform device allows you to make changes to an HL7 message before sending it to the next device in the channel. For example, you may convert a code to plain text or replace a patient identifier with a name.

Use the toolbar buttons to reorder the list of paths, copy, paste, activate single-step mode (see Troubleshooting below), and pause the selected transform path.

Configuring the HL7 Transform device

Select the HL7 Transform device in the channel to see all of the transform actions and conditions associated with the device.

The device can have one or more transform functions. The checkbox in the Enabled column tells whether or not the condition is in use.

Clearing the Enabled box is equivalent to setting the Condition to "Never."

Adding a transform

The toolbar at the top of the transform lists allows you to add various types of transform operations to the device.

Each transform contains the following:

Enabled: When this box is checked, the transform is evaluated as part of the message transformation process.
Path: This is the HL7 field/path whose value is being transformed.
Transform: The expression, or annotated description, of the transform operation itself.
Condition: A boolean expression that evaluations to True or False. When True, the operation in the Transform field is evaluated.
Description: An optional, plain-English, user-defined description of the transform operations

Transforms are evaluated sequentially, in the order in which they appear in the table. The following transforms are available.

Expressions

The Expression Transform uses simple expressions to transform a message path. Click the button to add a new row. In the Path column, enter the message path you want to transform (e.g., MSH-3).

Enter the transform expression in the Transform field. When run, the expression will return a new value for the specified path. Transform expressions are expected to return string values. This is the opposite of conditional expressions, which return Boolean values. For this reason, transform expressions should not contain compare operators such as '='.

There are some sample expression transforms:

ORC-3: Returns the current value from HL7 path ORC-3.
OBR-32.1.1 + '^" + OBR-32.1.2: Concatenates the path values of OBR 32.1.1 and OBR 32.1.2 with a hat separator.
'RADIS1': Returns the string RADIS1.

Enter an optional description for the expression transformer in the Description field.

Tables

The Table transform maps existing HL7 path values to new values. Click the Add Table Transformer button to add the transformer, then click the icon to launch the popup window. In the Path column, enter the HL7 path to be transformed. Add a condition (see Conditions below), and then click the text in the Transform field to show the Table Editor popup window.

This window contains the following fields:

Assignment Path: The path that will receive the modified value.
Source Path: The path that contains the value that will be checked against the mapping table's In values.
Table Name: An optional name for the current table. If you want to use an existing mapping table, select it from the drop-down.
Empty Mapping: Enter the value to be used if the source path value is empty.
Unmatched Mapping: If none of the mapping table's In values match the source path value, you can set a new value or select No Change.
Mappings tab: This tab contains the table mapping values:
- In Value: The source path value to match.
- Out Value: The new assignment path value, if the In Value matches the table.
- Mappings Description: An optional plain-English description for the mapping.

You can also copy all of the mappings in the table to the clipboard, or paste mappings from the clipboard into the table using the available button icons.

When the In Value for the specified HL7 path matches the table, it will be transformed and the HL7 message path will be populated with the specified Out Value.

Once you have created a mapping table, you can use that table in other table transforms within the HL7 Transform device.

Custom Code

Us the Custom Code transform to write a message-transforming function in C#. Click on the Add C# Transformer button and then click the Function(<Name>) text to launch the popup window.

The window contains the following:

Function Name: A descriptive name for the function. Do not change the C# function name.
References: Click to add an assembly reference to your transform.
In the box, enter your message transform code.
Compile Errors: When the transform code is compiled, any errors will be displayed in this bottom box.

Again, you can set a condition for the transform and add an optional description.

Adding References

To add an assembly reference to your custom code transform, click the References button.

You can add .NET assembly references or references from other devices. Click on the appropriate tab to see a list of references.

.NET References

The .NET tab contains the following:

Filter: Use this to filter the list of available assemblies.
Include: Check this box to include the reference in the device. You can select multiple assemblies.
Assembly Name: The GAC assembly name.
Version: The version number associated with the reference. Note that some assemblies may have multiple versions; be sure to select the version that targets .NET version 4.5.1.
Path: The path of the assembly file.
Browse: Click the button to browse for a specific non-GAC assembly file.

Device References

You can also reference assemblies from another device in your custom code transform. Click the Devices tab to see a list of available devices.

Click the arrow icon to expand/collapse the list of devices in each category. Click the checkbox to include the particular device assembly in the transform.

When you are finished, click OK.

Filters

Use the Filter Transform to filter any unwanted HL7 messages out of the incoming feed before they are passed to the next device in the channel. For example, you may want to filter out messages if a specific field contains a certain value.

You can perform more complex filtering using the C# Transformer.

Click the Add Filter Transform button. In the Condition field, enter the field to be checked and the value that will trigger the filter. In the example below, the transform will filter out messages where the MSH-9 path contains the value "ADT."

Click the icon to launch the popup window.

Normally, filtering simply removes the message and puts it in the Filtered category in the Queue. If you want the message to be marked as an Error instead, and listed in the Error category, check the box. You will see that the default value of "False" in the Transform field is changed to "True."

To add a message that should be included in the message history when the message is moved to the Filtered or Error queue, enter it in the Filter Message field.

Click the "X" to close the window.

Segment Filters

Sometimes, you may want to let a message through, but exclude (or only include) certain portions of the message. To do this, use the Segment Filter Transformer. Click the Add Segment Filter Transform button and then launch the popup window.

First, choose whether to include or exclude the listed segments. Enter the individual segments in the Segments column (e.g., MSH). As you enter segments, a description is populated. For example, specifying MSH in the Segments column will filter out all segments that are in the Message Header.

When you are finished, close the popup window.

Conditions

A condition is an expression that, when it evaluates to True, triggers the execution of a transform. You can set a condition for any transform.

In the above example, if the HL7 path "OBR-3.1" is empty (null), the transform will be executed.

The following conditions are available:

Always: Returns true and the transform will always be executed.
Never: Returns false, and the transform will never be executed (this is equivalent to unchecking the Enabled option).
<path>=<value>: Does the specified HL7 path equal the specified value (e.g., PV1-8.1.1=99999 - does the value of the PV1-8.1.1 path equal 99999).
<path>!=<value>: Does the specified HL7 path no equal the specified value (e.g., PV1-8.1.1!=99999 - does the value of the PV1-8.1.1 path NOT equal 99999).
<path='': Is the specified HL7 path empty (e.g., OBR-3.1='' - is the OBR-3.1 path empty).

Available functions

The following functions are available for use in the HL7 Transform device.

Function	Use
?	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-2) will append the contents of the OBR-2 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 allowedCharacters. 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 7.
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 that is used to select a portion of the string. 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'.
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'.
UnEscape(expression)	The UnEscape function replaces escape characters with the character it represents.

Deleting a transform

If you want to temporarily stop using a transform, uncheck the box in the Enabled column. But there may be times you want to completely delete the transform. This cannot be undone, so use with caution.

Highlight the row containing the transform you want to delete.
Click the Delete the current HL7 path icon.
Confirm the deletion.

Troubleshooting the HL7 Transform device

The best way to diagnose problems with a transform is to compare the incoming message with the transformed message. Connexion displays this if you click on the message in the Queue.

Click on each message to see the proposed transform changes. Use the arrows to browse through pages of messages.

Changes to message text are highlighted in yellow. Additions to the message are in green; deletions are displayed in red.

By default, clicking on a message displays the changes that will be performed by every transform executed by the HL7 Transform device. If you want to see the changes for each transform individually, use Connexion's Single Stepping functionality.

Single Stepping

Single-stepping is a standard code convention that allows you to view individual transform changes line by line. To activate single-stepping, click the toolbar button.

Once single-stepping is activated, the transform currently being displayed is highlighted in yellow.

Use the arrow buttons, click the single-step button again, or use the F10 key to navigate through each transform to view the changes. When you have finished stepping through each transform, Connexion will exit single-step mode.

To exit single-step mode, click the Exit single-step mode button (the red box next to the single-step button on the toolbar).

Connexion

HL7 Transform device

Analytics