Use Master Catalog API

Master Catalog Entries

During persistence all Acts, Entities, and Role objects are validated against the Master Catalog. Master Catalog defines the ETS values for class code, mood code, determiner code, code, player entity, and/or scoper entity that are allowed for these objects. HDR supports three types of ETS values: (1) explicit values specifying the ID of the concept, (2) null values when no values are required, or (3) any value when all ETS concepts are valid.

To ensure that Master Catalog entries exist for all objects being persisted prior to submission, HDR provides APIs to query and create Master Catalog data.

HDR provides MasterCatalogService APIs to create, update, and query Master Catalog entries.

Concepts

Master Catalog entry defines constraints based on:

Act: Class Code, Mood Code and Code.
Entity: Class Code, Determiner Code and Code.
Role: Class Code, Code and the Player and Scoper Master Catalog IDs.

All Master Catalog entries define a code type—ID, ANY, or NULL.

ID: Code attribute of the entity should be a valid ETS concept code.
ANY: Code attribute of the entity should be null.
NULL: Code attribute of the entity should be null.

For all Master Catalog getXxx() search operations, if the codeType is ID, then the getXxx() operation goes by the following order of precedence:

Looks for the exact concept code.
If the exact code not found, it looks for equivalent concept code.
If equivalent concept code not found, it looks for code type ANY.

The Master Catalog supports concept equivalence. It considers a concept valid if it is equivalent to a concept used in an entry. You need not update the Master Catalog when new a coding scheme or version is loaded in ETS, provided equivalence information is also loaded with the new coding scheme or version. Concept equivalence is also used to verify whether user is trying to set up a duplicate Master Catalog entry. If one Master Catalog entry exists for a concept, no other entry with its equivalent concepts is permitted.

See also:

Oracle Healthcare Data Repository API Documenation for more information about Master Catalog interfaces.
Oracle Healthcare Data Repository Implementation Guide for more information about Master Catalog validations.

Example 7-20 Check for the Existence of a Master Catalog Entry Matching the Control Act

// Find the Master Catalog Entry with parameters:
        // class code = CACT (From the ActClass Domain)
        // mood code = EVN (From the ActMood Domain)
        // code = null
        // code type = "NULL"
        MasterCatalog mc = masterCatalogService.getMasterCatalogActEntry(ActClass.CACT, ActMood.EVN, 
         null, "NULL");
        if (mc.getMasterCatalogId() != null)
        { 
            System.out.println("Master Catalog Record found. ID: " + mc.getMasterCatalogId());
        }
        else 
        {
              System.out.println("No Master Catalog Record found");
        }

Example 7-21 Check for the Existence of a Master Catalog Entry Matching the Person

// Find the Master Catalog Entry with parameters:
        // class code = PSN (From EntityClass Domain)
        // determiner code = INSTANCE (From EntityDeterminer Domain)
        // code = null
        // code type = "NULL"
        MasterCatalog mc = masterCatalogService.getMasterCatalogEntityEntry
         (EntityClass.PSN, EntityDeterminer.INSTANCE, null, "NULL");
        if (mc.getMasterCatalogId() != null)
              { 
            System.out.println("Master Catalog Record found. ID: " + mc.getMasterCatalogId());
              }
        else 
             {
             System.out.println("No Master Catalog Record found");
             }
 
 
 
       If suitable entries do not exist, use the persistMasterCatalog API to create one.

Example 7-22 Create a Master Catalog Entry for a Diagnostic Image

// Create a Master Catalog Entry with parameters:
      // class code = DGIMG (From the ActClass Domain)
      // mood code = EVN (From the ActMood Domain)
      // code = null
      // code type = "NULL"
      MasterCatalog mc = masterCatalogFactory.newMasterCatalog();
      mc.setClassCode(ActClass.DGIMG);
      mc.setCodeType(MasterCatalog.NULL_CODE_TYPE);
      mc.setMoodCode(ActMood.EVN);
      mc.setEntryTypeCode(MasterCatalog.ACT_ENTRY_TYPE_CODE);
      mc.setActiveFlag(true);
 
      masterCatalogService.persistMasterCatalogEntry(mc);

Example 7-23 Create an Array of Master Catalog Entries

You can create or update an array of MasterCatalog entries using MC bulk persists API. For each entry in array, the API checks, if it is a valid entry, as follows and persists it. In the case of one or more invalid entries, the API rejects all of them.

MasterCatalog mc1 = masterCatalogFactory.newMasterCatalog();
 MasterCatalog mc2 = masterCatalogFactory.newMasterCatalog();
 
// For each master catalog entry defined above, to set the values follow the steps described in Example 7-32.
 
//Create an array of mastercatalog with the above mentioned entries
MasterCatalog [] mcArray = new MasterCatalog [] {mc1,mc2};
 
//Call bulk persist method
 masterCatalogService.persistMasterCatalogEntries(mcArray);

Example 7-24 Search Master Catalog Entries Using Query Criteria

You can retrieve MasterCatalog entries based on MasterCatalogQueryCriteria using this API, which takes the MasterCatalogQueryCriteria as the parameter. MasterCatalogQueryCriteria defines methods that can be used to build a query for retrieving MasterCatalog records based on the criteria.

// Defining the MasterCatalogQueryCriteria to find Master Catalog Entry, for code type = "ID" and coding scheme
// name = "HDR Supplemental", coding scheme version name = "HDR Supplemental (2005-04-08)" and concept code = "001827"
 
// get an instance of the Master Catalog Criteria 
 
MasterCatalogQueryCriteria masterCatalogSearchCriteria = masterCatalogFactory().newMasterCatalogQueryCriteria(); 
SearchTerm searchTerm = masterCatalogSearchCriteria.equalsCode("HDR Supplemental", "HDR Supplemental (2005-04-08)", "001827"); 
 
// set the code type to ID 
searchTerm = masterCatalogSearchCriteria.and(searchTerm, masterCatalogSearchCriteria.equalsCodeType(MasterCatalog.ID_CODE_TYPE));
 
// set the root search term 
masterCatalogSearchCriteria.setRootSearchTerm(searchTerm); 
 
// retrieve master catalog entry 
MasterCatalog [] fetchedMasterCatalog = masterCatalogService.findMasterCatalogEntries(masterCatalogSearchCriteria);

Example 7-25 Remove Master Catalog Entries from Cache

The Master Catalog API uses the CTBCacheService for caching the Master Catalog and Master Catalog Focal Class State Transition entries. The following table lists the cache names used to store the object:

Cache Names

Cache Name	Description	Key
CtbCoreMcActEntriesCache	Cache name for Master Catalog Act entries	ClassCode
CtbCoreMcEntityEntriesCache	Cache name for Master Catalog Entity entries	ClassCode
CtbCoreMcRoleEntriesCache	Cache name for Master Catalog Role entries	ClassCode
CtbCoreMcStTrnstnsCache	Cache name for Master Catalog Focal Class State Transition entries	ControlActMasterCatalogId

Example 7-26 Remove Master Catalog Entries from Cache

There are 2 APIs, which you can use to remove Master Catalog entries from the cache.

//This will remove all the entries from the Act Master Catalog cache, here we only supply the cache name as parameter.
 
cacheService.invalidate("CtbCoreMcActEntriesCache");
 
//There is also an option to selectively delete entries from the cache using the key. 
//Here the class code is being used as a key for the Act Master Catalog entries cache. 
//This will remove all the act master catalog entries having that class code from the cache. 
 
cacheService.invalidate("CtbCoreMcActEntriesCache", "OBS");

Focal Class State Transitions

Focal Class State Transitions define the valid state transitions for a given combination of the Control Act Master Catalog ID and the Focal Class Master Catalog ID. These transitions must be a subset of the valid transitions for the RIM object type (Act, Entity, and Role). These transitions should be valid according to the generic state transition rules. The following are the possible state transition scenarios during creation or update of Act, Entity, and Role objects.

null -> null (Always allowed and is never validated)
not null -> not null (Allowed only after validation)
null -> not null (Allowed only after validation)
not null -> null (Not Allowed)

The examples below illustrate how to query for the existence of a Focal Class State Transition, and how to create a required Focal Class State Transition.

See also:

Oracle Healthcare Data Repository API Documentation for focal class description.
Oracle Healthcare Data Repository Implementation Guide for more information about Focal Class State Transitions.

Example 7-27 Check for Existence of a Focal Class State Transition (for Control Act and Focal Class)

String controlActMasterCatalogId = "";
        String focalClassMasterCatalogId = "";
 
        // Find the Master Catalog Entry for the Control Act
        MasterCatalog mc = masterCatalogService.getMasterCatalogActEntry(
            ActClass.CACT, ActMood.EVN, null, "NULL");
        controlActMasterCatalogId = mc.getMasterCatalogId();
 
        // Find the Master Catalog Entry for the Focal Class
        mc = masterCatalogService.getMasterCatalogEntityEntry(
            EntityClass.PSN, EntityDeterminer.INSTANCE, null, "NULL");
        focalClassMasterCatalogId = mc.getMasterCatalogId();
 
        // Retrieve the Focal Class State Transition for the given
        // Control Act, Focal Class where 
        // Focal Class start state = "null" and 
        // Focal Class end state = "active"        
              MasterCatalogFocalClassStateTransition mcfcst = 
            masterCatalogService.getFocalClassStateTransitionEntry(
            controlActMasterCatalogId, focalClassMasterCatalogId,
            "null","active");
        if (mcfcst != null)
        {
            System.out.println("Valid Focal Class State Transition found.");
        }
              else
              {
            System.out.println("Focal Class State Transition not found.");
              }

Example 7-28 Create a Focal Class State Transition

// Create a Focal Class State Transition for the
        // Master Catalog entry for DGIMG, EVN, NULL
      
        // Find the Control Act Master Catalog Entry
              MasterCatalog mcCact = masterCatalogService.getMasterCatalogActEntry(
            ActClass.CACT, 
              ActMood.EVN, null, 
            "NULL");
        // Find the DGIMG Act Master Catalog Entry
              MasterCatalog mcDgimg = masterCatalogService.getMasterCatalogActEntry(
            ActClass.DGIMG, 
              ActMood.EVN, null, 
            "NULL");
 
        MasterCatalogFocalClassStateTransition mcfcst = 
            masterCatalogFactory.newMasterCatalogFocalClassStateTransition();
        mcfcst.setControlActMasterCatalogId(mcCact.getMasterCatalogId());
        mcfcst.setFocalClassMasterCatalogId(mcDgimg.getMasterCatalogId());
        mcfcst.setActiveFlag(true);
        mcfcst.setStartState("any");
        mcfcst.setEndState("any");
 
        masterCatalogService.persistFocalClassStateTransitionEntry(mcfcst);
 
        // Now check it was persisted
        mcfcst = 
            masterCatalogService.getFocalClassStateTransitionEntry(
                mcCact.getMasterCatalogId(),
                mcDgimg.getMasterCatalogId(),
                "any", "any");
        if (mcfcst == null) throw new HDRConfigException(
              "Master Catalog Focal Class State Transition not found");

Example 7-29 Create an Array of Focal Class State Transition Entries

You can create or update an array of MasterCatalogFocalClassStateTransition entries using MC bulk persists API. For each entry in the array, the API checks if it is a valid entry as follows and persist it. If the API finds one or more invalid entries, it rejects all of them.

MasterCatalogFocalClassStateTransition mcfcst1 = masterCatalogFactory.newMasterCatalogFocalClassStateTransition(); MasterCatalogFocalClassStateTransition mcfcst2 = masterCatalogFactory.newMasterCatalogFocalClassStateTransition(); // For each mastercatalogfocalstatetransition entry defined above, to set the values follow the steps

// described in Example 7-37. //Create an array of mastercatalogfocalstatetransition with the above mentioned entries MasterCatalogFocalClassStateTransition [] mcfcstArray = MasterCatalogFocalClassStateTransition[] { mcfcst1, mcfcst1 }; //Call bulk persist method masterCatalogService.persistFocalClassStateTransitionEntries(mcfcstArray);