DRAFT
Overview
This document describes the OpenCDS Configuration for version 1.3.x and above.
What's new?
- Dedicated schemas for describing configuration metadata.
- Migration tool to migrate configuration schema from the previous version (1.2.x, 1.1.x, etc.) to the new version.
- REST interface for adding/updating and retrieving the configuration metadata
- including reloadability of File-based configuration.
- Backwards compatibility with ClassPath- and File-based configuration.
- NOT compatible with previous schemas; migration is required.
- New backend configuration scheme using BerkeleyDB (BDB-JE).
- This is the only method that is supported via REST.
Schemas
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 Discussion
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.
<?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 fromConcepts compose the local and standard concepts that are contained in the vMR data. For each of the local concepts found, OpenCDS will add the OpenCDS concept (the toConcept) to the internal fact lists.
An example ConceptDeterminationMethod is shown below:
<?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.
<?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.
<?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
<?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
<?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 />
<package>
<packageType>PKG</packageType>
<packageId>org.opencds^NQF_0031_v1^1.1.1.pkg</packageId>
<preload>false</preload>
</package>
<primaryProcess></primaryProcess>
<timestamp>2014-07-30T13:21:46.772-06:00</timestamp>
<userId>phillip</userId>
</ns3:knowledgeModule>
SemanticSignifiers
SemanticSignifier
Examples
<insert examples refs here>
Backend
The OpenCDS backend is configured using one of three methods: Classpath, Filesystem and BDB. The choice of configuration strategy is made within the opencds.properties file (see OpenCDS RunTime Installation Guide for details).
Classpath
This configuration option is most useful when initially evaluating OpenCDS. (As an aside, we also use this option for our continuous builds for functional testing purposes.)
When OpenCDS is configured using the Classpath-based configuration, it will look for the configuration files contained in a .jar file in the main .war file. The opencds.properties file must contain the following lines to enable this configuration strategy:
knowledge-repository.type=CLASSPATH knowledge-repository.path=resources_v1.3
Filesystem
When OpenCDS is configured using the Filesystem-based configuration, it will look for the configuration files in a folder specified by the knowledge-repository-path option in the opencds.properties file. The opencds.properties file must contain the following lines to enable this configuration strategy:
knowledge-repository.type=SIMPLE_FILE knowledge-repository.path=<path_to_resources_v1.3>
Examples of "path_to_resources_v1.3" include:
- C:/opencds-knowledge-repository-data/resources_v1.3
- (Note the forward-slashes for Windows-based systems)
- /home/opencds/knowledge-repository-data/resources_v1.3
BDB
When OpenCDS is configured using the BDB-based configuration, it will look for configuration in the BDB database in the store folder within the folder specified by the knowledge-repository-path. The opencds.properties file must contain the following lines to enable this configuration strategy:
knowledge-repository.type=STORE knowledge-repository.path=<path_to_store>
If the store folder does not exist, OpenCDS will create it at startup. Please note, however, as this will be a new store, OpenCDS will contain no configuration at all; the Migration tool or the REST Client (see below for each) may be used to upload the configuration metadata to OpenCDS.
Additionally, the folder specified by knowledge-repository.path will also contain two other folders (in addition to store; also created by OpenCDS if they do not exist):
knowledgePackagessupportingData
These folders will contain the binary knowledge packages (e.g., from Guvnor), and any supporting data which will be used by OpenCDS (the implementation of which will be implemented at a later date) before passing the data into the inferencing engine. These files are not stored in BDB in order to keep the database size to a minimum.
Security
The backend configuration also requires a security file, which contains the username and passwords for each user and the roles for each...
REST API
Security
Methods
Configuration API (REST) Version 1.0