The HL7 External Code Translation Filter takes input of one HL7 message and attempts to translate the contents of multiple, pre-configured coded fields to another coding system. Code Translation is an extension on Code Validation and is setup in a similar way.

The Code Translation filter performs validation in the same way as the Code Validation filter and once a field has been validated it is translated.

Configuration Properties

Property

Description

Definition

The definition file for input messages, click the ... Browse button to locate this.

Coded Fields

The coded fields to validate. These should be HL7 CE datatypes or CE compatible types. Refer to Configuration of Coded Fields for details.

Database url

The JDBC URL with which to connect to the database containing the coding systems. Refer to Database Drivers and URLs for details.

Database username

The username with which to connect to the database.

Database password

The password with which to connect to the database.

Database driver

The driver with which to connect to the database. Refer to Database Drivers and URLs for details.
Socket Timeout

Specifies how long, in seconds, the underlying connection should remain open before timing out. The socket timeout prevents Rhapsody from waiting indefinitely for results from a database in the event Rhapsody loses its connection to the database.

A value of zero indicates the timeout is not configured.

Tables

The code-set with which the coded fields are validated. Refer to Configuration of the Code Set for details.

Translation

The same columns as the Table setup except it describes which values the CE fields should be translated to. The Row in Translation are matched with the Rows in Tables by taking the first match between the 'Table Names'. Refer to Examples for details.

Fail Action

Determines if messages that fail code validation are sent to the error node (the default) or the normal connector to continue processing:

  • Continue Processing.
  • Send to Error Node (default).

Translation Behavior

Determines what should happen to the new values:

  • Shuffle Codings (default) - copies the current values to the Alternative Coding System fields and overwrites the current values.
  • Overwrite Coding - overwrites the current values.
  • Overwrite Alternative Coding - overwrites the Alternative Coding System fields.
  • Empty and Shuffle Codings.
  • Empty and Shuffle Codings, Load Local Description If Empty.

Error Generation Type

Defines how error messages are formatted:

  • HL7 (default).
  • None - errors are not attached to the message.
  • Plain Text.

Output Property

The message property to which a validation error list should be stored in when validation errors are detected. Defaults to CodeValidationErrors. A leading $ in front of this property name is ignored.

Change Identifier and Coding System Case

Determines whether the identifier's/coding system's case should be changed before testing if it is present. This option allows for case insensitivity as the filter has no way of knowing how the database handles case-insensitive comparisons or indexes.

  • No Change (default).
  • Uppercase.
  • Lowercase.

Cache Size

Specify the number of coded fields from the database that are stored in memory. The larger the size of the cache, the less database access is required which will increase performance but requires more memory. This must have a value of 1 or greater.

The default value is 100.

Cache Age Limit (minutes)

The age limit specifies how long a coded field will be retained for use by the filter. This allows updates in the database to propagate to the cache. The default value of 1440 (24 hours) means database updates can take a maximum of 24 hours to effect the filter.

Coded fields are not purged from the cache; they are only marked for update. Therefore having a low value does not decrease memory use in low activity periods.

Connection Pool Size

The number of connections the filter can have to the database. A value of 2 - 5 is generally appropriate. A small cache size (relative to the database) generally indicates a large pool size is required for best performance.

Invalid Path Action

The action to perform when a path is not valid for a message:

  • Throw Invalid Path Exception (default).
  • Log.
  • Ignore.

Examples

The following examples show two simple ways that translation can be performed. There are many possible ways for the translation to be performed. The only restrictions are: Both the Table and Translation have a Table Name that matches. Both the Table and Translation have an Identifier Column and either a Coding System, Coding System Column or both. Everything else is optional.

Example 1 shows a database table, the values set in the Tables and Translation and an example CE before and after it is translated.

Simple Translation

This example shows a simple translation using a database table that contains the Identifier and the Identifier to translate to. The coding system is specified as a parameter in the configuration.

Database Table CodingSystemA

Value

NewValue

A

Z

B

X

C

Y

D

W

Tables

Property

Value

Table Name

CodingSystemA

Identifier Column

Value

Description Column

 

Coding System

TestCodingSystem1

Version

 

Coding System Column

 

Version Column

 

Translation

Property

Value

Table Name

CodingSystemA

Identifier Column

NewValue

Description Column

 

Coding System

NewCodingSystem

Version

 

Coding System Column

 

Version Column

 

Example Message (OK)*

Coding System Name

TestCodingSystem1

Identifier

D

Result

Coding System Name

NewCodingSystem

Identifier

W

Translation Using a Database Table

This example shows a translation using a database table that contains both the coding System and Identifier to translate from and to.

Database Table MultipleA

System

Identifier

NewSystem

NewIdentifier

CS 1

A

CS A

1

CS 2

A

CS A

2

Table

Property

Value

Table Name

MultipleA

Identifier Column

Identifier

Description Column

 

Coding System

 

Version

 

Coding System Column

System

Version Column

 

Translation

Property

Value

Table Name

MultipleA

Identifier Column

NewValue

Description Column

 

Coding System

NewIdentifier

Version

 

Coding System Column

NewSystem

Version Column

 

Example Message (OK)

Coding System Name

CS 1

Identifier

A

Result

Coding System Name

CS A

Identifier

1

Example Message (OK)

Coding System Name

CS 2

Identifier

A

Result

Coding System Name

CS A

Identifier

2