2 Implement the HDR Platform

Implementation Tables

Creating an 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.

Loading an 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.

Editing an 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

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.

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-8.0.0/db/execute/readme from hdr-1.0.0-8.0.0.zip, for details regarding file formats required by ETS terminology loaders.

   • /ets/hdr-ets-1.0.0-8.0.0/db/execute/readme/Change_File_Formats_General.txt from hdr-1.0.0-8.0.0.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).

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-8.0.0/db/execute/readme from hdr-1.0.0-8.0.0.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. For more information, refer to Appendix D: Running HDR Terminology Jobs.

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. For more information refer Appendix D: Running HDR Terminology Jobs.

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

• Appendix D: Running HDR Terminology Jobs

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-8.0.0/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.

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.

Prerequisites

None

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 2-3 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.

Loading Cross Maps Provided by the College of American Pathologists

The principal difference between cross map files distributed by the College of American Pathologists (with SNOMED CT) and those expected by ETS loaders is that the SNOMED CT files could contain data regarding multiple map sets in a single file. The map set file may contain multiple rows, each pertaining to a different map set. The cross map file may contain cross maps relating to multiple map sets, and the map targets file may contain targets used by multiple map sets (targets related to multiple coding schemes).

To make the SNOMED CT files suitable for ETS loading, split the files into map sets. The map set file should contain only one row, representing one map set. The cross maps file should contain only rows containing the map set ID of the chosen map set. The map targets file should contain only targets related to the target coding scheme specific to the map set.

See Also:

/ets/hdr-ets-1.0.0-8.0.0/db/execute/readme from hdr-1.0.0-8.0.0.zip for the cross-map table structures.

Associating a Usage Context with an Organization

Use the following method to associate a usage context with an organization:

associateUsageContextWithExternalOwner

See Also:

Oracle Healthcare Data Repository Javadoc

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

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.

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

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

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.

See Also:

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-8.0.0/db/execute/readme /Terminology_File_Formats_Generic.txt from hdr-1.0.0-8.0.0.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):

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:

1. Create a Classifications file. This file lists the classifications to be created and their properties.

2. 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.

   See Also:

   Creating New Generic Coding Schemes

3. 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.

4. Create a control file specifying the Classifications, Classification Descriptions, and Classification Declarations files.

   See Also:

   /ets/hdr-ets-1.0.0-8.0.0/db/execute/readme/Terminology_File_Formats_Classifications.txt from hdr-1.0.0-8.0.0.zip for file formats.

5. 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).

   See Also:

   Loading a Coding Scheme Version

6. Import the classification. The procedure for importing a classification is the same that for importing a Coding Scheme Version.

   See Also

   Publishing a Coding Scheme Version

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

Steps

Refer to Running HDR maintenance Job from Appendix D: Running HDR Terminology Jobs

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

• Appendix D: Running HDR Terminology Jobs

Creating Profile Options

Create new profile options using the ProfileOptionService.createProfileOption API.

For example, a physician order entry application could define a profile option that defines the default sort order of patient problem lists (by date, severity,...).

Updating Profile Options

Update profile options using the ProfileOptionService.updateProfileOption API.

Updating Profile Option Values

Update existing profile option values for the already created profile options using the ProfileOptionService.setProfileOptionValue API.

Concept Equivalence Support

The Master Catalog incorporates concept equivalence. Concept equivalence considers all concepts that are equivalent to the concept used in the Master Catalog entry, as also being covered by that Master Catalog entry. For example, an OBS.EVN Master Catalog entry is defined with the Code attribute valued with 364075005 (SNOMED-CT, Version 0607CORE) for heart rate. Subsequently, a new version of SNOMED-CT is released with a different concept representing heart rate. When using concept equivalence, it is not necessary to modify or append the existing Master Catalog entry. If the concept equivalence defines the equivalence between the two concepts for heart rate, Master Catalog will consider as valid any OBS.EVN with either of the two concepts, though the Master Catalog entry itself only contains the Version 0607CORE concept. This approach eliminates the need to update the Master Catalog when a new coding scheme or version is loaded in ETS, provided equivalence information is also loaded with the new coding scheme or version.

Using the Code Type Attribute for Acts

The Code Type attribute in the Master Catalog specifies the values permitted for the Code attribute on the Act instance. You can choose to do any one of the following:

• Allow a specific Code value for a given Class Code and Determiner Code (Code Type ID)

