Configuration Schemas

Owned by Phillip Warner
Last updated: Aug 12, 2015
9 min read

OpenCDS Configuration schemas consist of a base schema and a REST schema.  The REST schema contains the elements that are used for physical configuration metadata (e.g., XML files).

Base Schema

<insert base schema ref here>

REST Schema

<insert rest schema ref here>

Schema Elements and Examples

The REST schema is the entry point for OpenCDS configuration, whether they exist as files on the filesystem or as objects in BerkeleyDB.  The main elements are as follows:

ConceptDeterminationMethods

ConceptDeterminationMethods consists of one or more ConceptDeterminationMethod elements.

This style of configuration may be used via the REST service or may exist on the filesystem (as in the 1.2.x and previous configuration).

An example ConceptDeterminationMethods is shown below:

ConceptDeterminationMethods Example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:conceptDeterminationMethods xmlns:ns2="org.opencds.dss.config.v1_0" xmlns:ns3="org.opencds.dss.config_rest.v1_0">
    <conceptDeterminationMethod code="C45" displayName="NQF" codeSystem="2.16.840.1.113883.3.795.12.1.1" version="1.0">
    ...
    </conceptDeterminationMethod>
    <conceptDeterminationMethod code="C267" displayName="AHRQ" codeSystem="2.16.840.1.113883.3.795.12.1.1" version="1.0">
    ...
    </conceptDeterminationMethod>
    <conceptDeterminationMethod code="C36" displayName="OpenCDS" codeSystem="2.16.840.1.113883.3.795.12.1.1" version="1.0">
    ...
    </conceptDeterminationMethod>
</ns3:conceptDeterminationMethods>

ConceptDeterminationMethod

ConceptDeterminationMethod contains concept mappings from local or standard concepts to OpenCDS concepts.  The concept mapping metadata is organized such that toConcept is the OpenCDS concept, while the associated concept elements within fromConcepts compose the local and standard concepts that may be expected in the vMR data.  When processing the vMR, for each of the local concepts found, OpenCDS will add the OpenCDS concept (the toConcept) to the internal fact lists.

Elements are described as follows:

  • conceptMapping - the element wrapping the overall mapping of local/standard concepts to OpenCDS concepts
  • toConcept - the OpenCDS concept to which all fromConcepts will map
  • fromConcepts - the wrapper element for local/standard concepts that are mapped to the OpenCDS concept; contains the codeSystem of the concepts (NOTE: multiple fromConcepts within the conceptMapping are supported, in order to support concepts from any number of codeSystems).
    • concept - the local/standard concept, within the codeSystem specified in the fromConcepts element.

 

This style of configuration may be used via the REST service or may exist on the filesystem (as in the 1.2.x and previous configuration).

An example ConceptDeterminationMethod is shown below:

ConceptDeterminationMethod Example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:conceptDeterminationMethod xmlns:ns2="org.opencds.dss.config.v1_0" xmlns:ns3="org.opencds.dss.config_rest.v1_0" code="C74" displayName="CDC-RD concept determination method" codeSystem="2.16.840.1.113883.3.795.12.1.1" version="1.0">
    <conceptMapping>
        <toConcept code="C88" codeSystem="2.16.840.1.113883.3.795.12.1.1" codeSystemName="OpenCDS concepts" displayName="Result Negative" />
        <fromConcepts codeSystem="2.16.840.1.113883.3.795.12.1.2" codeSystemName="OpenCDS proprietary local" displayName="Result Negative">
            <concept code="NEGATIVE" displayName="Result Negative" />
            <concept code="Negative" displayName="Result Negative" />
            <concept code="negative" displayName="Result Negative" />
            <concept code="NEG" displayName="Result Negative" />
            <concept code="Neg" displayName="Result Negative" />
            <concept code="neg" displayName="Result Negative" />
            <concept code="N" displayName="Result Negative" />
            <concept code="n" displayName="Result Negative" />
            <concept code="Invalid" displayName="Result Negative" />
            <concept code="Indeterminate" displayName="Result Negative" />
            <concept code="Inadequate" displayName="Result Negative" />
            <concept code="Not Detected" displayName="Result Negative" />
        </fromConcepts>
    </conceptMapping>
    <conceptMapping>
        <toConcept code="C273" codeSystem="2.16.840.1.113883.3.795.12.1.1" codeSystemName="OpenCDS concepts" displayName="Strep Pneumo Test For Organism" />
        <fromConcepts codeSystem="2.16.840.1.113883.3.795.12.1.2" codeSystemName="OpenCDS proprietary local" displayName="Streptococcus pneumoniae">
            <concept code="Strpne" displayName="Streptococcus pneumoniae" />
        </fromConcepts>
    </conceptMapping>
