OpenCDS Apelon Services

OpenCDS provides a web application that provides a service that will generate content for building 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 Guvnor 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:

 

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:

 

The property name, as shown above, is:

guvnor.vmrenumerations.service.url

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

PLEASE NOTE: A failure to provide this option will cause VMREnumerationsClient startup to fail.

Guvnor Enumerations and opencds-apelon

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

 

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

 

or they may be retrieved dynamically using the tools provided in OpenCDS–specifically opencds-common.jar.  In order to do this, the following steps are required:

  1. Add the opencds-common.jar to the Guvnor 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 <guvnor.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 Guvnor war, the next step is integration.  This is done by updating the value of the enumerations to the following:

(new org.opencds.common.terminology.VMREnumerationsClient()).getOpenCdsConcepts("determinationMethod")

as shown in the image below:

 

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: