Draft Concept Determination Method Proposal - 2/28/2014 (Updated 3/14/2014)

Overview

One of the features of interest for a future version of OpenCDS is the ability to "hot deploy" new knowledge bases (e.g. - codes, concepts, drools rules, and supporting data) as needed without having to restart OpenCDS for the changes to take place. ICE, an application based on OpenCDS, envisions the following automated knowledge deployment capabilities within OpenCDS to support the operation of ICE. However, we also believe that the proposed functionality is generic and would benefit any OpenCDS-based services. For purposes of this discussion document, we will talk about the scenarios with respect to ICE for complete understanding of the requirements, and then abstract the requirements afterwards.

ICE is immunization forecasting software; the customizable rules are written in software called the CDS Administration Tool (CAT).
CAT manages - and can deploy to OpenCDS - the following artifacts, all of which are files stored in the OpenCDS knowledge-repository-data file structure:
- OpenCDS concepts (resourceAttributes/supportedConceptsConfigFile.xml)
- Code to OpenCDS concepts mappings (conceptMappingSpecifications/manualMappings)
- Knowledge modules; Scoping Entity ID/Business ID/Version (resourceAttributes/knowledgeModules.xml)
- Code System Code List (resourceAttributes/OpenCDSCodeSystems.xml)
- Drools Artifacts (DSLs, DRLs, DSLRs)
CAT also manages the following information that are represented in OpenCDS indirectly or in memory):
- Supporting Data (in-memory data that is cached by a knowledgeModule, such as immunization schedule parameters)
- Concept Determination Method (not directly deployable to OpenCDS but contained in code->concept mapping files)

Supporting data is any kind of data that is cached in instances of Java classes by the knowledgeModule during runtime operation. OpenCDS has the infrastructure to support the cached data (see Deployment Scenarios below).

For ICE, most of the cached data is stored in various Map classes that are accessed by the rules. Examples include table of static data related to vaccine, etc., and static values such as recommended ages and intervals. The cached data is not modified during execution and remains in memory for as long as the knowledge module is in memory by OpenCDS.

Deployment Use Case Scenarios

To start, I propose supporting the following "hot" deployment scenarios to OpenCDS. For those functions at the level of a knowledge module, the knowledgeModule is defined by its associated <scoping-entity>/<businessId>/<version>. That is, the OpenCDS web service should have the following capabilities for deploying knowledge to OpenCDS.

Note: For each of the below, we talk about the OpenCDS capability with respect to its XML representation in OpenCDS v1. However, this list is not meant to describe the solution as XML - just to describe the functionality. (e.g. - if the data in these files are represented in some other way in future versions of OpenCDS, the functionality requested is the same.)

