ETS Object Model

The ETS base code consists of a core set of objects and services required for ETS to operate. The following sections provide a brief review of some of these core terminology objects:

Coding Scheme

A coding scheme is a representation of a single terminology across all of its versions. CPT-4, ICD-9, LOINC and SNOMED are examples of common coding schemes. Coding schemes can be created as needed by calling the createCodingScheme method in the ETSAdministrationService. Coding Schemes can be added into the repository but can never be removed.

Coding Scheme Version

A coding scheme version represents a single release of a coding scheme. A new coding scheme version is added every time a new release of a coding scheme is loaded into HDR. The 2004 release of CPT-4 and the v2.10 release of LOINC are examples of coding scheme versions. Coding scheme versions are created by running the HDR Terminology Jobs using a set of terminology files. Although coding scheme versions can never be removed from the system, they can be retired. The number of coding scheme versions in a system typically grows over time.

Concept

A concept is a single representation of an idea in a terminology and is associated with the coding scheme version that defines it. For example, a concept with concept code ACTN is included in version 2.01.4 of coding scheme ActClass. The number of concepts in a coding scheme version can range from less than a hundred to thousands. A concept is required to have a content-publisher defined concept code, which must be unique within a coding scheme version. A concept cannot be removed from a system, but its parent coding scheme version can be retired.

Concept Description

A concept description, sometimes also called a description, is a human-readable text description for a single concept. There are two types of concept descriptions: terminology-specified and locally-specified. A terminology-specified concept description is supplied by a terminology provider and populated by the ETS Loader/Importer. Terminology-specified concept descriptions are immutable once they are in the system and cannot be deleted. Every concept is required to have exactly one preferred terminology-specified description that can be used as the default when displaying a concept without any other contextual information. For example, concept ACTN in version 2.01.4 of coding scheme ActClass has the terminology-specified description action. In contrast, locally-specified descriptions are supplied by an organization using ETS. A locally-specified concept description can be associated with a UsageContext to aid the application by providing a contextually-appropriate description of a concept.

Relationship

A relationship is a connection that ties concepts together into graphs representing ontological information. Relationships can be used to represent hierarchies, classifications, or arbitrarily connected graphs within terminologies. Relationships are built as a combination of three concepts: a source concept, a relationship type concept, and a target concept. BACTERIAL PNEUMONIA (source), IS TREATED_BY (relationship type), ANTIBIOTIC (target) is an example of a typical relationship.

Some coding schemes, such as SNOMED-CT, contain explicit relationship information. Others have implicit relationships, which can be derived from other fields. In ICD-9, for example, a hierarchical relationship is implicitly defined by the ICD-9 concept codes. In another example, Concept 710.x, is automatically known as a child of concept 710.

Usage Context

A usage context is a mechanism that lets customers define an application specific context for descriptions and customized child concept lists. Concepts provide a method for getting a description based on a usage context; concept lists have a method, getChildConceptList(UsageContext), to get the child concept list based on the usage context. The number of usage contexts in a typical system is expected to be small (less than 50).

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 8-2 Inheritance of Activation/Retirement Dates

Creating and Updating a Concept List

Use ETS API to create a concept list. For more information on Concept Lists API, refer to the Oracle Healthcare Data Repository Javadoc.

Adding Concepts to a Concept List

Concepts can be added to extensible concept lists. Concepts to be added to a concept list must be contained in a coding scheme version that has already been loaded into ETS. Determine if the concept exists in ETS and the coding scheme version in which it is contained.

Perform the steps described in this section to add concepts to a concept list.

Caution:

Certain extensible concept lists are empty and must be populated with concepts before using their respective functionality.

Adding Concepts to a Concept List

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.

Specializing a Concept List

Concept lists can be specialized. A specialization of a concept list is a child concept list that initially inherits the active members of the parent list. It is a separate concept list, distinct from the parent list. Subsequent behavior of the specialization (a child concept list) with respect to the parent concept list depends upon the setting of its inheritance type:

Addition Inheritance: Any concept added to the parent list is added to the child list.
Deletion Inheritance: Any concept retired from the parent list is retired from the child list.
Restricted Inheritance: A child list cannot contain any concept not contained in its parent list; before a concept is added to the child list it must first either exist in the parent list or be added to the parent list. A concept in a restricted child list also inherits certain changes to the activation and retirement dates of the corresponding concept in the parent list.