• Allow any Code value for a given Class Code and Determiner Code (Code Type ANY)

• Constrain the Code attribute so it must be null (Code Type NULL)

Code Type ID

If the Code Type attribute of the Act Master Catalog entry is ID, the Class Code, Mood Code, and Code attributes of the entry specify which Acts are covered by this Master Catalog entry. The Code attribute of the Act (Act.code) must have the specified value, or its equivalent.

The following table displays a sample Act entry with Code Type attribute as ID:

This Act Master Catalog entry encompasses Acts representing a patient care provision event, specifically a primary care provider (PCP) assignment. That is, any Act whose Class Code attribute is PCPR, Mood Code attribute is EVN, and Code attribute is 000928 or an equivalent ETS Concept.

Code Type NULL

If the Code Type attribute of the Act Master Catalog entry is NULL, the Class Code, Mood Code, and Code attributes of the entry specify which Acts are covered by this Master Catalog entry. The Code attribute of the allowed Act (Act.code) must be null.

The following table displays a sample Act entry with Code Type attribute as NULL:

This Act Master Catalog entry encompasses Acts representing a request for patient care provision, with no further specification. That is, any Act whose Class Code attribute is PCPR, Mood Code attribute is RQO, and Code attribute is null.

Code Type ANY

If the Code Type attribute of the Act Master Catalog entry is ANY, the Class Code, Mood Code, and Code attributes of the entry specify which Acts are covered by this Master Catalog entry. The Code attribute of the allowed Act (Act.code) can have any value except null.

The following table displays a sample Act entry with Code Type attribute as ANY:

This Act Master Catalog entry encompasses Acts representing a request for patient care provision, with further specification. That is, any Act whose Class Code attribute is PCPR, Mood Code attribute is RQO, and Code attribute is any valid ETS concept. Acts that have a null Act.code are not covered by this Master Catalog entry.

The following table displays sample Act Master Catalog entries from the HDR seed data:

Note: The Confidentiality Code column has not been displayed as no data is seeded for this attribute

Master Catalog Entities

In the RIM, the Class Code, Determiner Code, and Code attributes on an Entity specify the type of Entity that instance represents. As in the RIM, these attributes in the Master Catalog specify the types of Entities that are used in HDR. Entity Master Catalog entries define the specific combinations of the Class Code, Determiner Code and Code, which are required by the HDR solution.

The following table describes the Master Catalog metadata that can be defined for Entities:

See Also

Oracle Healthcare Data Repository API Documentation, MasterCatalog interface

Sample Entity Master Catalog entries (from the seeded data supplied with HDR) are given in the Sample Entity Entries table.

Using the Code Type Attribute for Entities

The Code Type attribute in the Master Catalog specifies the values permitted for the Code attribute on the Entity instance. You can choose to do any one of the following:

• Allow a specific Code value for a given Class Code and Determiner Code (Code Type ID)

• Allow any Code value for a given Class Code and Determiner Code (Code Type ANY)

• Constrain the Code attribute so it must be null (Code Type NULL)

Code Type ID

If the Code Type attribute of the Entity Master Catalog entry is ID, the Class Code, Determiner Code, and Code attributes of the entry specify which Entities are covered by this Master Catalog entry. The Code attribute of the Entity (Entity.code) must have the specified value or its equivalent.

The following table displays a sample Entity entry with Code Type attribute as ID:

This Entity Master Catalog entry encompasses Entities representing an organization instance, where the organization is specifically a religious organization. That is, any Entity whose Class Code attribute is ORG, Determiner Code attribute is INSTANCE, and Code attribute is RELIG or an equivalent ETS Concept.

Code Type NULL

If the Code Type attribute of the Entity Master Catalog entry is ANY, the Class Code, Determiner Code, and Code attributes of the entry specify which Entities are covered by the entry. The Code attribute of the allowed Entity (Entity.code) can have any value except null.

The following table displays a sample Entity entry with Code Type attribute as NULL:

This Entity Master Catalog entry encompasses Entities representing an organization instance, with no further specification. That is, any Entity whose Class Code attribute is ORG, Determiner Code attribute is INSTANCE, and Code attribute is null.

Code Type ANY

If the Code Type attribute of the Entity Master Catalog entry is ANY, the Class Code, Determiner Code, and Code attributes of the entry specify which Entities are covered by the entry. The Code attribute of the allowed Entity (Entity.code) can have any value except null.

