Plugin Configuration

This documents describes the process for adding pre and post-processing plugins to OpenCDS deployed as a war file. If your deployment differs from this assumption, you may need to alter some of these steps but the general guidance provided in this document should allow you to get up and running with plugins fairly quickly.

Changes to the configuration files described below should be made in the configuration folder specified in the beans.xml file. The beans.xml file is generally located in the WEB-INF folder of the web application. The typical location for opencds configuration folders and files is: ${user.home}/.opencds.

Implementing a Plugin

Dependencies

In your maven project or module where the plugin will be developed, add the following dependency:

<dependencies>
  <dependency>
    <groupId>org.opencds</groupId>
    <artifactId>opencds-plugin-api</artifactId>
    <version>3.0.0-SNAPSHOT</version>
  </dependency>
</dependencies>

This dependency includes the necessary plugin interfaces that shall be implemented by your pre and post-processing plugins.

Implementing the PreProcessPlugin Interface

Preprocessing plugins must implement the PreProcessPlugin interface. An example is provided below:

package com.example.opencds.plugin;

import org.opencds.plugin.PluginContext;
import org.opencds.plugin.PreProcessPlugin;

public class MyPreProcessingPlugin implements PreProcessPlugin {

  public ContentNormalizationPlugin() { .. }

  @Override
  public void execute(PluginContext.PreProcessPluginContext preProcessPluginContext) {
    //Your code goes here
  }
}

Configuring and Registering a New Plugin

The new plugin must be registered in the opencds-plugins.xml file located in the plugins folder inside the knowledge repository folder. The knowledge repository folder is specified in an opencds properties file which is itself specified in the beans.xml file. 

You can find the location of your knowledge repository folder by first identifying the properties file where this folder is specified in the beans.xml file as shown below:

<bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
  <property name="systemPropertiesModeName" value="SYSTEM_PROPERTIES_MODE_OVERRIDE" />
  <property name="valueSeparator" value="?" />
  <property name="ignoreResourceNotFound" value="true" />
  <property name="locations" value="file:${user.home}/.opencds/opencds.properties" />
</bean>

The opencds.properties file provides the location of your knowledge repository as shown in the example below:

knowledge-repository.type=SIMPLE_FILE
knowledge-repository.path=/Users/myusername/.opencds/opencds-knowledge-repository
config.security=/Users/myusername/.opencds/sec.xml
km.threads=1

Navigate to the location specified by knowledge-repository.path and locate the plugins folder. Update the opencds-plugins.xml file by adding the definition of your plugin as illustrated below:

<?xml version="1.0" encoding="UTF-8"?>
<rest:pluginPackages xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rest="org.opencds.dss.config_rest.v1_0" xsi:schemaLocation="org.opencds.dss.config_rest.v1_0 ../../schema/OpenCDSConfigRest.xsd">
  <pluginPackage>
    <identifier scopingEntityId="com.example.entity" businessId="informative-plugin-group-name" version="1.0.0"/>
    <loadContext>CLASSPATH</loadContext>
    <plugins>
      <plugin>
        <identifier scopingEntityId="com.example.entity" businessId="informative-plugin-name" version="1.0.0"/>
        <className>com.example.entity.app.opencds.plugin.MyNewPreProcessingPlugin</className>
      </plugin>
    </plugins>
    <timestamp>2018-08-31T11:53:45</timestamp>
    <userId>yourusername</userId>
  </pluginPackage>
</rest:pluginPackages>

The definition and documentation of the pluginPackages' elements and attributes can be found in the OpenCDSConfigRest.xsd schema located in the opencds-parent project (in the module opencds-config/opencds-config-schema).

Referencing a Plugin in a Knowledge Module

Once a new plugin has been registered with the OpenCDS server, it can be referenced in a knowledge module by adding an entry for the plugin in the knowledgemodules.xml file located at the root of the knowledge repository folder specified in the opencds.properties file. In that file, locate or add the preProcessPlugins element as specified in the OpenCDSConfigRest.xsd. Add an entry for the newly defined plugin as shown below:

<preProcessPlugins>
   <preProcessPlugin scopingEntityId="com.example.entity" businessId="informative-plugin-name" version="1.0.0"></preProcessPlugin>
</preProcessPlugins>

Please note: ensure that the scopingEntityId, the businessId, and the version match those defined in the opencds-plugins.xml file.

Please note: plugins must be listed in order of execution.