Introduction to the Lexicon Server

The management of the Lexicon Server, as well as a much more in depth look at the idea of terminologies can be found in the documentation to the Lexicon Manager. For the purposes of this tutorial, we only need a rough idea.

The Lexicon Manager is a facility to store and define terminologies, terms and their representations. It enables re-use of data, and enables a receiving system to understand the meaning of data from a foreign system. In other words, it allows the receiving system to understand the data sent to it by the foreign system. It acts as a translator between the terminologies used in the two systems.

An Example

Suppose a HL7 message is sent containing a reference to Sodium. Unfortunately, as there is no standard way to express information like this, the foreign and receiving systems both have different expressions for Sodium. The foreign system had encoded it in the message as Na, but the receiving system expects the code to be 2947-0. Although a translation script like the one written in Tutorial 5 would work, the Lexicon Server provides a much simpler and elegant solution, allowing you greatly simplify the replacement of the variable using the provided functions.

Importing the Terminology

To perform these translations, we have provided a premade terminology here. Save the file somewhere. Access the Lexicon Manager (HL7Connect | Lexicon). Make sure your options (accessed from the login box) are set correctly (ie in most cases like below), and login using your HL7Connect username and password.

Lexicon Options Screen

First we need to create some terminologies to import our terms into. Click Add new terminology and fill out the screen similar to that given.

LOINC Terminology

Now, create another terminology with the Name of SYSTEMA and a Namespace of urn://www.hl7connect.com/SysCodes. Do not click OK however, as we must modify the SYSTEMA terminology more in order for it to allow our translations. Go to the Attributes tab and create a new attribute with the same values as the following window:

SYSTEMA Attribute

This equivalency will allow us to translate terms between these two terminologies. Accept the changes to go back to the Lexicon Manager screen.

Now, select Import Terminology and choose "Import from a data file.". Browse to the saved file and accept. Select the terminology LOINC to import the terminology into and click Next. Select tblloincmap, and in the next stage set the mapping of values like so:

ID   LOINCode
Name   LOINCode
Preferred Code   LOINCode
Admitted Code   N/A
Definition   Description

Select to match the terms By ID and finish importing the terms.

Import the same file the same way for the SYSTEMA terminology, but this time alter the mapping to be like the following table:

ID   Testcode
Name   Testcode
Preferred Code   Testcode
Admitted Code   N/A
Definition   Description
LOINC translation   LOINCode

We now have a set of terminologies able to be used by the Lex functions. We are now able to start writing our translation script.

Performing the Conversion

In this case, we will not be translating Sodium, but a variety of different codes found in the terminology we've imported. The translatable codes, we will assume, will all be found in the first OBR-4 field as a String. This example javascript code will convert it into the CE required by the receiving system:

      rcodein  = aEvent.message.hl7.segment("OBR",0).Element("4").AsString;

      tcodekeyin = Lex.LexGetTermByCode("urn://www.hl7connect.com/SysCodes", rcodein);

      tcodekeyout = Lex.LexTranslate(tcodekeyin, "urn://www.hl7connect.com/LOINC", 0);
      tcodeout = Lex.LexGetTermRepresentation(tcodekeyout, "Code");
      tdescout = Lex.LexGetTermRepresentation(tcodekeyout, "Defn");

      aEvent.message.hl7.segment("OBR",i).element("4.1").AsString = tcodeout;
      aEvent.message.hl7.segment("OBR",i).element("4.2").AsString = tdescout;
      aEvent.message.hl7.segment("OBR",i).element("4.3").AsString = "HL7Connect";

The first line takes the fourth element of the first OBR segment, and assigns it (as a string) to rcodein.

Line 2 looks in the terminology urn://www.hl7connect.com/SysCodes for the code rcodein, and assigns the key for the given code in the terminology.

LexTranslate, on the third line, gets the translation for the codekey in the terminology urn://www.hl7connect.com/LOINC. If there is no translation, the default (in this case 0) is returned.

The next two lines simply get String representations of the type. The Code representation, in the example case, would be the numerical code 2947-0, while the Defn would be the more descriptive SODIUM.

The translation is inserted back into the message in the final three lines.


© Kestral Computing P/L 2000-2010.