The following table displays a sample Act entry with Code Type attribute as ANY:

This Entity Master Catalog entry encompasses Entities representing an instance of an organization, with further specification. That is, any Entity whose Class Code attribute is ORG, Determiner Code attribute is INSTANCE, and Code attribute is any valid ETS Concept. Entities that have a null Entity.code are not allowed by this entry.

The following table displays sample Master Catalog Entity entries from the HDR seed data:

Master Catalog Roles

In the RIM, the Class Code and Code attributes on a Role, and the Class Code, Determiner Code, and Code attributes on the player and scoper Entity, specify the type of Role that instance represents. As in the RIM, these attributes in the Master Catalog specify the types of Roles that are used in HDR. Role Master Catalog entries define the specific combinations of the Class Code and Code, and Entity Class Code, Determiner Code, and Code, which are required by the HDR solution.

The following table describes the Master Catalog metadata that can be defined for Roles:

See Also

Oracle Healthcare Data Repository Javadoc, MasterCatalog interface

Using the Code Type Attribute for Roles

The Code Type attribute in the Master Catalog specifies the values permitted for the Code attribute on the Role instance. You can choose to do any one of the following:

• Allow a specific Code value for a given Class Code, player, and scoper Entity (Code Type ID)

• Allow any Code value for a given Class Code, player, and scoper Entity (Code Type ANY)

• Constrain the Code attribute so it must be null (Code Type NULL)

Code Type ID

If the Code Type attribute of the Role Master Catalog entry is ID, the Class Code and Code attributes of the Role entry, and the Class Code, Determiner Code, and Code attributes of the player Entity and scoper Entity, specify which Roles are covered by this Master Catalog entry. The Code attribute of the Role (Role.code) must have the specified value or its equivalent.

The following table displays a sample Role entry with Code Type attribute as ID:

This Role Master Catalog entry encompasses Roles representing a guarantor, specifically a workers compensation guarantor, with a playing organization Entity and a scoping person Entity, where the scoping person Entity owns the role. That is, any Role whose Class Code attribute is GUAR and Code attribute is 001899 or an equivalent ETS Concept, which is played by an ORG.INSTANCE with any valid Entity.code, and scoped by a PSN.INSTANCE with a NULL Entity.code, where the PSN.INSTANCE is the owning Entity.

Code Type NULL

If the Code Type attribute of the Role Master Catalog entry is NULL, the Class Code and Code attributes of the Role entry, and the Class Code, Determiner Code, and Code attributes of the player Entity and scoper Entity, specify which Roles are covered by this Master Catalog entry. The Code attribute of the allowed Role (Role.code) must be null.

The following table displays a sample Role entry with Code Type attribute as NULL:

This Role Master Catalog entry encompasses Roles representing a birthplace, with a playing place Entity and a scoping person Entity, where the scoping person Entity owns the role. That is, any Role whose Class Code attribute is BIRTHPLC and Code attribute is null, which is played by a PLC.INSTANCE with any valid Entity.code and scoped by a PSN.INSTANCE with a null Entity.code, where the PSN.INSTANCE is the owning Entity.

Code Type ANY

If the Code Type attribute of the Entity Master Catalog entry is ANY, the Class Code and Code attribute of the Role entry, and the Class Code, Determiner Code, and Code attributes of the player Entity and scoper Entity, specify which Roles are covered by this Master Catalog entry. The Code attribute of the allowed Role (Role.code) may have any value except null.

The following table displays a sample Role entry with Code Type attribute as ANY:

This Role Master Catalog entry encompasses Roles representing a covered party, with a playing person Entity and a null scoping Entity, where the role is not owned. That is, any Role whose Class Code attribute is COVPTY and Code attribute is any valid ETS Concept, which is played by a PSN.INSTANCE with a null Entity.code, with no scoper entity and no owning entity.

The following table displays sample Master Catalog Role entries from the HDR seed data:

Note: The Confidentiality Code column has not been displayed as no data is seeded for this attribute.

Business Events

In the Focal Class State Transition table there is a Business Event attribute, which refers to a process that will be raised or initiated in the event of that state transition. (This attribute is named TriggerEventCode in the HDR API). HDR Applications can use these business events to initiate processes that are dependent on specific focal class state transitions.

For example, an encounter discharge may be defined in the Focal Class State Transition table with the relevant Control Act and Focal Class, and begin state active and end state completed. The business event code for the discharge business event will then be populated in the Focal Class State Transition table to cross reference the state transition to the business event details.

No default values for the business events are seeded with the base HDR platform data. You must add your own business event codes if you wish to utilize this functionality.

See Also

• Oracle Workflow

• Oracle BPEL Server

The following table describes the metadata that can be defined for Focal Class State Transitions:

See Also

Oracle Workflow

Start State and End State

The start state and end state of the Focal Class State Transitions can be defined with specific values (RIM-defined states, such as active and completed) or generic values (null or any). This allows you to define which state transitions are allowed. For example, an entry can allow a start state of active and an end state of completed for a given control act and focal class. Alternatively, an entry can broadly define the state transitions allowed for a given control act and focal class. For example, from any start state to any end state, or from a null start state to a specific end state of active.

The following combinations of start state and end state are valid:

• any to any

• null to null

• specific state to specific state

• null to specific state

The following combinations of start state and end state are invalid:

• specific state to any

• specific state to null

• any to specific state

The following table displays sample Focal Class State Transitions from the HDR seed data:

Setting Up Master Catalog

Perform the following steps to make entries into the Master Catalog:

Steps

For a new implementation of HDR, perform the following steps:

1. Create a comprehensive list of all Acts, Entities, and Roles required by the entire healthcare enterprise.

   This may include Acts, Entities, and Roles that will need to be persisted by RIM Services, and any required to support Act Concept Configuration and Side Effect Configuration.

   Many generic Act, Entity, and Role entries are provided in the Master Catalog as seed data. These can be a starting point for this analysis. Identify any required Act, Role, and Entity classes that are not provided as seed data.

   See Also

   • Oracle Healthcare Data Repository, Seeded Master Catalog Entries for Version 5, an Oracle White Paper available on My Oracle Support

   • Oracle Healthcare Data Repository Programmer's Guide (HDR Messaging > HDR Inbound Message Processor > IMP Configuration > Side Effect Configuration)

2. Analyze the identified acts, roles and entities to determine which terminology best meets enterprise requirements.

   • In some cases, a single standard terminology may be sufficient for a logical group. For example, the LOINC terminology can be used for all laboratory results.

   • In other cases, you may have to extend a standard terminology. For example, LOINC and a local vocabulary could be used for laboratory orders.

   • Less frequently, an unmapped local vocabulary scheme may be required or created for unique needs, such as patient education.

3. Load the core, standard, and local terminologies into ETS that are required for creating the enterprise Master Catalog. Also load the relevant Cross Maps and Change files (which contain the equivalence data).

   See Also

   • Implementing Enterprise Terminology Services

   • Implementing Interterminology and Intraterminology Equivalence

4. Search for the ETS Concepts that are to be used for specific Act, Entity, and Role Master Catalog entries with a Code Type ID and identify their Concept Code, Code System, and Version. For example, to create a Master Catalog Act entry for a specific observation (Code Type is ID) with Act.code defined as SNOMED-CT concept 364075005 (heart rate), you must determine the Concept Code, Code System, and Version for this concept.

5. Determine the Master Catalog attribute values for each Act, Entity, and Role.

   See Also

   Act, Entity, and Role Master Catalog Attribute tables for information about Act, Role, and Entity attributes

6. Identify focal class state transitions (clinical, administrative and core) relevant to the defined Act, Entity, and Role Master Catalog entries. All focal class state transitions required to support the HDR messaging solutions are provided as seed data. These can be used as a starting point. Identify any additionally required focal class state transitions, which are not already provided as seed data.

   To identify the focal class state transitions do the following:

   • Identify the focal class object, which must be an Act, an Entity, or a Role from the Master Catalog.

   • Identify the appropriate Control Act from the Master Catalog.

   • Identify the required state transitions.

   Caution: These state transitions must be a complete set or subset of the valid state transitions defined by HL7. You cannot extend the valid state transitions defined by HL7.

7. Create the Master Catalog (Act, Entity, and Role) entries and Focal Class State Transition entries using the MasterCatalogService API.

   See Also

   • Act Master Catalog Attributes table, for information about Act attributes.

   • Entity Master Catalog Attributes table, for information about Entity attributes.

   • Role Master Catalog Attributes table, for information about Role attributes.

