9 Enterprise Terminology Server (ETS)

Verify Different Terminology Versions Using Change Files

Change files are used to document the differences between successive versions of a terminology that are loaded into ETS, in a format that is acceptable for loading purposes. Change files are loaded at the same time as the terminology version data using the same loader and importer. Change files contain the following types of information:

• Reassignment: The meaning of one concept is occasionally reassigned to another concept represented by a different concept code. Following are some of the situations in which reassignment occurs:

  • Duplicate concepts are detected. One of them is elected to continue representing the meaning while the other is retired or deleted and reassigned to the retained concept.

  • A concept is detected to be erroneous. The erroneous concept is retired or deleted and reassigned to a correct concept.

  • The classification of a concept is changed. If the concept codes are hierarchical (as in ICD-9-CM), the change in classification translates to a change in concept code, necessitating reassignment.

  • A reassignment is indicated in a change file by a row containing an entry of type S (semantic reassignment), followed by a source concept code (the concept whose meaning is being reassigned to another code), and a target concept code (the concept whose code now captures the meaning).

  See Also

  /ets/hdr-ets-1.0.0-SNAPSHOT/db/execute/readme/Change_File_Formats_General.txt from hdr-1.0.0-SNAPSHOT.zip for more information about the format of the change file.

  If both the source and target concepts of a reassignment are from the new version, the reassignment is said to be intra-version. For example, in SNOMED-CT, if a duplicate or erroneous concept is detected, the new version carries forward the duplicate or erroneous concept in an inactive status. The reassignment in this case is from the inactive concept in the new version to an active concept in the new version.

  If the source of a reassignment is from the previous version and the target is from the new version, the reassignment is said to be inter-version. For example, in ICD-9-CM, if an erroneous concept is detected, it is deleted and excluded from the new version. A correct concept is provided in the new version and a reassignment is created between the concepts in the previous version and the new version. To process an inter-version reassignment contained in a change file, the ETS importer looks for the source code in the non-quarantined version (of the terminology in question) that has the latest load date. The non-quarantined version can be either active or retired.

• Reuse: Occasionally, a concept code used in the previous version is reused to represent a concept with a different meaning in the new version. Note that this is considered bad terminology practice and should only be used to account for inadvertent errors. Unless a reuse is explicitly called out in the change file, a concept in the previous version is always considered equivalent to a concept with the same concept code in the new version.

Change files are preseeded for the following terminologies:

• HL7

• HDR Supplemental

For each of the following terminologies, new versions and their change files are available to customers, possessing licenses, from the vendor of the terminology:

• IETF RFC 1766

• ISO 3166-1 alpha2

• NUBC-UB92

• CPT-4

• FDB

• HCPCS-2

• ICD-10

• ICD-9-CM-DRG

• ICD-9-CM-MDC

• ICD-9-CM-V1

• ICD-9-CM-V3

• LOINC

• SNOMED-CT

For all other terminologies that are loaded into ETS, change files must be created separately and loaded for each new version.

Note that change files must be loaded concurrently with the new version of a terminology. It is not possible to load a change file for a version of a terminology after both versions have been loaded.

Note also that a change file can only equivalence concepts between two consecutively imported versions of a terminology. Hence the order in which versions are imported is significant if change files are being used. The following scenarios illustrate this constraint:

• A concept (concept code X) exists in version 1 of a coding scheme. The concept neither appears in version 2 nor is reassigned to an equivalent version 2 concept. A concept with code X reappears in version 3 with the same meaning as in version 1. It is not possible to indicate to ETS that concept X from version 1 is equivalent to concept X from version 3-because it spans a version.

• A concept (concept code X) exists in version 1 of a coding scheme. The concept neither appears in version 2 nor is reassigned to an equivalent version 2 concept. In version 3, another concept (concept code Y) is created that is equivalent to concept X from version 1. It is not possible to indicate to ETS that concept X from version 1 is equivalent to concept Y from version 3.

  Note: To support concept equivalence, the ETS importer does not import a second quarantined version of a terminology if one already exists. This facilitates verification of equivalence between the quarantined version and the previous version of the terminology before the quarantined version is published.

Preparing Terminology Content and Control Files

To create the terminology files and move them into the correct folder, perform the following steps:

Steps

