DRAFT

Overview

This document describes the OpenCDS Configuration for version 1.32.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

Configuration Schemas

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

BerkeleyDB (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):

• knowledgePackages
• supportingData

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 Service

Run-time OS

For initial OpenCDS run-time configuration, please start with the relevant section of the documentation according to the operating system where OpenCDS will be deployed, as there are some differences for Windows and Linux/Mac installations:

• Linux/Mac Configuration
• Windows Configuration

The remaining configuration is described below:

Schemas

Configuration Schemas

Backend Configuration of OpenCDS Server

Configuration Backend Tooling

REST Service

PLEASE NOTE: OpenCDS Configuration REST Services should be used while no (DSS) requests are being processed by the system.  Doing otherwise may result in a race condition on the configuration backend, yielding potentially unexpected results.

Security

REST Security

Methods

Configuration API (REST) Version 1.0

REST Client

Migration

A migration path has been provided in order to facilitate migration from configuration file formats from 1.2.x and previous versions.

The migration code supports two methods of migration from version 1.2.x and earlier, namely file-based and REST service-based.

Data must be in previous formats for migration to succeed.

File-based Migration

The file-based method reads from the files in a standard 1.2.x or earlier configuration, transforms the metadata, and writes them in their new format in the specified target location.  Recall that prior to 1.3.x, OpenCDS required a specific layout for configuration files in addition to a directory/folder layout for the files. File-based configuration for version 1.3.x also requires a similar layout, but this is handled by the migration program.

<migration example here>

REST Service-based Migration

The REST Service-based migration reads from the files in a standard 1.2.x or earlier configuration, transforms the metadata, and uploads them to the OpenCDS service.  The storage locations of these files are handled by OpenCDS; all files must be updated through the REST Configuration Service.

<migration example here>

...

Front-end Tooling to Re-configure OpenCDS Server

Use of OpenCDS will normally require posting updates to:

• install new or updated Knowledge Modules (KMs), and the configuration for the KMs, including any
  • Concept Determination Methods (CDMs),
  • Supporting Data, or
  • Plugins required by the new or updated Knowledge Modules.

These configuration changes can be posted to one or more OpenCDS Servers using the Front-end Tooling, which is currently implemented by a REST client.

REST Client

Configuration Front-end Tooling (REST Client)

Migration from Earlier Versions of OpenCDS Configuration

Configuration Migration