Exporting a Knowledge Module to OpenCDS - File-Based

Owned by Phillip Warner
Last updated: Aug 13, 2015
5 min read

(Needs validation) 

 

 


Exporting a Knowledge Module to OpenCDS is currently a manual process.

The configuration location for OpenCDS is in a folder specified within the OpenCDS base properties file:

    1. $HOME/.opencds/opencds.properties
    2. %HOME%\.opencds\opencds.properties on Windows (deployed as a user)
    3. C:\.opencds\opencds.properties (deployed as a Windows service)
    4. As specified as a server flag (see example configuration for details–TBD)

Configuration Overview

The current configuration requires understanding of the following folder hierarchy:

  • conceptDeterminationMethods
    • cdm.xml
      • file containing concept mappings from local or standard terminologies to OpenCDS concepts (or concepts expected by the rules that have been developed).
      • See ConceptDeterminationMethods
  • executionEngines.xml
    • file specifying the execution engines available to OpenCDS.  The default execution engine is Drools 5.5.
    • See ExecutionEngines
  • knowledgeModules.xml
  • knowledgePackages
    • Location of source (DRL) or binary package (PKG) exported from Guvnor.
  • plugins
  • semanticSignifiers.xml
    • Used to define which semantic models (vMR, FHIR, etc.) are supported by the system.
    • This file should not need to be modified except in certain cases.
    • See SemanticSignifiers
  • supportingData
    • Location for supporting data metadata (configuration) files.
    • See SupportingData
    • packages
      • Location of supporting data packages.

Export/Import Process

Add a New Knowledge Module

The steps for importing a Knowledge Module into OpenCDS are as follows:

  1. Add or update the concept mappings in the cdm.xml file (see Concept Mappings).
  2. Export the knowledge module from Guvnor and place the downloaded binary package (or the DRL file, if using a single DRL) into the knowledgePackages folder (see Configuration Overview).  After building the package as is described here, download the binary (or DRL) and place it inside of knowledgeModules folder.
  3. Add an entry for the new knowledge module to the knowledgeModules.xml file (see Knowledge Modules).
  4. Add any Supporting Data configuration and files (see Supporting Data).
  5. Restart OpenCDS or call the reload URL.

Update an Existing Knowledge Module

  1. Export the knowledge module from Guvnor and replace the existing module, ensuring the file name is consistent with the previous instance (see Configuration Overview).  Place it into the knowledgeModules folder.
  2. If necessary, update the entry for the knowledge module in the knowledgeModules.xml file (see Knowledge Modules).
  3. If necessary, add or update any Supporting Data configuration and files (see Supporting Data).
  4. Restart OpenCDS or call the reload URL.

Concept Mappings