Master Catalog Object Factory

The Master Catalog object factory provides methods for creating two types of objects:

• Master Catalog entries

• Master Catalog focal class state transition entries

Both object types are intended to be passed to the MasterCatalogService.

-DCTB_SUBQRY_OPT_METHOD=NONE

This is the default behavior where all nested select sub queries in the where condition will be generated as the SQL IN condition.

For example, SELECT CtbCoreRolesEO.ROLE_ID, CtbCoreRolesEO.ROLE_VERSION_NUM FROM CTB_CORE_ROLES CtbCoreRolesEO WHERE CtbCoreRolesEO.CLASS_CODE = 'PAT' AND(CtbCoreRolesEO.PLAYER_ID, CtbCoreRolesEO.PLAYER_VERSION_NUM) IN ( SELECT CtbCoreEntitiesEO.ENTITY_ID, CtbCoreEntitiesEO.ENTITY_VERSION_NUM FROM CTB_CORE_ENTITIES CtbCoreEntitiesEO WHERE CtbCoreEntitiesEO.CLASS_CODE = 'PSN' AND CtbCoreEntitiesEO.DETERMINER_CODE = 'INSTANCE' AND CtbCoreEntitiesEO.ENTITY_ID IN ( SELECT CtbCoreEntyIIEO.ENTITY_ID FROM CTB_CORE_ENTY_II CtbCoreEntyIIEO WHERE CtbCoreEntyIIEO.ROOT_ID = '1.2.3' AND CtbCoreEntyIIEO.EXTENSION_TXT = 'Person1' ) ) ;

-DCTB_SUBQRY_OPT_METHOD=EXISTS

By setting sub-query optimization method to EXISTS, all nested select sub queries in the where condition will be generated as the SQL EXISTS condition.

For example, SELECT CtbCoreRolesEO.ROLE_ID, CtbCoreRolesEO.ROLE_VERSION_NUM FROM CTB_CORE_ROLES CtbCoreRolesEO WHERE CtbCoreRolesEO.CLASS_CODE = 'PAT' AND EXISTS ( SELECT 1 FROM CTB_CORE_ENTITIES CtbCoreEntitiesEO WHERE CtbCoreEntitiesEO.CLASS_CODE = 'PSN' AND CtbCoreEntitiesEO.DETERMINER_CODE = 'INSTANCE' AND CtbCoreEntitiesEO.ENTITY_ID = CtbCoreRolesEO.PLAYER_ID AND CtbCoreEntitiesEO.ENTITY_VERSION_NUM = CtbCoreRolesEO.PLAYER_VERSION_NUM AND EXISTS ( SELECT 1 FROM CTB_CORE_ENTY_II CtbCoreEntyIIEO WHERE CtbCoreEntyIIEO.ROOT_ID = '1.2.3' AND CtbCoreEntyIIEO.EXTENSION_TXT = 'Person1' AND CtbCoreEntyIIEO.ENTITY_ID = CtbCoreEntitiesEO.ENTITY_ID ) ) ;

-DCTB_SUBQRY_OPT_METHOD=JOIN

By setting sub-query optimization method to JOIN, all nested select sub queries in the where condition will be converted to the SQL JOIN condition.

For example, SELECT CtbCoreRolesEO1.ROLE_ID, CtbCoreRolesEO1.ROLE_VERSION_NUM FROM CTB_CORE_ROLES CtbCoreRolesEO1, CTB_CORE_ENTITIES CtbCoreEntitiesEO1, CTB_CORE_ENTY_II CtbCoreEntyIIEO1 WHERE CtbCoreRolesEO1.CLASS_CODE = 'PAT' AND CtbCoreEntitiesEO1.CLASS_CODE = 'PSN' AND CtbCoreEntitiesEO1.DETERMINER_CODE = 'INSTANCE' AND CtbCoreEntitiesEO1.ENTITY_ID = CtbCoreRolesEO1.PLAYER_ID AND CtbCoreEntitiesEO1.ENTITY_VERSION_NUM = CtbCoreRolesEO1.PLAYER_VERSION_NUM AND CtbCoreEntyIIEO1.ROOT_ID = '1.2.3' AND CtbCoreEntyIIEO1.EXTENSION_TXT = 'Person1' AND CtbCoreEntyIIEO1.ENTITY_ID = CtbCoreEntitiesEO1.ENTITY_ID;