Rationale

1. Supporting Data is a requested feature (see Automated Deployment of Knowledge to OpenCDS - Scenarios), which would allow deployers to dynamically deploy knowledge artifacts that need not (or should not) be embedded within the (Drools) Knowledge Package.  In order for OpenCDS to support any desired data format, whether XML, JSON, textual tables, binary tables, etc., OpenCDS would need to support each of those specific formats, thereby requiring additional maintenance to OpenCDS itself to support the format, or requiring deployers to reimplement the rules adapter (DroolsAdapter) for their specific case.
   
   In order to facilitate adaption to various formats of Supporting Data, we propose a Plugin-based framework to allow deployers to leverage/build their own transformers for their supporting data, thus transforming the data into a format the rules can use.
   
   
2. A recent development in an operational environment required the addition of vMR components be copied as other vMR components in order for the rule writer to work around issues with looping inherent in some BPMN configurations.  This led to modification of the OpenCDS source code to support such a feature.  The drawback, however, is that these changes unnecessarily affect all data that enter the OpenCDS system.
   
   In order to facilitate custom processing of vMR data (and other input to the rules engine–see below) and to limit their effect to specific Knowledge Modules, we propose the same Plugin-based framework allow for pre- and post-processing of data as they enter and exit (respectively) the rules engine.

Proposed Components

The following is a proposal of features of the Plugin-based framework.

Plugin Context

The Plugin Context is composed of two sub-components, namely the PreProcessPluginContext and the PostProcessPluginContext.

PreProcessPluginContext

The PreProcessPluginContext is constructed each time rule execution is requested.  The following data components are contained within the context:

• evalTime
• clientLanguage
• clientTimeZoneOffset
• focalPersonId
• assertions
  • This object is a set of strings, or more specifically, Set<String>, and is a placeholder for assertions and is instantiated and given to Drools as a global variable. Drools may write to this set to provide the calling code with the information about the inferencing performed on the input data. (As of today--2014-09-20) the assertions object is not being used external to Drools, as there is a rule that is commonly being used which assembles the assertions into a comma-delimited list, as part of the vMR output.)
• globals
  • This (new) object is a Map of String to Object, or more specifically, Map<String, Object>.  The key of each map entry may be any given String, which is typically used as a Global within the Drools context.  Names are restricted to any value other than the following:
    • read-only: evalTime, clientLanguage, clientTimeZoneOffset, focalPersonId
    • read-write: assertions, and namedObjects
• allFactLists
  • This object is a Map of Class to List, or more specifically, Map<Class<?>, List<?>>.  The key of each map entry may be a Class of any given type, though Plugins should restrict the types to OpenCDS-internal components of the vMR.
  • Fact Lists are the facts that Drools uses for inferencing–these contain data from the vMR.
  • All facts that are submitted are returned unless they are retracted by the rules.  They are returned to OpenCDS, but OpenCDS only puts them into the output XML if they are flagged to be returned (using ClinicalStatement fields: clinicalStatementToBeRoot and/or toBeReturned; a ClinicalStatement marked as clinicalStatementToBeRoot and toBeReturned will return all child elements).
• namedObjects
  
  • This object is a Map of String to Object, or more specifically, Map<String, Object>.  The key of each map entry may be any given String, which is typically used within Drools.
  • Named objects are currently (at the University of Utah) used by Drools rules as follows:
    • adds named objects to what is found to be returned in submitted allFactLists.
• cache
  
  • Cache is a cache of data within an OpencdsCache cache region, where plugins may store the data they support for future processing, as in the case of, e.g., SupportingData.

PostProcessPluginContext

The PostProcessPluginContext is constructed each time rule execution has completed.  The following data components are contained within the context:

• evalTime
• clientLanguage
• clientTimeZoneOffset
• focalPersonId
• assertions
  • This object is a set of strings, or more specifically, Set<String>, and is a placeholder for assertions and is instantiated and given to Drools as a global variable. Drools may write to this set to provide the calling code with the information about the inferencing performed on the input data. (As of today--2014-09-20) the assertions object is not being used external to Drools, as there is a rule that is commonly being used which assembles the assertions into a comma-delimited list, as part of the vMR output.)
• globals
  • This object (created and added to the PreProcessPluginContext) is a Map of String to Object, or more specifically, Map<String, Object>.  The key of each map entry may be any given String, which is typically used as a Global within the Drools context.  Names are restricted to any value other than the following:
    • read-only: evalTime, clientLanguage, clientTimeZoneOffset, focalPersonId
    • read-write: assertions, and namedObjects
• resultFactLists
  • This object is a Map of String to List, or more specifically, Map<String, List<?>>.  Data contained by this map are the result fact lists, which are the final return value of the DroolsAdapter.getOneResponse method and OpenCDS post processing.
  • Effectively this is a copy of allFactLists (above) with any changes made by Drools, and the contents of namedObjects (added by OpenCDS after Drools processing).
    • Currently namedObjects informs the output XML generator to determine which elements should be included in the output XML.

• cache
  
  • Cache is a cache of data within an OpencdsCache cache region, where plugins may store the data they support for future processing, as in the case of, e.g., SupportingData.

Plugin Configuration

Plugin Data Access

(Supporting Data)

(Sandboxing)

Plugin Loading

(Configuration)

(Loading & Sandboxing)

(To be continued...)

Updated Configuration Diagram