KIE and Terminology (ApelonDTS)

Attribution...

This document is heavily based on Guvnor and Terminology (ApelonDTS) written by Phillip Warner.

OpenCDS Apelon Services

OpenCDS provides a web application that provides a service that will generate content for building KIE and/or Guvnor Enumerations.

This service (deployed as a war file) is typically deployed as a web application in any Java EE container (Tomcat, JBoss, etc.).

The service also provides caching of values from ApelonDTS in order to improve the performance between KIE and ApelonDTS.  The cache is refreshed on a regular basis (as defined in the configuration–see below), or may be refreshed on-demand by accessing the URL:

http://localhost:8080/opencds-apelon/apelonDtsRefreshService

NOTE: Modify the host and port of the above URL to adapt it to the hostname and port of the container on which the service is deployed.

Configuration

This service requires a number of configuration values to function properly.  These configuration values should be placed in a properties file in the following location:

• Linux/UNIX/MacOS-based systems: $HOME/.opencds/opencds-apelon.properties
• Windows: %HOME%\.opencds\opencds-apelon.properties

Configuring the service

apelon.host=<ApelonDTS Host>
apelon.port=<ApelonDTS Port>
apelon.username=<username>
apelon.password=<password>
apelon.namespace=OpenCDS
concept.refresh.cron.value=0 0 0 * * ?

The above properties must be modified to support your local configuration.

The refresh interval may be modified (the above value is for a daily refresh at midnight).  See http://quartz-scheduler.org/api/2.2.0/org/quartz/CronTrigger.html for additional configuration values.

VMREnumerationsClient Configuration

VMREnumerationsClient also requires a configuration file or system property, as follows:

guvnor.vmrenumerations.service.url=http://localhost:8080/opencds-apelon/apelonDtsService

Modify the host and/or port as per your configuration.  This file should exist in the same location as the opencds-apelon.properties–namely:

• Linux/UNIX-based systems: $HOME/.opencds/opencds-guvnor.properties
• Windows-based systems: %HOME%\.opencds\opencds-guvnor.properties

The property name, as shown above, is:

guvnor.vmrenumerations.service.url

This property and its value will need to be provided either:

• as a System property, i.e.,

  -Dguvnor.vmrenumerations.service.url=...

  provided on the Java command-line (for the container or otherwise), or

• in the configuration file $HOME/.opencds/opencds-guvnor.properties or %HOME%\.opencds\opencds-guvnor.properties

PLEASE NOTE:

• A failure to provide this option will cause VMREnumerationsClient startup to fail. 
• Do NOT change the letters "guvnor" in any of the above configuration or property files to "kie" as that will also cause it to fail. 
• A single instance of this service can support multiple instances of both Guvnor and KIE...

KIE Enumerations and opencds-apelon

KIE enumerations can be found in the Enumerations section of a package, as shown below:

KIE enumerations may be created manually, as shown in the image below:

or they may be retrieved dynamically as shown in the example for "GenderConcept" here:

by using the tools provided in OpenCDS (they are found in opencds-common.jar).  In order to do this, the following steps are required:

1. Add the opencds-common.jar to the KIE war.

   1. for a Unix-based system (easily adapted to Windows Console or PowerShell):

      mkdir WEB-INF/lib/
      mv opencds-common.jar WEB-INF/lib 
      jar -uvf <kie.war> WEB-INF/lib/opencds-common.jar

   2. For Windows Use a tool such as Windows Explorer or others:
      1. change the name of the archive from .war to .zip
      2. open the newly created zip file
      3. add opencds-common.jar to the WEB-INF/lib/ folder in the archive
      4. navigate out of the zip file archive
      5. on the Command Prompt or PowerShell, rename the file from opencds-common.zip to opencds-common.war
         1. Windows Explorer doesn't seem to easily allow renaming extensions (a Windows expert might know differently)
      6. Windows expert says:
         
         1. click on the file name in windows explorer, and wait a moment.  It will usually highlight the the name minus the extension after a second or two.
         2. then do either of the following:
            
            1. Use the mouse to double-click on the extension alone which will highlight it and you can then retype it as "war", or
            2. Use keyboard navigation keys together with judicious use of the shift key to highlight the extension and retype it to "war"
2. Once the war has been updated, the service must be redeployed.  See your container documentation for deploying/redeploying war files.
   1. E.g., for Tomcat this is simply deleting the war and the exploded folder of the same name in the webapps folder, then copying the newly updated archive into the webapps folder.

Once the jar has been added to the KIE war, the next step is integration. 

The Fact column in the table is the list of fact concept names that are to be supported by this installation of OpenCDS.  The publicly accessible OpenCDS Apelon DTS instance currently contains a fully specified set of Facts for HL7 vMR 1.0, and will be expanded in the near future to include a similar fully specified set of Facts for HL7 FHIR, once HL7 FHIR is balloted to a normative version.

Each Fact having a dynamic enumeration is then updated to include the following pair of lines as the Context for the "determinationMethodCode" and the "openCdsConceptCode", respectively.  Both lines are required for a particular Fact, since OpenCDS has a robust system for selecting a specific valueset of mappings based on the combination of a selected "determinationMethodCode", and the "openCdsConceptCode".  The "determinationMethodCode" will return the list of opencds concept codes stored in Apelon for all the concept determination methods that are supported, and the "openCdsConceptCode" will return the list of opencds concept codes stored in Apelon for various concepts relevant to the named Fact. 

This is done by updating the value of the enumerations to the following in the Context column:

(new org.opencds.common.terminology.VMREnumerationsClient()).getOpenCdsConcepts("determinationMethod")
(new org.opencds.common.terminology.VMREnumerationsClient()).getOpenCdsConcepts("<fact-attribute-name>")

as shown in the image below:

When it is invoked, the VMREnumerationsClient will call the opencds-apelon web service to obtain the concepts relevant to the argument.

VMREnumerationsClient

VMREnumerationsClient supports the following operations, each of which returns a list of Strings:

• getOpenCdsConcepts("calendarUnit")
  • Retrieves supported calendar units.

  • Example response:

    [1=year(s), 2=month(s), 3=week(s), 5=day(s), 11=hour(s), 12=minute(s), 13=second(s)]

• getOpenCdsConcepts("all")
  • Retrieves all concepts and assertions

  • Example response:

    [C1341=(metered Dose) Inhaler, C1342=1 Hour, C1340=100, C1343=2 Hours, C1344=3 Hours, C1345=4 Hours, C1346=5 Hours, C1347=6 Hours, C1348=7 Hour, C1349=8 Hours, C450=AHRQ PSI-10 PostOp Phys. Metab. Derangement, C440=AHRQ PSI-11 Resp. Failure, ... ]

• getOpenCdsConcepts("assertion")

  • Retrieves all assertions

  • Example reponse:

    [C2531=Alpha-glucosidase inhibitors, C2550=Amputation, Lower Extremity, C2533=Amylin analogs, ... ]

• getOpenCdsConcepts("determinationMethod")
  • Alternate name: "conceptDeterminationMethod"

  • Retrieves the list of supported Determination Methods within the ApelonDTS service

  • Example response:

    [C267=AHRQ v4.3, C464=AHRQ v4.4, C265=Best Available, C263=HEDIS 2011, C264=HEDIS 2012, C2511=HEDIS 2014, C494=NHIQM 2013, C45=NQF, C36=OpenCDS, C74=Reportable Disease]

• getOpenCdsConcepts("<concept type>")
  • clinicalStatementRelationship

    • Example response:

      [C877=Associated with, C438=Discharge Dx, C439=Dx POA, C405=Part of, C406=Parts include]