The inheritance types are not mutually exclusive. A restrictive list must also exhibit deletion inheritance. You can update a list's addition inheritance and deletion inheritance by turning them on or off, but you cannot update its restricted inheritance.

A specialization can be associated with a usage context, as can a concept local description. A usage context can in turn be associated with an organization. Accordingly, a concept list can have multiple specializations, each associated with a particular organization.

A concept list specialization is created in the same manner as any other concept list (Steps).

Values in a concept list specialization can be added or retired as for any concept list.

Subsetting a Concept List

It may be desirable to subset a concept list—using only a subset of a concept list's members, for UI display purposes, or for validating data to be stored by an application. The following sections describe how to subset a concept list:

Subsetting a User Concept List

A concept list of extensibility type User can be subsetted by retiring unwanted members from the list. A member is retired by updating its retirement date and time.

Note:

This subsetting procedure does not apply to System or System extensible concept lists.

Subsetting a Concept List of any Extensibility Type

A concept list of any extensibility type (including user) can be subsetted using either of two additional procedures. These procedures are especially useful if the list to be subsetted is a System or System Extensible list, from which members cannot be retired (two methods):

Method 1: Using the Core Member Setting of List Members

The core set of members in the list can then be retrieved using the method:

getCoreSet

Checks of individual members of the list can be performed using the method:

isCoreMember

Method 2: Using a Specialization of the Concept List and Retiring Members

Reference

Oracle Healthcare Data Repository Javadoc

Table 8-1 Service and Methods: Specializing Concept Lists

Level	Detail
Package	oracle.hsgbu.ets.base
Class	ConceptList
Methods	getChildConceptList

To subset a concept list of any extensibility type using Procedure-2, do the following:

Create a specialization of the concept list, and specify a usage context for the child list. You can then subset the child concept list, and you can use the subsetted list as required by your application.

Access the specialization using the method:

getChildconceptList

See also:

HDR Concept Lists Index for further information about HDR supported concept lists.
HDR ConceptList Interface for further information about the ConceptList_Class.

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

Reference

Oracle Healthcare Data Repository API Documentation

The following table provided information about the ETSAuthoringService interface used to implement editable terminologies:

Oracle Healthcare Data Repository Javadoc

Table 8-2 Service and Methods: Editable Terminologies

Level	Detail
Package	oracle.hsgbu.ets.authoring
Interface	ETSAuthoringService
Methods	addAttributes addConcepts addConceptDescriptions addRelationships changeStatus removeAttributes

Refer to the following sections to edit the components of an Editable Coding Scheme:

Adding Components
Changing Component Status
Adding and Removing Component Attributes

Note:

These changes are exclusive; any other changes to concepts, descriptions, and relationships can only be made by retiring the component and adding a new one.

Adding Components

Use the addConcepts, addConceptDescriptions, and addRelationships methods to add concepts, descriptions, relationships and attributes to an editable coding scheme. Candidate components are created first and passed to the add methods.

Changing Component Status

Components such as concepts, relationships and descriptions of an editable coding scheme cannot be edited or removed directly. To modify a component, it must be retired and replaced. A component can be retired or made active by changing the status flag associated with the component. Use the changeStatus method to change component status.

Adding and Removing Attributes

Use the addAttributes and removeAttributes methods to add and remove attributes, respectively.

The code samples below help you to:

Create an Editable Coding Schema (see Example 8-1)
Create a Coding Scheme Version and making it the Default (see Example 8-2)
Create a Concept (see Example 8-3)
Create a Relationship between Two Concepts (see Example 8-4)

Note:

The RelationshipTypecode of the IS_A concept used in Example 9-4 should be set to CandidateConcept.REL._TYPE_YES.

Example 8-1 Create an Editable Coding Scheme

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

Example 8-2 Create a Coding Scheme Version and Making it the Default

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

Example 8-3 Create a Concept

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);

Example 8-4 Create a Relationship between Two Concepts

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);

See also:

Oracle Healthcare Data Repository API Documenation for more information about using ETS APIs.

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:

Table 8-3 Service and Methods: ETS Classifications

Level	Detail
Package	oracle.hsgbu.ets.base
Class	ETSAdministrationService
Methods	addConceptToConceptList addDeclarationToClassification createClassification createCodingScheme createConceptList removeDeclarationFromClassification
Class	ETSService
Methods	findClassificationByCode findcodingScheme findCodingSchemeVersion findConcept findConcepts isEquivalent
Class	Classification
Methods	contains findChildClassifications findConceptsInClassification

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 8-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 8-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