</ns3:conceptDeterminationMethod>

 

ExecutionEngines

ExecutionEngines consists of one or more ExecutionEngine elements.

This style of configuration may be used via the REST service or may exist on the filesystem (as in the 1.2.x and previous configuration).

ExecutionEngines Example
<?xml version="1.0" encoding="UTF-8"?>
<rest:executionEngines xsi:schemaLocation="org.opencds.dss.config_rest.v1_0 ../schema/OpenCDSConfigRest.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rest="org.opencds.dss.config_rest.v1_0">
    <!--include all supported executionEngine package names in this list, along with the operations they support -->
    <executionEngine>
	...
    </executionEngine>
    <executionEngine>
	...
    </executionEngine>
</rest:executionEngines>

ExecutionEngine

The ExecutionEngine metadata contains information about the rules engine adapter that should be used for rule processing.  Elements are as follows:

  • identifier - the identifier of the ExecutionEngine; this should be the fully-qualified class name of the adapter.
  • description - a free-form description of the ExecutionEngine
  • timestamp - the timestamp of metadata creation
  • userId - the user id of the user who created the metadata
  • supportedOperation - (may include more than one) describes the types of operations supported by the ExecutionEngine.

 

This style of configuration may be used via the REST service.

ExecutionEngine Example
<?xml version="1.0" encoding="UTF-8"?>
<rest:executionEngine xsi:schemaLocation="org.opencds.dss.config_rest.v1_0 ../schema/OpenCDSConfigRest.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rest="org.opencds.dss.config_rest.v1_0">
    <identifier>org.opencds.service.drools.v55.DroolsAdapter</identifier>
    <description>Drools 5.5 based adapter</description>
    <timestamp>2014-04-08T00:00:00</timestamp>
    <userId>Someone</userId>
    <supportedOperation>EVALUATION.EVALUATE</supportedOperation>
    <supportedOperation>EVALUATION.EVALUATE_AT_SPECIFIED_TIME</supportedOperation>
</rest:executionEngine>

 

KnowledgeModules

KnowledgeModules consists of one or more KnowledgeModule elements.

This style of configuration may be used via the REST service or may exist on the filesystem (as in the 1.2.x and previous configuration).

KnowledgeModules Example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:knowledgeModules xmlns:ns2="org.opencds.dss.config.v1_0" xmlns:ns3="org.opencds.dss.config_rest.v1_0">
    <knowledgeModule>
	...
    </knowledgeModule>
    <knowledgeModule>
	...
    </knowledgeModule>
</ns3:knowledgeModules>

 

KnowledgeModule

