• Settings
• Legacy Settings
• Applying the Filter
• Character Encoding issues in XML Files

Settings

When you create a channel, you can specify a filter that defines a transformation to be performed on incoming messages before they are transmitted to the destination component of the channel. You can also use this filter to specify that certain types of messages are to be ignored.

To add a filter to your channel:

1. When configuring a new channel, click the Filter tab.
2. Enable the Use filter check box. Additional settings appear automatically:
3. From the Apply filter list box, select the appropriate option:
   • Select before writing the message to the queue to apply the filter before the message is logged.
   • Select after reading the message from the queue to apply the filter after the message is logged. See Applying the Filter for more information on how this filter affects message logging.
4. Enable the Log pre/post-filter message check box if you want to write an additional copy of the message to the log files before/after the filter is applied. This additional copy of the message is written with a message type of Unqueued message.
5. From the Filter options list, select the most appropriate method:
   • Select Translator if you wish to create a script using Iguana’s Translator tool that will transform data flowing through the filter. If you select Translator, no additional settings are required.
   • Select Legacy if you wish to use a VMD file to specify how the data flowing through the filter should be transforms (or what messages are to be ignored). If you select Legacy, additional settings appear. See below for details.

Legacy Settings: [top]

If you selected the Legacy filter option, the following settings appear:

1. In the Full filter VMD path field, type or browse for the location of the VMD file that will be used to perform filtering. When you supply the file path, the absolute path is displayed to ensure that the file is located where you expect it to be.

   Note: To include the value of an environment variable in the file path, use ${name}, where name is the name of the environment variable that you have defined. For example, the file path ${MYDIR}\myfile.vmd includes the value of the MYDIR environment variable. The iguana_dir environment variable, which is defined by Iguana, is set to be the location of the Iguana configuration directory. To include this directory in your file path, specify ${iguana_dir} as part of the path.

2. From the Error handling list box, select how errors should affect the behaviour of this channel:
   • Select Skip message to log the errors and skip the current message.
   • Select Stop channel to log the errors and stop the channel.
3. In the Ignored messages field, type the name of a message that is to be ignored by this channel and click Add Ignored Message.The message names specified here must match message names defined in the VMD file that you’ve specified by the Full filter VMD path field. To remove a message from the ignore list, click the Remove button beside its name.

   Note: If you want to add multiple messages to the list of those to be ignored, press Return or Enter after typing a message name instead of clicking the Add Ignored Message button.

4. From the Transformation mode list box, select the appropriate mode:
   

   Transformation mode	Definition
   No transformation	Messages are filtered without being transformed.
   Scripted transformation	Use scripted transformation to transform the messages.
   Graphical transformation	Use graphical transformation to transform the messages.
   XML to HL7	Transform the message from XML format to HL7 format.
   HL7 to XML	Transform the message from HL7 format to XML format.

5. If you selected Scripted transformation, a Configuration name field appears that allows you to the configuration name that is defined in your VMD file. If you have not created any configuration names for your VMD file, use default.
6. If you selected Graphical transformation, two additional fields appear:
   • In the Incoming configuration name field, type the name of the incoming configuration.
   • In the Outgoing configuration name field, type the name of the outgoing configuration.

   Both of these configuration names must be defined in the VMD file specified in the Full filter VMD path field.

Applying the Filter [top]

A filter can be configured for any channel that you create. This filter can define a transformation that is to be performed on incoming messages before they are sent to the destination component of the channel. The filter can also specify that messages of certain types are to be ignored.

When you configure a filter for a channel, you can specify that the filter is to be applied before or after the message is queued in the Iguana log:

• If the filter is applied before writing the message to the queue, only the transformed message is added to the log. Messages that are ignored are not logged.
• If the filter is applied after reading the message from the queue, all messages are logged right away. Messages that are ignored are included in the log, but are skipped.

For best results, applying the filter after reading the message from the queue is recommended. Here are the reasons why this approach is best:

• If a filter is applied after the original message is logged, any future log entries for this message can be related to the original message. This is helpful when you are debugging your channel.
• Because the original message is logged, it can be resubmitted to the filter and destination if necessary.
• If an error occurs during filtering, and the filter is configured to stop the channel when an error occurs, the message that caused the error will still be in the message queue. If the filter is applied before the message, the original message is lost.
• If the filter is performing a transformation, and the transformation script in the VMD file takes a long time to execute, other messages can still be added to the message queue. If the filter is applied before the message, the transformation must be completed before other messages can be added to the message queue.

However, applying the filter before writing the message to the queue has its advantages:

• If an incoming message contains confidential data, the message can be ignored, which ensures that it does not appear in the Iguana logs. You can also transform a message to eliminate the confidential data before the message is logged.
• If a message is too large to be logged, a transformation script can eliminate unneeded information and make the message smaller.
• If your incoming messages are in XML format, and you only want HL7 messages to appear in your logs or in your message queue, you can apply the filter’s transformation before logging the message.

Character Encoding issues in XML Files [top]

If you are having trouble processing XML files in Iguana, the following tips may be helpful to you:

1. Ensure that the XML file specifies the character encoding that is being used. This character encoding information normally appears as the first line of the XML file:<?xml version="1.0" encoding="UTF-8"?>
2. When you define a VMD file in the Filter component of a channel to perform XML to HL7 translation, this VMD file can only process XML input that is UTF-8 or ASCII encoded. XML files that are encoded in ISO-8859-1 format (ISO-Latin-1) may not yield the output that you are expecting.For example, consider the following sample segment, which is generated from an XML file in ISO-8859-1 format:FT1|4|1|Incoming|200701240000^200701240000|200701251212|CG|Passé|Call as soon as possible||1||||||ABC||||4004^Smith^ John|In this sample segment, notice that the eighth field contains some unexpected characters. This is because the HL7 output message is generated in UTF-8 format. For best results, ensure that the XML input is in UTF-8 or ASCII format.