1. Code Systems
  1. Replace entire OpenCDSCodeSystems.xml file. (Q: Is this still used somehow? We are using code systems not specified in this file and all still seems to work ok. If not, nevermind. PBW: Yes, this is still actively used (there are other places, but they're currently unused and will become deprecated): when building the OpenCDSConcepts and CDs–to get the code system from the OID (via a cached map) provided in the concept mappings..)
2. Concepts and Codes
  1. supportedConceptsConfigFile.xml: (PBW: The contents of this file are unused in the current release candidate–1.2.0.RC1.) (DC: Without this file, how are the Concept Types loaded on to the fact list, i.e. - is it a ProblemConcept, ImmunizationConcept, etc.)
    1. ~~FOR DEPLOYMENT: Replace the entire supportedConceptsConfigFile.xml file~~
    2. ~~FOR DEPLOYMENT: Add/Update/Delete individual entries in the supportedConceptsConfig.xml file~~
  2. Concept Mapping Files (See below wrt CDM)
    1. FOR DEPLOYMENT: Add/Replace all mapping files in the conceptMappingSpecifications/manualMappings or conceptMappingSpecifications/autoGeneratedMappings directory. (PBW: Would you want to add/replace all or be able to pick/choose which ones to replace, or add new concept mappings independently of all other mappings?)
3. BPMNs/DSLs/DRLs/DSLRs (Knowledge Module – by scopingEntityId, businessId, version)
  1. FOR DEPLOYMENT: Replace all DSLs/DRLs/DSLRs associated with a specified knowledgeModule at once (PBW: All or nothing or piecewise?) (DC: All or nothing by knowledgeModule; replacing all in one knowledgeModule would not affect another KnowledgeModule)
4. Supporting Data. (The supporting data will be supplied to OpenCDS as an XML (or some other type of) document, and it is up to the knowledgeModule implementer to write the necessary routines to read in the document contents into its custom Java instance objects. PBW: My thought is that it will be an opaque data set–hence whether it is XML or some other document or binary file, it will (should?) be handled, likely, as a byte array. In this case, however, it might make sense to provide additional metadata for the KM implementer to be able to know what type of data exists in the byte array. Thoughts?)
  1. FOR DEPLOYMENT: Replace the entire contents of the Supporting Data into the necessary persistence mechanism - likely files, as with artifacts - associated with a specified knowledgeModule at once.
  2. FOR RUNTIME: Provide the knowledgeModule author a routine for adding the in-memory contents to the global OpenCDS cache, which associates one-and-only-one in-memory supporting data object with a knowledgeModule (PBW: Which is to say that you want the ability to add/remove/update the SD independently of the KM? Which implies the KM must first exist in OpenCDS Configuration before adding the SD?) (DC: that's correct... the SD would be independent of the knowledgeModule, but the SD would have be "linked" to the knowledgeModule. The author would basically be indicating "this SD goes with this KM". So the knowledgeModule must first exist as you said.)
    2014-09-19 PBW: Is it possible that the SD could be leveraged by multiple knowledge modules? I'm currently thinking about a plugin system (as we discussed during our last call), where not only the plugin, but SD could potentially be used by multiple knowledge modules. Thinking about it this way allows me to consider loading a plugin and supporting data (the latter loaded into a cache by a plugin) at a higher level–the same level as the KMs and the CDMs, etc., such that the system only loads an instance of the plugin (and hence SD) for all KMs versus loading the same for each KM.
    DC: 2014-09-24: Yes, I could definitely see the supporting data being used by more than one Knowledge Moule, and therefore the SD could be loaded in at the plugin level. So this would essentially mean the same plugin could be used by different knowledge modules as well. Is this the design consideration you were intending to decide on?
    2014-09-24 PBW: Yes, that's the path I'm considering. To that extent, could an instance of SupportingData be used by multiple plugins?
    2014-09-24 DC: I suppose an instance of the supporting data could be used my multiple plugins, but my question would be under what circumstances we envision this would be used. What is the likelihood that different knowledge modules would need the same supporting data instance but use different plugins? Is this to accommodate if - for example - the knowledge modules used a different set of globals? Also, perhaps related to this, I don't understand what the purpose of the PluginPackage is. Hope this is helpful.
  3. FOR RUNTIME: Provide the knowledgeModule author a routine for removing the in-memory contents for a knowledgeModule from the global OpenCDS cache
  4. FOR RUNTIME: Provide the knowledgeModule author a routine for checking if in-memory contents exists for a knowledgeModule from the global OpenCDS cache
5. Initial functionality will not support the automated modifications to the knowledgeModule.xml or openCdsExeuctionEngines.xml files; these files can continue to be modified manually as they will rarely change. (PBW: In the general use case, the KMs may be updated frequently–particularly in the case of active development of rules.) (DC: Would be great to be able to have this automated too... I was just suggesting this is a lower priority.)

Revisions to OpenCDS Concept Determination Method

Description of Functionality

Initial Document Here.

The initial document (authored by Dave Shields) with some proposed designs for new features for Concept Determination Method handling in OpenCDS is in the link above. The proposed functionality is a little simplified from what is in the document.

ICE would like to support the following functionality now - configurable at the knowledge module level:

For each knowledgeModule, provide a way to represent in knowledgeModules.xml,indicate the Concept Determination Methods (CDMs) of interest for that particular knowledgeModule.
1. If no CDM is specified in the knowledgeModule.xml, mappings for all CDMs take place. (This is the Current OpenCDS behavior).
If specific CDMs are specified to be applied, then only apply mappings for the specified CDMs for the knowledge module during runtime. (That is, for each runtime request, only mappings for those CDMs listed for the knowledge module will be mapped to a concept and placed on the concept/fact list.)
If specific CDMs are listed for a knowledge module, one primary CDM must be specified. Primary CDMs are are always mapped, except as indicated by replacement CDMs. (PBW: Probably reading too much into this, but it sounds like you want multiple primary CDMs? Or one and only one primary? Would it even make sense to have multiple primaries?) (DC I was thinking one and only one primary, but I may not have thought through all the use cases.)
Additive CDMs can be specified for the knowledge module. Additive CDMs ALSO get mapped in addition to the primary CDM.
Replacement CDMs can be specified for the knowledge module (if any) which will replace any mappings from the primary CDM. So if the primary CDM for a code maps to one concept but the replacement CDM maps to a different concept for that code, the concept associated with the replacement CDM is chosen. (Note: Need to work out what to do if more than one replacement CDM is specified, or only permit one replacement CDM per knowledge module.)
PBW: Thoughts on 5... This is the way it will initially be implemented:
1. Replacement will only be replacement; if a concept exists in the secondary but does not exist in the primary, the replacement is not 'added' to the map.
2. Replacement will take a last-one-wins approach, where the last secondary CDM in the list will override all others before it, if the given concept exists in primary and other secondary CDMs which were previously specified
(in the list).

DC: Just to confirm the behavior for this one: when you say last-one-wins, this is only the case if more the one replacement-CDM is specified, right? Because additive CDMs would still be mapped. Thanks.

PBW: That is correct. Also, if you have a number of ADDITIVE CDMs, and add a REPLACEMENT CDM at the end of the list, it will replace matching concepts that were added. If you replace, then add, ADDITIVE will add the concepts the mappings. Ordering is important. I've also added a few docs about this; see Configuration Schemas.

Examples

Example definition of CDMs for a knowledge module

The below example knowledgeModules.xml entry shows three way to specify the CDMs of interest for the knowledge module for illustrative purposes only. Only concepts with codes belonging to these CDMs would be put on the Concept List / Fact List.

(1) org.nyc.cir.ICE.1.0.0

<kmMetadata>
    <identifier scopingEntityId="org.nyc.cir" businessId="ICE" version="1.0.0"/>
    <purpose language="en">New York City Immunization Calculation Engine (ICE)</purpose>
    <explanation language="en">String</explanation>
    <executionEngine>gov.nyc.health.ice.service.ICEDecisionEngineDSS55EvaluationAdapter</executionEngine>
    <dataModel>org.opencds.vmr^VMR^1.0</dataModel>
    <knowledgeModulePrimaryProcessName>PrimaryProcess</knowledgeModulePrimaryProcessName>
</kmMetadata>

(2) org.nyc.cir.ICE.1.0.1

<kmMetadata>
    <identifier scopingEntityId="org.nyc.cir" businessId="ICE" version="1.0.1"/>
    <purpose language="en">New York City Immunization Calculation Engine (ICE)</purpose>
    <explanation language="en">String</explanation>
    <executionEngine>gov.nyc.health.ice.service.ICEDecisionEngineDSS55EvaluationAdapter</executionEngine>
    <dataModel>org.opencds.vmr^VMR^1.0</dataModel>
    <knowledgeModulePrimaryProcessName>PrimaryProcess</knowledgeModulePrimaryProcessName>
    <conceptDeterminationMethods>

        <primary>NYCICESchedule-Primary</primary>

    </conceptDeterminationMethods>

</kmMetadata>

(3) org.nyc.cir.ICE.1.0.2

<kmMetadata>
    <identifier scopingEntityId="org.nyc.cir" businessId="ICE" version="1.0.2"/>
    <purpose language="en">New York City Immunization Calculation Engine (ICE)</purpose>
    <explanation language="en">String</explanation>
    <executionEngine>gov.nyc.health.ice.service.ICEDecisionEngineDSS55EvaluationAdapter</executionEngine>
    <dataModel>org.opencds.vmr^VMR^1.0</dataModel>
    <knowledgeModulePrimaryProcessName>PrimaryProcess</knowledgeModulePrimaryProcessName>
    <conceptDeterminationMethods>

        <primary>NYCICESchedule-Primary</primary>

        <additive>NYCICESchedule-Schools</additive>

        <additive>NYCICESchedule-NewFeature</additive>

        <replacing>NYCICESchedule-FIX</replacing>

    </conceptDeterminationMethods>

</kmMetadata>

For the above:

ICE 1.0.0 will instantiate concepts for any codes across all CDMs within the OpenCDS mapping files.
ICE 1.0.1 will map codes->concepts specified by the "NYCICESchedule-Primary" CDM only
ICE 1.0.2 will map codes->concepts specified by the NYCICESchedule-Primary, additional code->concepts for those mappings specified by "NYCICEShedule-Schools" and "NYCICESchedule-NewFeature". Additionally, any codes that have mappings in both "NYCICESchedule-FIX" AND "NYCICESchedule-Primary" will only be mapped to concepts as specified by the "NYCICESchedule-FIX" mappings; the "NYCICESchedule-Primary" code->concepts for those overlapping/same codes will not be applied.

For example, for the below 4 mapping files, the proposed functionality would work as follows:

org.nyc.cir.ICE.1.0.0 will apply all the concept mappings. The Drools Concept list will contain MMR, Measles, Mumps and Rubella.
org.nyc.cir.ICE.1.0.1 will only apply the first mapping, and therefore the Drools Concept List will only contain MMR.
org.nyc.cir.ICE.1.0.2 will only apply the last 3 mappings, and therefore the Drools Concept List will contain Measles, Mumps and Rubella, but not MMR.

<?xml version="1.0" encoding="UTF-8"?>
<OpenCdsConceptMappingSpecificationFile>
 <specificationNotes>Created manually.</specificationNotes>
 <openCdsConcept code="MMR" displayName="MMR"></openCdsConcept>
 <conceptDeterminationMethod code="NYCICESchedule-Primary" displayName="Best available OpenCDS concept determination method"></conceptDeterminationMethod>
 <membersForCodeSystem codeSystem="2.16.840.1.113883.12.292" codeSystemName="Vaccines administered (CVX)">
 <CD code="03" displayName="MMR" />
 </membersForCodeSystem>
</OpenCdsConceptMappingSpecificationFile>

<OpenCdsConceptMappingSpecificationFile>
 <specificationNotes>Created manually.</specificationNotes>
 <openCdsConcept code="Measles" displayName="Measles"></openCdsConcept>
 <conceptDeterminationMethod code="NYCICESchedule-FIX" displayName="Best available OpenCDS concept determination method"></conceptDeterminationMethod>
 <membersForCodeSystem codeSystem="2.16.840.1.113883.12.292" codeSystemName="Vaccines administered (CVX)">
 <CD code="03" displayName="MMR" />
 </membersForCodeSystem>
</OpenCdsConceptMappingSpecificationFile>

<OpenCdsConceptMappingSpecificationFile>
 <specificationNotes>Created manually.</specificationNotes>
 <openCdsConcept code="Mumps" displayName="Mumps"></openCdsConcept>
 <conceptDeterminationMethod code="NYCICESchedule-FIX" displayName="Best available OpenCDS concept determination method"></conceptDeterminationMethod>
 <membersForCodeSystem codeSystem="2.16.840.1.113883.12.292" codeSystemName="Vaccines administered (CVX)">
 <CD code="03" displayName="MMR" />
 </membersForCodeSystem>
</OpenCdsConceptMappingSpecificationFile>

<OpenCdsConceptMappingSpecificationFile>
 <specificationNotes>Created manually.</specificationNotes>
 <openCdsConcept code="Rubella" displayName="Rubella"></openCdsConcept>
 <conceptDeterminationMethod code="NYCICESchedule-FIX" displayName="Best available OpenCDS concept determination method"></conceptDeterminationMethod>
 <membersForCodeSystem codeSystem="2.16.840.1.113883.12.292" codeSystemName="Vaccines administered (CVX)">
 <CD code="03" displayName="MMR" />
 </membersForCodeSystem>
</OpenCdsConceptMappingSpecificationFile>