(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-decision-support-service war (v1.1.5), or
- Specified in the OpenCDS base properties file:
- $HOME/.opencds/opencds.properties
- %HOME%\.opencds\opencds.properties on Windows (deployed as a user)
- C:\.opencds\opencds.properties (deployed as a service)
- As specified as a server flag (see example configuration for details–TBD)
Configuration Overview
The current configuration requires the following folder hierarchy:
- conceptMappingSpecifications
- autoGeneratedMappings
- folder containing auto-generated concept mappings
- manualMappings
- folder containing manually created concept mappings
- autoGeneratedMappings
- knowledgeModules
- folder containing knowledge modules exported from Guvnor (or other systems that generate knowledge packages)
- resourceAttributes
- folder containing OpenCDS configuration resources
- knowledgeModules.xml
- used for knowledge module metadata, for knowledge modules contained in the knowledgeModules folder (see above)
- openCDSCodeSystems.xml
- used to define the Code Systems supported by OpenCDS
- openCdsExecutionEngines.xml
- used to define which inferencing engines should be available to/used by OpenCDS
- This file should not need to be modified except in certain cases.
- semanticSignifiers.xml
- Used to define which vMR versions are supported by the system.
- This file should not need to be modified except in certain cases.
- supportedConceptsConfigFile.xml
- Used to indicate the supported concept for each OpenCDS Concept Type. (Unused during runtime.)
Concept Mappings
Concept mappings group ConceptDeterminationMethods with a Code System and the Codes within that Code System. Three examples are provided in the snippets below.
Auto-generated Concept Mapping
<OpenCdsConceptMappingSpecificationFile>
<specificationNotes>Created using ApelonConceptMappingSpecificationFileCreator.</specificationNotes>
<openCdsConcept code="C60" displayName="Hysterectomy"></openCdsConcept>
<conceptDeterminationMethod code="C45" displayName="NQF"></conceptDeterminationMethod>
<membersForCodeSystem codeSystem="2.16.840.1.113883.6.12" codeSystemName="CPT4">
<CD code="51925" displayName="Closure of vesicouterine fistula; with hysterectomy [51925]"></CD>
<CD code="58150" displayName="Total abdominal hysterectomy (corpus and cervix), with or without removal of tube(s), with or without removal of ovary(s) [58150]"></CD>
</membersForCodeSystem>
…
</OpenCdsConceptMappingSpecificationFile>
Manual Mapping Example
<OpenCdsConceptMappingSpecificationFile>
<specificationNotes>Created manually from AHRQ PSI specifications.</specificationNotes>
<openCdsConcept code="C295" displayName="Medical Discharge DRGs" />
<conceptDeterminationMethod code="C267" displayName="AHRQ" />
<membersForCodeSystem codeSystem="2.16.840.1.113883.12.416" codeSystemName="DRG">
<CD code="009" displayName="SPINAL DISORDERS AND INJURIES" />
<CD code="010" displayName="NERVOUS SYSTEM NEOPLASMS W/ CC" />
</membersForCodeSystem>
</OpenCdsConceptMappingSpecificationFile>
Manual Concept Mapping Example
<openCdsConceptMappingSpecificationFile>
<specificationNotes>Codes from Appendix A.1 ICD-9-CM Code Table 5.22 from the Specifications Manual for National Hospital Inpatient Quality Measures
Discharges 01-01-13 (1Q13) through 12-31-13 (4Q13)</specificationNotes>
<openCdsConcept code='C502' displayName='Elective Hip Replacement' />
<conceptDeterminationMethod code='C494' displayName='NHIQM 2013' />
<membersForCodeSystem codeSystem='2.16.840.1.113883.6.104' displayName='ICD9CM procedures'>
<CD code='00.70' displayName='Revision of hip replacement, both acetabular and femoral components' />
<CD code='00.71' displayName='Revision of hip replacement, acetabular component' />
<CD code='00.72' displayName='Revision of hip replacement, femoral component' />
<CD code='00.73' displayName='Revision of hip replacement, acetabular liner and/or femoral head only' />
<CD code='00.77' displayName='Hip bearing surface, ceramic-on-polyethylene' />
<CD code='00.85' displayName='Resurfacing hip, total, acetabulum and femoral head' />
<CD code='00.86' displayName='Resurfacing hip, partial, femoral head' />
<CD code='00.87' displayName='Resurfacing hip, partial, acetabulum' />
<CD code='81.51' displayName='Total hip replacement' />
<CD code='81.52' displayName='Partial hip replacement' />
<CD code='81.53' displayName='Revision of hip replacement, not otherwise specified' />
</membersForCodeSystem>
</openCdsConceptMappingSpecificationFile>
Resource Attributes
OpenCDS Code Systems
Example: openCDSCodeSystems.xml
<tcs:codeSystems xsi:schemaLocation="org.opencds.term.codeSystem ..\schema\OpenCDSCodeSystems.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:tcs="org.opencds.term.codeSystem"> <codeSystem codeSystemOID="2.16.840.1.113883.6.12" codeSystemDisplayName="CPT4" apelonNamespaceName="CPT" isApelonOntylog="false" /> … </tcs:codeSystems>
Supported Concepts
Example: supportedConceptsConfigFile.xml
<SupportedOpenCdsConceptsConfigFile>
<supportedConceptsForType>
<openCdsConceptType>conceptDeterminationMethod</openCdsConceptType>
<supportedOpenCdsConcept>
<openCdsConcept code="C265" displayName="UUHC"></openCdsConcept>
</supportedOpenCdsConcept>
…
</supportedConceptsForType>
<supportedConceptsForType>
<openCdsConceptType>gender</openCdsConceptType>
<supportedOpenCdsConcept>
<openCdsConcept code="C404" displayName="Other or Unknown Gender"></openCdsConcept>
</supportedOpenCdsConcept>
…
</supportedConceptsForType>
…
</SupportedOpenCdsConceptsConfigFile>
Knowledge Modules
Example: knowledgeModules.xml
<kmm:kmMetadataList xsi:schemaLocation="org.opencds.km.metadata.v1_0 ..\schema\OmgDssKmMetadata.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:kmm="org.opencds.km.metadata.v1_0">
<kmMetadata>
<identifier scopingEntityId="edu.utah" businessId="SCIP_VTE_2" version="2014.0.0" />
<purpose language="en">SCIP VTE Rule</purpose>
<explanation language="en">some explanation of the KM</explanation>
<executionEngine>org.opencds.service.drools.v55.DroolsAdapter</executionEngine>
<dataModel>org.opencds.vmr^VMR^1.0</dataModel>
<knowledgeModulePrimaryProcessName>PrimaryProcess</knowledgeModulePrimaryProcessName>
</kmMetadata>
…
</kmm:kmMetadataList>
The knowledge module metadata is used by OpenCDS to determine which knowledge module will be used for processing the vMR input.
Two important pieces of information are critical: the identifier element and the knowledgeModulePrimaryProcessName element.
The attributes of the identifier element must match the file name of the knowledge module. E.g., for the identifier in the example above, the file name of the knowledge module will be
edu.utah^SCIP_VTE_2^2014.0.0.pkg
The knowledgeModulePrimaryProcessName must be consistent with the name attribute of the process tag in the bpmn2 file (the asset in the Processes section of Guvnor).
All other fields (with the exception of purpose and explanation, should remain the same.
Export/Import Process
The steps for importing a Knowledge Module into OpenCDS are are as follows:
- If you are using new concepts, add them to the relevant folder within the conceptMappingsSpecifications folder (see Concept Mappings).
- If your Knowledge Module supports one or more Code Systems that are not currently specified in OpenCDS configuration, add them to openCDSCodeSystems.xml (see OpenCDS Code Systems).
- New Knowledge Module
- Export the knowledge module from Guvnor and place the downloaded binary package into the knowledgeModules folder (see Configuration Overview).
- Add an entry for the new knowledge module in knowledgeModules.xml (see Knowledge Modules).
- Replacing an Existing Knowledge Module
- Export the knowledge module from Guvnor and replace the existing module, ensuring the file name is consistent with the previous instance (see Configuration Overview).
- Restart OpenCDS (v1.1.5 and earlier).