Concept mappings are specified in the cdm.xml file (other names may be used, as OpenCDS scans the conceptDeterminationMethods folder for concept mappings.

A description of the XML format is as follows:

  • The conceptDeterminationMethod is used to group conceptMappings into logical sets that can be combined with other conceptDeterminationMethods within the knowledge module configuration.
  • The toConcept is the target concept that will be used by the knowledge module.
  • The fromConcepts contains the list of local or standard concepts used in the data being sent to OpenCDS.

The following is a snippet from an example cdm.xml file:

Snippet from cdm.xml file
    <conceptDeterminationMethod code="C2511" displayName="HEDIS 2014" codeSystem="2.16.840.1.113883.3.795.12.1.1" version="1.0">
        <conceptMapping>
            <toConcept codeSystem="2.16.840.1.113883.3.795.12.1.1" codeSystemName="OPENCDS_CONCEPTS" code="C2787" displayName="HEDIS-Other Emphysema"/>
            <fromConcepts codeSystem="2.16.840.1.113883.6.103" codeSystemName="ICD9CM" displayName="Interstitial emphysema">
                <concept code="518.1" displayName="Interstitial emphysema"/>
                <concept code="518.2" displayName="Compensatory emphysema"/>
            </fromConcepts>
        </conceptMapping>
		…

Knowledge Modules

OpenCDS uses the knowledgeModules.xml file to read to configure the knowledge module.  Required and optional components are as follows:

  • identifier - REQUIRED - the identifier will be used to load the knowledge module during the evaluation request, and is specified in the DSS message.
  • executionEngine - REQUIRED - the execution engine is the module that loads the knowledgeModule and processes the incoming data.  This element references the execution engine specified in the executionEngines.xml file.
  • conceptDeterminationMethods - REQUIRED - specifies which concept determination methods will be used to transform the incoming concepts to those that are used by the knowledge module (e.g., a local concept to an OpenCDS concept).
    • primaryCDM - REQUIRED - a knowledge module requires a primary concept determination method
    • secondaryCDM - OPTIONAL - any number of secondary concept determination methods may be specified; the method attribute specifies the relationship of the secondary concepts to the primary concepts (ADDITIVE or REPLACEMENT).
  • package - REQUIRED - specifies the package to load for KM processing
    • packageType - REQUIRED - the type of package to load; the default execution engine allows either DRL or PKG files.
    • packageId - REQUIRED - this is the name of the package file.
    • preload - REQUIRED 
      • true - indicates the package will be loaded when the configuration is loaded (or reloaded)
      • false - indicates the package will be loaded when data are first sent to OpenCDS
  • preProcessPlugins - OPTIONAL - specifies the plugins that will be used before the data are evaluated by the execution engine.
  • postProcessPlugins - OPTIONAL - specified the plugins that will be used after the data are evaluated by the execution engine.
  • timestamp - REQUIRED - used to indicate when the KM was added to the system (or modified)
  • userId - REQUIRED - the user who added or modified the KM

An example KM configuration is shown below:

Example: knowledgeModules.xml
    <knowledgeModule>
        <identifier scopingEntityId="edu.utah" businessId="HEDIS_W34" version="2015.0.0" />
        <status>APPROVED</status>
        <executionEngine>Drools 5.5 Adapter</executionEngine>
        <semanticSignifierId scopingEntityId="org.opencds.vmr" businessId="VMR" version="1.0" />
        <conceptDeterminationMethods>
            <primaryCDM code="C3391" codeSystem="2.16.840.1.113883.3.795.12.1.1" displayName="HEDIS 2015" version="1.0" />
            <secondaryCDM code="C36" codeSystem="2.16.840.1.113883.3.795.12.1.1" displayName="OpenCDS" version="1.0" method="ADDITIVE" />
            <secondaryCDM code="C3414" codeSystem="2.16.840.1.113883.3.795.12.1.1" displayName="HEDIS UUHC" version="1.0" method="ADDITIVE"/>
            <secondaryCDM code="C3419" codeSystem="2.16.840.1.113883.3.795.12.1.1" displayName="HEDIS 2015 Medications" version="1.0" method="ADDITIVE"/>
        </conceptDeterminationMethods>
        <package>
            <packageType>PKG</packageType>
            <packageId>edu.utah.HEDIS.v2015_0.W34.pkg</packageId>
            <preload>true</preload>
        </package>
        <primaryProcess>PrimaryProcess</primaryProcess>
        <preProcessPlugins>
            <preProcessPlugin version="0.1" businessId="EncountersFromProblemAndProcedureConcepts" scopingEntityId="org.opencds.plugin" />
        </preProcessPlugins>
        <postProcessPlugins>
            <postProcessPlugin version="0.1" businessId="PrintObjects" scopingEntityId="org.opencds.plugin" />
        </postProcessPlugins>
        <timestamp>2014-10-16T07:42:09.815-06:00</timestamp>
        <userId>phillip</userId>
    </knowledgeModule>
	…
</ns2:knowledgeModules>

The knowledge module metadata is used by OpenCDS to determine which knowledge module will be used for processing the vMR input.

Supporting Data

The following example of concepts-supportingData.xml file point out to a concepts.txt file where the supported concepts are listed. 

Example: concepts-supportingData.xml
<rest:supportingData xmlns:config="org.opencds.dss.config.v1_0" xmlns:rest="org.opencds.dss.config_rest.v1_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="org.opencds.dss.config_rest.v1_0 ../schema/OpenCDSConfigRest.xsd ">
    <identifier>concepts</identifier>
    <package>
        <packageType>properties</packageType>
        <packageId>concepts.txt</packageId>
    </package>
    <loadedBy version="0.1" businessId="Assertions" scopingEntityId="org.opencds.plugin"/>
    <timestamp>2015-02-12T15:44:00</timestamp>
    <userId>Phillip</userId>
</rest:supportingData>
Example: concepts.txt
C2361=Injection
C238=Inpatient Encounter
C239=Emergency Department Encounter
C2504=something something something
C2556=Provider Eye Care Professional
C2557=Performer
C2559=Blood Pressure, Diastolic
C2560=Blood Pressure, Systolic
C257=Influenza Species
C258=Chlamydia Species
C259=Strep Pneumo Species
C260=Salmonella Species
C261=Influenza Test ForOrganism
C262=Influenza Test PosNeg
C2680=Comprehensive Well-Care
…