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 check box in the Enabled column tells whether or not the condition is in use.

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

The following transforms are available.

Using the Expression Transformer

The Expression Transformer lets you write a regular expression to make changes to message data. Click the button to add a new row. In the Path column, enter the message field you want to transform (e.g., MSH-3). Click on the expression symbol to see a list of possible expressions. You can also start typing to see a list of matching expression possibilities.

Enter the parameters for the expression. Connexion will display an error message if the expression is invalid.

You can set the conditions under which the expression is run in the Conditions column. By default, expressions are always run. However, you could choose to only execute the expression when the value of the selected field matches something specific (e.g., when MSH-9.2 = RO1).

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

Expressions are automatically saved.

Using the Table Transformer

Use the Table Transformer to map existing HL7 path values to new ones. Click the Add Table Transformer button to add the transformer, then click the icon to launch the popup window.

Set the Assignment Path (where the data will go) for the transformer and the Source Path (where the data will come from). In the Table Name field, specify the table to which the information should be written. You can create a new table or write to an existing table.

Set the value that should be used for an Empty value (the default is to leave it empty) and what should be used if the source value cannot be matched (the default is to leave it unchanged).

On the Mappings tab, list the In values and the corresponding Out values (that is, what matches for each value is). Optionally, enter a description. You can also specify that matches be case-sensitive by checking the box.

When you are finished, close the popup window. The list of transformers will show the new table transformer. Set any conditions for the transformer or add an optional description.

Using the C# transformer

If you know C#, you can write custom C# code to execute your transformer function. Click on the Add C# Transformer button and then click to launch the popup window.

Enter a name for the transformer. In the popup, write the C# code to execute the desired function. When you are finished, close the popup window.

Set any conditions for the transformer or add an optional description.

Using the Filter Transform

You can 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.

Click the Add Filter Transform button. In the Path column, enter the field you want to check (e.g., MSH-3). Click the icon to launch the popup window.

Enter the value that should be matched to the incoming message (the Filter Message).

By default, filters are "false." That is, if the Filter Message value does not match the incoming field value, the message will be filtered out. If desired, Connexion can mark this as an error (check the Mark as Error box on the popup).

Once the Filter Transform has been added and configured, set the Condition and add an optional Description.

Using the Segment Filter Transform

Sometimes, you may want to let a message through, but exclude (or only include) certain fields. 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.

Using Conditions

TBD

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.

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

Troubleshooting the HL7 Transform device