1. If the terminology is a generic terminology, create the terminology files in the format expected by the ETS generic loader. Otherwise, ensure that the files are in the format expected by the appropriate terminology loader. (If the terminology is supported by Apelon, this step is not required.)

   See Also

   • /ets/hdr-ets-1.0.0-SNAPSHOT/db/execute/readme from hdr-1.0.0-SNAPSHOT.zip, for details regarding file formats required by ETS terminology loaders.

   • /ets/hdr-ets-1.0.0-SNAPSHOT/db/execute/readme/Change_File_Formats_General.txt from hdr-1.0.0-SNAPSHOT.zip, for details about change files.

   Note:

   • To load equivalence information for the terminology version being loaded, the change file must be specified while loading the version-ETS does not support retrospective loading of change information.

   • For equivalence processing to be performed correctly, versions must be loaded in order. Equivalence processing assumes that the codes referenced in the change file are from the version currently being loaded and its immediate predecessor.

2. Move the terminology files to a directory in the same file system as the Applications instance-a directory that is accessible by the Oracle Database Scheduler (DBMS_SCHEDULER).

3. Create a control file that reflects the locations of the terminology files and move it to a directory in the same file system as the Applications instance-a directory that is accessible by the Oracle Database Scheduler (DBMS_SCHEDULER).

Creating New Generic Coding Schemes

ETS lets users define and implement custom terminologies for specific needs. Custom terminologies must be based on the generic ETS terminology model. Coding schemes that implement the generic terminology model are known as generic coding schemes.

See also:Coding Scheme

Loading a Coding Scheme Version

To load a new coding scheme version, use the Oracle Database Scheduler (DBMS_SCHEDULER).

See Also:

/ets/hdr-ets-1.0.0-SNAPSHOT/db/execute/readme from hdr-1.0.0-SNAPSHOT.zip, for information about control files.

Using Oracle Database Scheduler (DBMS_SCHEDULER)

Select the HDR Loader Job, and enter values for the Control File (absolute path), Coding Scheme Name, and Coding Scheme Version Name parameters.

Publishing a Coding Scheme Version

A loaded terminology is staged for importation into ETS. Use HDR Importer Job directly for publishing a coding scheme version.

The published coding scheme version is in the quarantined state by default. The coding scheme version must be activated before it can be used.

Note: In order to support concept equivalence, the HDR Importer job process does not publish a second quarantined version of a coding scheme if one already exists. This facilitates verification of equivalence between the quarantined version and the previous version of the terminology before the quarantined version is published.

Using Oracle Database Scheduler (DBMS_SCHEDULER)

For publishing a staged coding scheme version, select the HDR Importer job, and enter values for the Load Sequence Number and Dry Run Mode parameters. You can get the Load Sequence Number from the log file of the HDR Loader job that has successfully loaded the data (coding scheme versions, classifications, and cross maps).

See Also:

• Oracle Applications System Administrator's Guide

Note: In order to support concept equivalence, the HDR Importer job does not publish a second quarantined version of a terminology if one already exists. This facilitates verification of equivalence between the quarantined version and the previous version of the terminology before the quarantined version is published.

See Also:

/ets/hdr-ets-1.0.0-SNAPSHOT/db/execute/readme, for details regarding file formats for ETS terminologies and loaders.

Activating a New Terminology Version

A quarantined coding scheme version must be activated before it can be used. A quarantined version can be activated only ETS API.

Interterminology Mapping Using Cross Maps

Interterminology mapping provide a mechanism by which concepts from a source version in one terminology can be mapped to concepts from a target version in another terminology. Mappings are typically tailored for a specific application. For example, a data-aggregating or reporting application may require a mapping between specialized SNOMED-CT codes and coarse ICD-9-CM codes. A data retrieval application may use mappings with the opposite semantics (from less granular classifier codes to more detailed codes). These examples serve to illustrate that mappings serve multiple purposes, and not all cross maps indicate equivalence. Those cross maps that truly do indicate equivalence must be explicitly flagged by the author of the cross maps. This section describes the steps you should follow to indicate equivalence between concepts from two different terminologies using interterminology mapping files.

See Also:

The Implementation Guide for a detailed procedure on how to define interterminology mapping using cross maps and how to load the map set files.

Guidelines: Cross Maps

The ETS Cross mapping model is based on the SNOMED CT cross mapping model. Cross-mapping mechanisms provide support for the following:

• Mapping a single concept to a target code (a one-to-one mapping).

• Mapping to a set of Target codes (a one-to-many mapping).

The current structure does not support:

• Mapping a set of Concepts to a Target.

The relationship between these tables is shown by the following chart:

Figure 9-1 ETS Cross Mapping Relationship

A map set defines a mapping between two coding scheme versions, such as Terminology A version 2003 and Terminology B version 2.01. Each map set is composed of multiple cross maps. Each cross map consists of a source concept and one or more target concepts, such as a source concept from Terminology A and one or more target concepts from Terminology B—to which it maps.

ETS Concept Lists

An ETS concept list is a container for ETS concepts; each concept is associated with a membership code that is distinct within that list. This container abstraction has many practical applications within HDR and for customers interacting with ETS directly. A concept list is useful for presenting a commonly used list of values to a user, such as a list of valid lab tests, a list of commonly prescribed pain medications, or a list of surgical procedures. The concepts inside a concept list can be derived from any ETS coding scheme version. This permits the construction of a concept list to represent Concepts that represent Influenza, for example, containing one concept from each relevant terminology loaded into ETS.

ETS supports a number of advanced concept list features such as concept list groups, access restrictions (extensibility), and parent-child relationships between lists including inheritance options, specialization of lists, and integration with concept equivalence. Concept list objects can be specialized by implementing usage contexts linking a specialized child concept list to its parent concept list . Concept list objects have activation and retirement dates for the membership of their concept members, stored as a time stamp rounded to the nearest second.

Concept list objects have access restrictions, which are stored as extensibility values. Third-party developers do not have access to set the extensibility of a concept list. Concept list objects can be defined as system, extensible, and user. System-defined concept list objects are created and seeded with each HDR release. Customers cannot add, remove, or update concept list objects within this list. User-defined concept objects are created by customers and permit the addition and modification of concept objects. Extensible concept list objects are delivered with HDR, but let customers add concept objects into the list.

Parent-child concept list relationships are implemented in ETS. The child concept list can be restricted. Restricted concept list objects can only add concept objects or have concept objects that are already included in their parent concept list objects. Child concept list objects can also inherit additions or deletions of concept objects from their parent concept lists.

Figure 9-2 illustrates the inheritance behavior of restricted members.

Figure 9-2 Inheritance of Activation/Retirement Dates

Adding Concepts to a Concept List

Note:

A concept cannot be added under the following conditions: the concept is already active or pending in the selected list; the selected list is the parent of an additive child specialization and the concept is already active or pending on the child; the selected list is a SYSTEM list; or the selected list is a restricted child specialization and the concept is not active or pending on the parent lists.

If any (but not all) concepts chosen for addition are not addable, a warning diagnostic lists the concepts that will not be added. You can elect to continue or return to list selection.

If all concepts selected for addition are not addable, the List Selection window is reloaded with an information box listing these concepts. To continue, select another list.

If any of these conditions exist, select a new membership code or activation date as appropriate, and click Next. You can alternatively click Back to return to the List Selection page, or click Cancel to exit the addition process.

Note: If the concept is being added to a restricted specialization, and the selected activation date would cause the concept's active period to exceed that of the corresponding concept in the parent list, an exception occurs; a dialog warns you that the concept has not been added.

See Also:

Oracle Healthcare Data Repository Javadoc

Caution: We strongly recommend that wherever possible, you only add concepts from the same terminology to a single concept list. Concept meanings can be sensitive to the context in which they are included in a terminology; mixing them with concepts from other terminologies may distort those meanings.

ETS Editable Terminologies

Editable terminologies let developers add contents to a coding scheme identified as editable. After creating an editable coding scheme, you can add concepts, descriptions and relationships to a version of this coding scheme. An editable coding scheme can have only one version.

Editable Coding Scheme

Using the HDR API, you can create an editable coding scheme by creating a new generic coding scheme with the editable attribute set to true. After the coding scheme is created, you can edit the original version, but a new version is not permitted.

Editable Terminology

An initial version of the editable coding scheme must be created and loaded before it is used. Use the generic terminology loader to load an editable coding scheme version.

Editable Coding Scheme

Editing concepts, descriptions, and relationships is limited to addition and removal of attributes, changing status, and changing a description's preferred status. Other changes are made by retiring a component and adding a new component in its place. For example, a description's text cannot be changed, but the description can be retired and a new description added to replace it. The new description can optionally be designated preferred.

Equivalence

As an editable terminology has only a single version, equivalence in an editable terminology must be intraversion – in other words, equivalence may only be declared between concepts in the same version. In the initial version load, equivalence may be declared using a change file, just as for any terminology being loaded with intraversion equivalence information. After the initial load, reassignments (introduction of a new concept that has the same meaning as an existing concept but has a different concept code than the existing concept) may be declared when a new concept is added. The new concept's code may be declared, using the relevant API, to be a reassignment from an existing concept's code.

No reuse of codes (introduction of a concept whose concept code is the same as an existing code, but where the concept has a different meaning than the existing code represents) is permitted in an editable terminology.

See Also:

• Implementing Interterminology and Intraterminology Equivalence

• Implementing Interterminology Mapping Using Cross Maps

etsAdministrationService.createCodingScheme
(codingSchemeName, codingSchemeDescription,CodingScheme.CODINGSCHEME_MODEL_GENERIC, oid , true);

CodingSchemeVersion csv = etsAuthoringService.createCodingSchemeVersion(codingSchemeVersionName,
codingSchemeVersionDescription , codingScheme);etsAdmin.makeDefaultVersion(csv);

CandidateConcept[] candConcepts = new CandidateConcept[1];
candConcepts[0] = etsAuthoringService.newCandidateConcept();
CandidateConceptDescription[] candDescs = new CandidateConceptDescription[1];
 
candDescs[0] = etsAuthoringService.newCandidateConceptDescription();
candDescs[0].setStatusCode('A');
candDescs[0].setTermText(conceptDescription  );
candDescs[0].setPreferredDescription(true);
candConcepts[0].setCandidateDescriptions(candDescs);
 
 
candConcepts[0].setConceptCode(conceptCode);
candConcepts[0].setStatusCode('A');
candConcepts[0].setRelationshipType(relationshipType);
 
etsAuthoringService.addConcepts(csv, candConcepts, false);

String sourceConceptId = csv.getConceptByConceptCode(conceptCode).getETSID();
    
Concept targetConcept = csv.getConceptByConceptCode("TargetConcept");
String targetConceptId = targetConcept.getETSID();
 
Concept relationshipConcept = csv.getConceptByConceptCode( "IS_A");
String relationshipConceptId = relationshipConcept.getETSID();
 
CandidateRelationship[] candRelation = new CandidateRelationship[1];
candRelation[0] = etsAuthoringService.newCandidateRelationship();
 
candRelation[0].setSourceConceptID(sourceConceptId);
candRelation[0].setTargetConceptID(targetConceptId);
candRelation[0].setRelationshipTypeConceptID(relationshipConceptId);
candRelation[0].setStatusCode('A');
 
etsAuthoringService.addRelationships(csv, candRelation, false);

ETS Classifications

ETS Classifications are containers for grouping existing ETS concepts from different coding scheme and versions. Classifications are intended for large categorizations of concepts, while concept lists are intended for smaller sets for the purposes of validation or display. ETS Classifications provide the following features:

• Classifications describe a set of concepts that are all part of the same category. For example, the classification Antibiotics might include concepts for penicillin and telithromycin, among others.

• Classifications can be arranged in a hierarchy.

• Tests for containment in a classification search down the levels of the hierarchy.

• Classifications can be created and populated through an API or through creating and loading text files.

• Classification contents incorporate equivalence.

• Concepts added to an ETS Classification retain their equivalence information and characteristics.

• ETS Classifications are themselves ETS Concepts--components of a special, predefined editable terminology called ETSClassifications. Accordingly the following applies:

  • A classification has a concept identifier.

  • A classification can have multiple descriptions, including local descriptions.

  • A classification's local descriptions can be associated with usage contexts.

• ETS Classifications can be defined using the API or using the HDR Loader job and HDR Importer job.

• Classification contents are created with declarations that can leverage ontological relationships already present in many terminologies.

• All members of a classification implicitly include their semantic equivalents.

• Classifications are computed asynchronously by a new feature of the HDR Maintenance Job, supporting fast runtime response to classification queries.

Every classification created is backed by an ETS concept, and inherits all functionality that ETS concepts provide. Classification concepts are created on demand in a special coding scheme.

The following table summarizes the principal interfaces referenced by this section:

Large amounts of healthcare data are difficult to use unless they are well organized. Creating classifications is the most common means of organizing healthcare data. As institutions generally use a combination of (standard and local) terminologies, classifications need to incorporate concepts from different coding schemes and versions.

ETS Classifications provide a mechanism for grouping concepts from different coding schemes and versions, and arranging the groups in hierarchies navigable by the ETS API. ETS Classifications facilitate:

• Viewing a large number of concepts

• Selection of concepts

• Class-based query of information

For example, a classification called cardiovascular diseases could be created and populated with concepts that represent different cardiovascular diseases from different terminologies. The following chart shows this classification:

Figure 9-3 Simple ETS Classification

Description of ''Figure 9-3 Simple ETS Classification''

ETS Classifications are internally represented as concepts in an editable generic coding scheme called ETSClassification. In this example, the classification, cardiovascular diseases is stored as a concept in the coding scheme ETSClassification.

But you could also create another classification such as heart diseases and make it a child classification of the cardiovascular diseases classification. Thereafter, any concept in the heart diseases classification, such as congestive heart failure, would be considered by the Classifications interface to be implicitly contained in the cardiovascular diseases classification.

Figure 9-4 Parent and Child ETS Classification

ETS Classifications are basically containers of ETS concepts. In this chart, the concepts in each classification node could derive from different coding schemes.

ETS classification interfaces are oblivious to relationships between the classification concepts in their native terminologies. For example, in this chart, congestive heart failure and congenital cardiac failure are children of heart failure in their native terminology, but the heart disease ETS Classification views its contents as a flat list of concepts. There is no classification interface that is aware of relationships between the classification concepts in their native terminologies. However, those relationships can be navigated by querying the individual concepts, using the ETS generic terminology interface or a terminology-specific interface.

Classifications are themselves ETS Concepts – components of a special, pre-defined editable terminology called ETSClassifications. Creating a new classification actually is creating a new concept in the ETSClassifications terminology. Since classifications are concepts:

• A classification may have multiple descriptions, one of which is designated preferred

• Local descriptions may be associated with usage contexts

• A classification has an ETS ID

ETS Equivalence

ETS manages changes to terminology data over time by maintaining complete copies of each version of a terminology. ETS equivalence provides a mechanism to determine all of the instances of concepts that have the same semantic meaning, both within the history of a coding scheme and across coding schemes.

Equivalence may be Intra-terminology or Inter-terminology. Intra-terminology equivalence is defined between concepts from the same terminology. For example, the concept Cholera is represented in ICD-9-CM 2002 and in ICD-9-CM 2003 by the same concept code [001_CHOLERA]. Because both concepts have the same meaning, they can be treated as equivalents---ETS treats them as equivalent by default, as they belong to the same coding scheme and have the same concept code.

ETS allows concepts from two different terminologies to be defined as semantic equivalents. Equivalence between concepts from different terminologies, or Inter-terminology equivalence, is defined using cross maps. For example, the concept for the disease Cholera in the ICD-9-CM terminology (2002 version), and the concept representing the same disease in the SNOMED-CT terminology (2002 version), can be defined as equivalents using a cross map.

The information used to determine equivalence is provided by terminology vendors, either as an integral part of the terminology data, or as a separate change file. There are two types of equivalences in ETS:

• Intra-terminology equivalence captures exact, unambiguous equivalence between concepts in the same terminology. Declaring two concepts semantically equivalent indicates that their meaning is identical.

• Inter-terminology equivalence uses mappings to capture explicit equivalence between concepts from different terminologies.

Combining Intraterminology and Interterminology Equivalence

Equivalence between concepts is a transitive relationship. In the following chart, if Concept A1 is equivalent to Concept A2, and Concept A2 is equivalent to Concept A3, it can be inferred that Concept A1 is equivalent to Concept A3. Consistent with this logic, Concept Equivalence services in ETS can determine if concepts from two terminologies are equivalent—provided that an inter terminology mapping exists between versions of the two terminologies, and, change files have been loaded for all versions.

Concept Equivalence Model

In this chart, ETS transitively combines intraterminology equivalence and interterminology equivalence information to infer that Concept A1 is equivalent to Concept B1.