Classifications can be Linked Hierarchically

Classifications may be linked in strict or multiple hierarchies (a classification may have multiple parent classifications) to form a network of linked classifications forming an acyclic graph.

Testing Containment

ETS classifications support testing of containment across levels of a hierarchy. For example, given the hierarchy in the chart Sample ETS Classification, if the concept congestive heart failure is in the heart disease classification, and the heart disease classification is a child of the cardiovascular diseases classification, you can test if congestive heart failure is a cardiovascular disease, and the answer will be Yes.

Equivalence is incorporated into Classifications.

The concepts contained in an ETS Classification retain their equivalence information. For example, what is actually considered as included in cardiovascular diseases are groups of concepts that are equivalent to heart failure, congenital cardiac failure, congestive heart failure, and arterial anuerysm. Consequently, if concept X is equivalent to congestive heart failure, and the question “Does ‘cardiovascular diseases' contain X?" is asked, the answer will be “yes".

Creating and Populating Classifications

Classifications are created by generating a hierarchical network of classification nodes and populating those nodes with individual ETS concepts. An individual classification node may contain concepts from multiple terminologies.

A single concept can be used in multiple classifications, including multiple sub-classifications of the same parent classification, but it cannot appear more than once in the same sub-classification. However, equivalent concepts can be inserted into the same sub-classification. As for all ETS concepts, concepts in a classification can have multiple text representations.

Classifications may be created and populated by two methods:

Specifying classification data in files, and loading the files using HDR Terminology Jobs
Using ETS APIs directly

A new classification will have a pending state when it is created and loaded. It will become effective only when the HDR Maintenance job is run. Until then, the new classification will be unusable. This enables new classifications to be created and readied for use without requiring a downtime.

Whenever changes are made that could affect classification contents (declarations are added or removed, a version of a terminology that contains classification concepts is loaded, or a mapping involving a version that contains classification concepts is loaded), the classification moves from the active state to a dirty state. In this state the classification in its former active state is still usable. The effects of the changes that placed the classification into the dirty state will not be usable until the classification is moved from the dirty state to the active state. Classifications are moved from the dirty state to the active state by running the HDR Maintenance Job.

Note:

Classification contents are defined declaratively. This enables a short-cut for adding concepts declared a terminology to be children of another concept. For example, the concepts heart failure, congenital cardiac failure, and congestive heart failure could have been added to heart diseases by a single statement(add heart failure and its descendents to heart diseases). This adds heart failure and its children as defined within its native terminology. A declaration can also add a concept and only those concepts deemed to be direct children in its native terminology, add a concept's descendents but not the concept itself, or add a concept's direct children but not the concept itself. The various insertion choices are called insert options.

See also:

Oracle Healthcare Data Repository Javadoc
A declaration with an insert option of concept only adds a single concept ((the concept with none of its children). The contents of a classification amount to a series of declarations. Classification contents are augmented or reduced by adding or removing declarations.

To retrieve a concept's children when implementing a declaration, the ETS classification build process must know which relationships in the concept's native terminology represent parent-child relationships. Accordingly, for each core terminology, HDR has identified certain relationships as defining parent-child associations. The ETS classification build process queries for such relationships when called upon to find a concept's children. For generic terminologies, the build process queries for relationships in which the relationship type concept is identified as type IS_PARENT_OF or IS_CHILD_OF.

See also:

Documentation at the Apelon, Inc. web site for descriptions of the treatment of specific terminologies.
/ets/hdr-ets-1.0.0-SNAPSHOT/db/execute/readme /Terminology_File_Formats_Generic.txt from hdr-1.0.0-SNAPSHOT.zip

Note:

Each ETS concept defined in a generic terminology must be identified as being valid or invalid for use as a relationship type, and is indicated by the RELATIONSHIPTYPEFLAG column in the Concepts fie. This flag can contain one of the following values (Table):

Table 8-4 Concept File: RELATIONSHIPTYPEFLAG Legal Values

Value	Description
N	The concept cannot be used as a relationship type.
Y	The concept can be used as a relationship type.
IS_PARENT_OF	The concept can be used as a relationship type, and the type indicates that the source concept is the parent of the target.
IS_CHILD_OF	The concept can be used as a relationship type, and the type indicates that the source concept is the child of the target.

Those concepts designated as valid relationship types in the concepts file can subsequently be used in the relationships file in the RELATIONSHIPTYPECONCEPTCODE column.

Use the following HDR interfaces to define and use ETS classifications:

ETSAdministrationService
ETSService
Classification

Creating a Classification

To create and populate a classification via the loader, perform the following steps:

Steps

Create a Classifications file. This file lists the classifications to be created and their properties.
Create a Classifications descriptions file: This file lists the descriptions to be associated with the classifications and their properties. Just as multiple descriptions for a concept can be listed in a terminology descriptions file, multiple descriptions can be created for a classification.
Create a Classifications declarations file. This file lists the declarations (each declaration consisting of a concept and an insert option) that will be added to classifications. The classifications referenced in this file can be new classifications listed in the classifications file, or pre-existing classifications.

Note:
Declarations must be removed through an API call; they cannot be removed through the loader.
Create a control file specifying the Classifications, Classification Descriptions, and Classification Declarations files.
See also:
- /ets/hdr-ets-1.0.0-SNAPSHOT/db/execute/readme/Terminology_File_Formats_Classifications.txt from hdr-1.0.0-SNAPSHOT.zip for file formats.
Load the classification. The procedure for loading a classification is the same as that for loading a Coding Scheme Version. Enter ETSClassifications in the Coding Scheme Name field on the Parameters page. Enter any text for the Coding Scheme Version Name (this field must contain text, but the actual text is ignored by the loader).
Import the classification. The procedure for importing a classification is the same that for importing a Coding Scheme Version.
Run the Healthcare HDR Maintenance Job to build the classification.

Building a Classification with the HDR Maintenance Job

To build a classification run the HDR Maintenance Job with CLASSIFICATIONS in run mode.

Note:

Run the HDR Maintenance job in the full mode whenever a significant amount of new classification data is created (including the first time classifications are created and populated in ETS.

Updating Published Coding Scheme Versions

After a coding scheme version is imported (published), you can update its properties (description, status, and default status) through the ETS API.

Running the HDR Maintenance Job

The HDR maintenance Job performs several database tasks. These tasks include:

Maintaining the ETS stage tables. For example, cleanup of incomplete or obsolete data in the staged tables.
Maintaining the ETS data in the active tables. For example, cleanup of failed imports in the active tables.
Building classifications by processing data for classifications in the pending or dirty state.
Building and synchronizing intermedia indexes.
Gathering statistics for the Cost-based Optimizer.
Ensuring that there is an entry in the language mapping table for each combination of coding scheme version and installed languages.

The maintenance job must be run in either FULL mode or CLASSIFICATIONS mode to move a classification from the 'dirty' or pending state to the active state. In general, it is a good idea to run the maintenance job periodically to keep ETS running optimally.

Note:

You should run the HDR Maintenance Job in the FULL mode:

Each time you apply a patch to ETS.
Whenever a significant amount of new classification data is created (including the first time classifications are created and populated in ETS).

Scheduling the Maintenance Job

Note:

In job arguments, select the desired Run Mode. The available choices are:

CLASSIFICATIONS: Builds classifications by matching definitions of classifications in the pending or dirty state. Classifications that have been created since the last time the maintenance job was run in CLASSIFICATIONS or FULL mode will be in the pending state. Classifications that have been modified since the last time the maintenance job was run in CLASSIFICATIONS or FULL mode will be in the dirty state. Successfully processed classifications obtain the active state.
CLEAN_ACTIVE: Performs maintenance on the ETS data in the active tables. Removes data from failed imports in the active tables, and rebuilds the intermedia indexes, if necessary. Ensures that there is an entry in the language mapping table for each combination of coding scheme version and installed languages.
CLEAN_STAGE: Performs maintenance on ETS stage tables. Removes incomplete or obsolete data from the staged tables, and rebuilds the intermedia indexes, if necessary.
DEFAULT: Performs maintenance on ETS stage, active, and language mapping tables, but does not build classifications. This mode is composed of CLEAN_ACTIVE and CLEAN_STAGE modes of the maintenance job.
FULL: Performs all operations, including maintenance of stage, active and language mapping tables, and building of classifications. This mode is composed of CLEAN_ACTIVE, CLEAN_STAGE, and CLASSIFICATION modes of the maintenance job.
TRUNCATE_STAGE: Removes all staged contents, regardless of their status. This mode is faster than CLEAN_STAGE for large datasets.

Caution:
The TRUNCATE_STAGE option can cause data that could have been used by the importer to be lost.

See also:

Oracle Applications System Administrator's Guide
HDR ConceptList Interface for more information about the ETS ConceptList Class.
HDR Concept List Index for more information about ETS supported concept lists.

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.

Intraterminology Equivalence

Intraterminology equivalence deals with identical concepts (those with the same meaning) within a single terminology. When a new version of a terminology is released, there may be several changes to the representation and meaning of concepts when compared to the previous version. Because there is no way for ETS to automatically determine these changes, by default it treats concepts from the previous and new versions as distinct and unrelated. However, it is possible to explicitly indicate the changes that have occurred between a prior version and a new version in a change file that is loaded with the new version. Using this information, Intraterminology equivalence services can determine whether two concepts from the previous version and the new version have the same meaning.

Given a concept from a version of a terminology, ETS can retrieve equivalent concepts from all contiguous versions that have change files loaded. Given two concepts from different versions of a terminology, ETS can verify if they are equivalent, provided that the more recent version and all the intermediate versions have change files loaded.

Interterminology Equivalence

Interterminology equivalence deals with identical concepts (those with the same meaning) from different terminologies. Concepts from two different terminologies can vary widely in their granularity and coverage of a domain. Because there is no way for ETS to automatically determine these differences, by default it treats concepts from the two terminologies as distinct and unrelated. However, it is possible to explicitly indicate equivalence between concepts from two versions of different terminologies in the form of an Interterminology Mapping. Using this information, Interterminology equivalence services can determine whether two concepts from different terminologies have the same meaning.

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 8-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)

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:

Table 8-5 Sample Concept Descriptions

Version ID	Concept ID	Description Text	Language
v20070101	A25.66	Fracture of Femur	American English
v20070101	A25.66	Fracture of Femur	Korean
v20070101	A25.66	Fracture of Femur	Spanish
v20070101	A25.66	Fracture of Femur	Japanese
v20070101	A25.66	Fracture of Femur	German

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.

See also:

The HDR Loader Job Readme files for information about loading terminologies, including language mapping setup.

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.

Scenario

Assume an installation in London, England with base (or default) language in American English.

Assume a terminology that includes French and American English descriptions but not British English. Users requesting British English are given an American English description because no British English description exists. This is represented in the following table:

Mappings

Requested Locale	Description Locale
en_GB	en_US
fr_FR	fr_FR
en_US	en_US

When a description is requested in a particular locale, ETS locates this mapping and determines which language to return. In this scenario:

If a British English description is requested, ETS returns an American English description.
If a French description is requested, ETS returns a French description.
If an American English description is requested, ETS returns an American English description.

If a description is requested and the locale is not specified (non locale enabled APIs), ETS assumes that the requested locale is in the base language and uses the mapping to determine which language the description should return. In this scenario, the American English description is returned because the base language (American English) maps to American English.

To provide British English descriptions, create British English local descriptions. When a description is requested in British English, ETS returns the British English local description and ignores the mapping.

Locale Enabled APIs

getLocale
findConcepts
createLocalConceptDescription
getDescription
getLocallyPreferredDescription
getTerminologyPreferredDescription
getAllDescriptions

A code sample below can help you to:

Use a Locale-Enabled API (see Example 8-6)

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", "")

Errors

Locale enabled APIs may throw the following exceptions for MLS specific reasons.

An ETSBadParameterException is thrown when the Locale is not valid. The following Locales are considered invalid:
- Locales where the language code or territory code is missing.
- Locales that contain a variant.
An ETSDataException is thrown when the language mapping is missing.

Example 8-6 Use a Locale-Enabled API

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());

See also:

Implementing Master Catalog
HDR Concept Lists Index, Oracle Healthcare Data Repository Javadoc (click HDR Concept Lists link at bottom of Javadoc pages), for seeded concept lists and values.

See also:

Character Sets & Conversion - Frequently Asked Questions (This information is on MOS in article 227330.1.)
Unicode character sets in the Oracle database (This information is on MOS in article 260893.1.)
IETF RFC 3066 (This information is on MOS in article 458871.1.)—The terminology data files that are processed by the ETS Loader validate against RFC 3066 (2-letter language—hyphen—2-letter territory). This representation is the combination of ISO 639-1 alpha-2 language codes and ISO 3166-1 alpha-2 territory codes.
ISO 639-1 (alpha-2 codes)
ISO 3166-1 (territory codes)
java.util.Locale