The KnowledgeModule element consists of metadata describing the KnowledgeModule.  Element descriptions are as follows:

  • identifier - the identifier of the KnowledgeModule, referenced by CDS requests.
  • status - the status of the KnowledgeModule
  • executionEngine - the identifier for the ExecutionEngine, used to cross-reference the ExecutionEngine metadata.
  • semanticSignifierId - the identifier for the SemanticSignifier, used to cross reference the SemanticSignifier metadata.
  • conceptDeterminationMethods - describes which Concept Determination Methods should be applied to incoming data, for concept mappings, before the data are processed by the rules engine.
    • primaryCDM - the primary Concept Determination Method to be used; must match the attributes of the given conceptDeterminationMethod in ConceptDeterminationMethod.
    • secondaryCDM - the secondary Concept Determination Method to be used; must match the attributes of the given conceptDeterminationMethod in ConceptDeterminationMethod.  Any number of secondaryCDM elements may be specified (0 to many).
      • The method attribute must be one of the following:
        • ADDITIVE - indicates that the list of concepts from the primary Concept Determination Method will be augmented by all concepts within the conceptMappings of the secondary Concept Determination Method.
        • REPLACEMENT - indicates that the list of concepts from the primary Concept Determination Method will be replaced by all matching concepts within the conceptMappings of the secondary Concept Determination Method.
          • Note: Only those concepts that are specified in the conceptMappings of the primaryCDM will be replaced.
          • Note: The replacement approach is last-one-wins, i.e., conceptMappings from the last secondaryCDM in the list, will take precedence over conceptMappings from all previous secondaryCDM elements (in the list).
  • package - the metadata describing the knowledge package containing the rules and other artifacts used by the rules engine.
    • packageType - the type of package (E.g., Drools accepts, .pkg, .bpmn2, and .drl).
    • packageId - the identifier used by OpenCDS to reference the package on the filesystem.
    • preload - indication to OpenCDS whether to preload the knowledge package on startup.
  • primaryProcess - the process name used by Drools (as specified in the BPMN2 process diagram).
  • preProcessPlugins - the list of pre-process plugins, which are applied before the data are sent to the rules engine.
    • preProcessPlugin - one or more may be specified; the attributes of each must match the attributes from the plugin identifier (see .
  • timestamp - the time when the metadata were created.
  • userId - the user id of the user who created/uploaded the KnowledgeModule.

 

This style of configuration may be used via the REST service.

KnowledgeModule Example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:knowledgeModule xmlns:ns2="org.opencds.dss.config.v1_0" xmlns:ns3="org.opencds.dss.config_rest.v1_0">
    <identifier scopingEntityId="org.opencds" businessId="NQF_0031_v1" version="1.1.1" />
    <status>APPROVED</status>
    <executionEngine>org.opencds.service.drools.v55.DroolsAdapter</executionEngine>
    <semanticSignifierId scopingEntityId="org.opencds.vmr" businessId="VMR" version="1.0" />
    <conceptDeterminationMethods>
        <primaryCDM code="C2511" codeSystem="2.16.840.1.113883.3.795.12.1.1" displayName="HEDIS 2014" version="1.0" />
        <secondaryCDM code="C36"  codeSystem="2.16.840.1.113883.3.795.12.1.1" displayName="OpenCDS" version="1.0" method="ADDITIVE" />
    </conceptDeterminationMethods>
    <package>
        <packageType>PKG</packageType>
        <packageId>org.opencds^NQF_0031_v1^1.1.1.pkg</packageId>
        <preload>false</preload>
    </package>
    <primaryProcess>PrimaryProcess</primaryProcess>
    <preProcessPlugins>
        <preProcessPlugin version="0.1" businessId="EncountersFromProblemAndProcedureConcepts" scopingEntityId="org.opencds.plugin" />
    </preProcessPlugins>
    <timestamp>2014-07-30T13:21:46.772-06:00</timestamp>
    <userId>Someone</userId>
</ns3:knowledgeModule>

 

SemanticSignifiers

SemanticSignifiers consists of one or more SemanticSignifier elements.

This style of configuration may be used via the REST service or may exist on the filesystem (as in the 1.2.x and previous configuration).

SemanticSignifiers Example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:semanticSignifiers xmlns:ns2="org.opencds.dss.config.v1_0" xmlns:ns3="org.opencds.dss.config_rest.v1_0">
    <semanticSignifier>
	...
    </semanticSignifier>
</ns3:semanticSignifiers>

 

SemanticSignifier

The SemanticSignifier element describes the external model of the vMR data that will enter the system.  These elements describe how the system should process the incoming vMR data:

  • identifier - the identifier of the SemanticSignifier
  • name - a human-readable name of the identifier (typically a ^-delimited combination of the identifier attributes)
  • description - free-form description of the SemanticSignifier
  • xsdComputableDefinition
    • xsdRootGlobalElementName - the global element name of the schema
    • xsdURL - the pathname of the schema implementation (e.g., the package name of the JAXB classes)
  • entryPoint - the entry point used by OpenCDS to transform the incoming data into the internal model.
  • exitPoint - the exit point used by OpenCDS to transform the outgoing data into the external model.
  • timestamp - the timestamp of creation
  • userId - the user id of the user who created the metadata instance.

 

This style of configuration may be used via the REST service.

SemanticSignifier Example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:semanticSignifiers xmlns:ns2="org.opencds.dss.config_rest.v1_0" xmlns:ns3="org.opencds.dss.config.v1_0">
    <semanticSignifier>
        <identifier scopingEntityId="org.opencds.vmr" businessId="VMR" version="1.0" />
        <name>org.opencds.vmr^VMR^1.0</name>
        <description>org.opencds.vmr^VMR^1.0</description>
        <xsdComputableDefinition>
            <xsdRootGlobalElementName>CDSInput</xsdRootGlobalElementName>
            <xsdURL>org.opencds.vmr.v1_0.schema</xsdURL>
        </xsdComputableDefinition>
        <entryPoint>org.opencds.vmr.v1_0.schema.CDSInput</entryPoint>
        <exitPoint>org.opencds.vmr.v1_0.mappings.out.CdsOutputModelExitPoint</exitPoint>
        <factListsBuilder>org.opencds.vmr.v1_0.mappings.in.CdsInputFactListsBuilder</factListsBuilder>
        <resultSetBuilder>org.opencds.vmr.v1_0.mappings.out.CdsOutputResultSetBuilder</resultSetBuilder>
        <timestamp>2014-11-03T15:24:57.212-07:00</timestamp>
        <userId>userId</userId>
    </semanticSignifier>
</ns2:semanticSignifiers>

SupportingData

The SupportingData element consists of metadata describing the SupportingData.  Element descriptions are as follows:

  • identifier - the identifier of the KnowledgeModule, referenced by CDS requests.
  • kmId - the KnowledgeModule identifier to which this SupportingData is associated.
  • package - the metadata describing the SupportingData package containing data to support rule processing.
    • packageType - the type of package.
    • packageId - the identifier used by OpenCDS to reference the SupportingData package on the filesystem.
    • preload - (optional) indication to OpenCDS whether to preload the SupportingData package on startup.
  • loadedBy - the plugin that is used to load the supporting data and prepare it for use within the system.  Attributes MUST match the attributes of a valid plugin identifier specified in the PluginPackage. (Implementation is currently incomplete.  Will be updated via OP-41 - Getting issue details... STATUS .)
  • timestamp - the time when the metadata were created.
  • userId - the user id of the user who created/uploaded the KnowledgeModule.

For a discussion of the SupportingData element, please refer to Automated Deployment of Knowledge to OpenCDS - Scenarios.

SupportingData Example
<?xml version="1.0" encoding="UTF-8"?>
<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>identifier</identifier>
    <kmId businessId="edu.utah" scopingEntityId="SCIP_VTE_2" version="2014.0.0" />
    <package>
        <link rel="self" href="http://opencds.org/nowhere" />
        <packageType>packageType</packageType>
        <packageId>packageId</packageId>
    </package>
    <loadedBy version="0.1" businessId="SupportingDataLoaderPlugin" scopingEntityId="custom.plugin"/>
    <timestamp>2001-12-31T12:00:00</timestamp>
    <userId>userId</userId>
</rest:supportingData>

PluginPackages

The PluginPackages element describes a list of plugins used in both pre- and post-processing.

PluginPackages Example
<?xml version="1.0" encoding="UTF-8"?>
<rest:pluginPackages xsi:schemaLocation="org.opencds.dss.config_rest.v1_0 ../schema/OpenCDSConfigRest.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rest="org.opencds.dss.config_rest.v1_0">
    <pluginPackage>
	...
    </pluginPackage>
</rest:pluginPackages>

PluginPackage

The PluginPackage describes the metadata describing the PluginPackages to be used in both pre- and post-processing.  These elements describe how the system should find and load the plugin:

  • identifier - the identifier of the PluginPackage, referenced by the system.
  • loadContext - indicates to the system where to find the plugin.  Values are restricted to the following:
    • CLASSPATH - the system should find the package resource on the Java CLASSPATH
    • IMPORTED - (To be implemented in the future.) the system should find the resource in the configuration folders.
  • resourceName - the name of the resource in the location specified in loadContext.  This name will (currently) be the name of a jar file.
  • plugins - the list of plugins contained in the plugin package
    • plugin - the plugin metadata, described by the following elements:
      • identifier - the identifier of the plugin, used as a reference by the system in order to obtain the className of the plugin.
      • className - the class name of the plugin.
  • timestamp - the time when the metadata were created.
  • userId - the user id of the user who created/uploaded the PluginPackage.

This style of configuration may be used via the REST service or may exist on the filesystem (as in the 1.2.x and previous configuration).

PluginPackages Example
<?xml version="1.0" encoding="UTF-8"?>
<rest:pluginPackage xsi:schemaLocation="org.opencds.dss.config_rest.v1_0 ../schema/OpenCDSConfigRest.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rest="org.opencds.dss.config_rest.v1_0">
        <identifier version="1.3.0-SNAPSHOT" businessId="opencds-plugin-encounters" scopingEntityId="org.opencds.plugin" />
        <loadContext>CLASSPATH</loadContext>
        <resourceName>opencds-plugin-encounters-1.3.0-SNAPSHOT.jar</resourceName>
        <plugins>
            <plugin>
                <identifier version="0.1" businessId="EncountersFromProblemAndProcedureConcepts" scopingEntityId="org.opencds.plugin" />
                <className>org.opencds.plugin.EncountersFromProblemAndProcedureConcepts</className>
            </plugin>
        </plugins>
        <timestamp>2014-10-13T22:39:00</timestamp>
        <userId>userId</userId>
</rest:pluginPackage>