Example 9-5 Using ETS Equivalence

import java.util.Properties; 
import oracle.hsgbu.ets.base.*; 
import oracle.hsgbu.ets.authoring.*; 
import oracle.hsgbu.ets.fwk.servicelocator.common; 
 
public class ProgrammerGuideTest2 { 
  
public static void main(String argv[]) throws Exception { 
 /* Add a concept with concept code "REPC_TE000005" into a concept list,  
 which has a name of "CL_TEL_USE" and belongs to a group "HTB_RIM". 
 The steps will be:
 
 1. find the concept and the concept list in the system; 
 2. check to see if the concept (and its equivalent concept) is already in the concept list; 
 3. if not, add the concept into the concept list.*/ 
 
addConceptToConceptList("REPC_TE000005","CL_TEL_USE","HTB_RIM"); 
 } 
 
public static void addConceptToConceptList(String conceptCode,String
conceptListName, String groupName) throws Exception{  
 
  Properties props = new Properties(); 
  props.setProperty(ServiceLocator.CLIENT_MODE,
   ServiceLocator.REMOTE); //Specify Client mode: Local or Remote 
  ServiceLocator slocator = ServiceLocator.getInstance(props); 
  slocator.login("sysadmin","sysadmin"); 
  ETSService ets = slocator.getEtsService();
  //get the ETSService through ServiceLocator 
  ETSAdministrationService etsAdmin =
  ets.getAdministrationServiceInstance();
  //get the getAdministrationService 
  //1. find the CodingScheme and its default version by calling 
   ets.getCodingScheme(String) and cs.getDefaultVersion();
 
  // if using this example code in your own code, replace "My Terminology" 
   with the terminology name in which you are interested 
  CodingSchemeVersion csv = ets.getCodingScheme("My Terminology").getDefaultVersion(); 
 
  //2. find the concept by calling csv.getConceptByConceptCode(String) 
   Concept con = csv.getConceptByConceptCode(conceptCode); 
 
  //3.find the concept list by calling ets.getConceptList(String, String) 
   ConceptList cl = ets.getConceptList(conceptListName, groupName); 
 
  //4. validation: check to see if the concept list contains this concept 
   by calling cl.contains(Concept,int) 
 
  //5. if not, add the concept to the concept list by calling 
   etsAdmin.addConceptToConceptList(Concept,String,ConceptList) 
   if (!cl.contains(con,Concept.EQUIVALENCE_TYPE_MAPPING)) 
    { 
    etsAdmin.addConceptToConceptList(con,conceptCode,cl);
    // here we use the concept code as the membership code, but you may use 
     something else 
    } 
  } 
} 

Note: ETS does not support authoring of equivalence information. Equivalence must be provided to ETS in one of the specified ETS file formats.

Intra-terminology equivalence information is provided to ETS as a ”change file”, when loading a new version of a terminology. Change files identify reuse of codes (codes that represent different meanings than the previous version), and reassignment of codes (meanings that are now represented with different codes).

Note:

ETS does not support the authoring of change files.

HDR Terminology Jobs

ETS includes a set of DB SCHEDULER jobs that let you load and import terminology data files, perform routine database maintenance, and delete unwanted map sets. You can run these jobs through the scripts provided.

• Loader: Running the HDR Loader Job is the first step in the process of populating terminology data into the ETS active repository. The loader job is used to load terminology data from flat, textual files into terminology staging tables. The loader interprets or converts data from its native format into a format that aligns with the internal ETS representations, and it also validates the format of the files being loaded.

• Importer: The HDR Importer Job takes data from a set of stage tables (populated by the loader), runs a series of validation checks on it, and publishes it to the ETS active tables.

• Maintenance: The HDR Maintenance Job cleanses data from the stage and active tables, gathers statistics for the stage and active tables, rebuilds intermedia indexes, and builds classifications.

ETS Multiple Language Support (MLS)

• Understanding Language (Locale) Mappings

• Locale Enabled APIs

ETS lets concepts to be described in any language. ETS languages are derived by appending the ISO Language code (in UPPER case) to the ISO Territory code (in UPPER case). The territory represents either a geographic region or a language dialect. For example, ENGB represents the English language used in Great Britain.

You can use one of the following methods to create a description in a different language than the base language:

• Use the HDR Loader Job

• Create local descriptions

This is achieved by locale enabling a subset of APIs. These locale enabled APIs permit retrieval of concepts and creation of descriptions in specific locales. The non-locale enabled APIs return descriptions in the base language. However, you can only create editable terminologies in the base language.

Mappings exist for every coding scheme version, ISO Language code and ISO Territory code. This resolves situations where a description does not exist for the installed language. For example, if Simplified Chinese is mapped to American English, American English descriptions are returned when requesting descriptions in Simplified Chinese. Local descriptions are an exception to this rule. Simplified Chinese local descriptions are returned when requesting descriptions in Simplified Chinese.

• Terminology-specified concept descriptions of non-editable terminologies.

• Locally-specified concept descriptions of terminologies (editable and non-editable) and Classifications.

MLS in ETS lets you load Coding Scheme versions with Concept descriptions in multiple languages. Each Coding Scheme version can support Concept descriptions in multiple languages, but every Concept in a Coding Scheme version must be supplied with a terminology-preferred description in the languages supported by that version.

You can create local descriptions in multiple languages. Concept descriptions (both terminology-specified and local) based on a language can be obtained by calling methods that accept a language.

Creating Local Descriptions

You can specify local descriptions for any ETS concept. These descriptions can be used in place of terminology-specified descriptions for display purposes. You can assign a single usage context to each local description.

The usage context for each local description must be unique; no two local concept descriptions share the same usage context.

Note: Local descriptions of a concept can be created for any language, not just for languages loaded with the coding scheme version.

Use ETS API to create local description. You can create local descriptions for retired or active concepts, but the typical procedure is to create a description for concepts in the active default version of the terminology.

Note:

• The terminology-specified Concept descriptions of editable terminologies and Classifications are created in the base language of the HDR installation.

• ETS will not translate terminology content - whether seeded or loaded.

• ETS does not perform any validation to ascertain whether a description is actually in the language that it claims to be in. You can load pseudo translated text as concept descriptions for a supported language along with the real description text. For example, you can load the data given in the following table as Concept descriptions into ETS without getting any errors:

Understanding Language (Locale) Mappings

Mappings let ETS return descriptions even though the terminology may not contain descriptions in the requested language. For example, the mappings can be set up so that if British English descriptions are requested, American English descriptions are returned. Every coding scheme version has a set of mappings that let the system determine which language to return.

Mappings can be created through one of the following mechanisms:

• By migration (upgrading from a prior version).

• By the HDR Loader Job.

• By using the HDR Maintenance Job.

You can use the HDR Maintenance Job to create missing mappings. For example, you can run the maintenance program after installing a language to create mappings from the new language to the base language.

Locale Enabled APIs

• getLocale

• findConcepts

• createLocalConceptDescription

• getDescription

• getLocallyPreferredDescription

• getTerminologyPreferredDescription

• getAllDescriptions

A code sample below can help you to:

• Use a Locale-Enabled API

Mixing calls to Locale enabled and non-Locale enabled APIs is not recommended. For example, calling getLocallyPreferredDescription() without a Locale and then calling it with a Locale.

There are two constructors for a java.util.Locale: one that accepts a language code and a country code, and one that also accepts a variant code. Locale variants are not supported by ETS; parameter constructor 3 should never be used to construct a parameter for the ETS API. Both the ISO 639 language code and the ISO 3166 country code are mandatory for a java.util.Locale that is passed to ETS. For example, it is valid to pass new Locale("en", "US") for American English or Locale("en", "GB") for British English, but not Locale("en", null) or Locale("en", "")

ServiceLocator slocator = ...;
  ETSService etsService = slocator.getEtsService();
  Locale locale = new Locale("en","US");
    
  String codingSchemeName = "A Terminology";
  CodingScheme codingScheme = etsService.getCodingScheme(codingSchemeName);
  CodingSchemeVersion csv = codingScheme.getDefaultVersion();
  String conceptCode = "A Concept Code";
  Concept concept = csv.getConceptByConceptCode(conceptCode);
 
  // get descriptions in the locale of the current session
  ConceptDescription[] descriptions = concept.getAllDescriptions(locale);
 
  System.out.println("Description of conceptCode: " + conceptCode + " is " + descriptions[0].getTerm());