Customize the existing Web Determinations user experience

What do you want to do?

Modify the behavior of Web Determinations

Implement a rulebase-specific look and feel

Modify the behavior of Web Determinations

Oracle Web Determinations allows you to deploy Oracle Policy Modeling rulebases into a configurable and extendable web application out of the box.

There is a comprehensive extension architecture available to technical consultants/system integrators with extension points to accommodate specific project implementation needs.

Web Determinations extensions are custom Java or .Net classes/packages that are developed by system integrators and deployed onto a Web Determinations web application.

There are two main types of interactive extensions:

  1. Plugins
  2. Event Handlers

 

When extending Web Determinations, both of these extension types do not need to be used exclusively. They both provide complementing extension points, so it is most likely that both plugins and Event Handlers will be used to achieve the desired project-specific behavior.

What is a plugin?

In the context of Oracle Web Determinations, the word plugin is ambiguous as it can mean either a single class that implements an exported interface, or the compiled JAR or DLL containing multiple class definitions; from this point on, these are referred to as plugin class and plugin archive respectively, and the interface they implement is a plugin interface. 

Plugins are constructed in two stages:

  1. At application startup, an instance is constructed by reflection, with a no-argument constructor.  This is called the factory instance. 
  2. Plugins are initialized by the factory instance, at different times and with different arguments for each different plugin interface. The factory instance is responsible for returning a fully-initialized actor instance which may be a copy of itself, or a newly constructed object. Alternatively, the factory instance may decline to attach by providing no actor instance at all; it is not really necessary to create factory instances as static methods with a specified name and signature could be used instead.

Kinds of plugins

There are several varieties of plugin interface:

Some examples:

General procedure for the creation of a plugin

To create a plugin:

  1. Determine what plugin is to be extended
  2. Locate the Web Determinations plugin folder inside the web application
    1. Tomcat (Java) - default is in the WEB-INF\classes\plugins path in the interactive web application in the Tomcat webapps folder; for example:
      C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\interactive\WEB-INF\classes\plugins
    2. IIS (.Net) - by default, this in C:\inetpub\interactive\plugins



  3. Determine what plugin interfaces need to be implemented
  4. Create a class file, and implement the required interfaces and methods
  5. Develop the methods
  6. Package the class files
  7. Deploy the packaged source into the plugins folder
  8. Add needed class libraries in the lib directory
  9. Restart the server
  10. Test

Configure plugins from the System Administrator's perspective

When deploying Oracle Web Determinations, plugin archives must be placed in a specific location within the deployed web application (classes/plugins).  This location cannot be changed by configuration.  In Java, plugin classes must be archived into a JAR (no naked .class files).  Other non-plugin files, such as dependencies or configuration files for the plugin classes, may also be placed in the plugins directory; they will be ignored by Oracle Web Determinations.

On application servers which allow us to search the plugins directory (such as Tomcat and IIS) every JAR (for Java platforms) or DLL (for .NET platforms) in the plugins directory will be examined to determine if it is a plugin archive. For the convenience of the systems administrator who may wish to deploy large numbers of plugin dependencies without incurring extra delay at startup, subdirectories of the plugins directory will not be searched.

On application servers which do not allow us to search the plugins directory (such as WebLogic and WebSphere) plugin archives must be named explicitly in the Oracle Web Determinations configuration file.

On any application server, even if the plugins directory can otherwise be searched, when plugins are specified in the configuration file, no other unnamed plugins will be loaded. This allows for consistent behavior when the same Oracle Web Determinations deployment is moved between application servers. It also allows an Oracle plugin archive to be overridden by a customer plugin archive while still being available for the customer plugin archive to use.

Plugin initialization order

Plugins are initialized in batches, according to the interfaces they implement.  Note that within each batch, the order of initialization is not specified:

  1. all Engine Singleton plugins
  2. all Platform Singleton plugins



  1. all Engine Session plugins
  2. all Platform Session plugins

Multithreading

Oracle Web Determinations is heavily multithreaded, and attention must be paid to threading issues to produce correct behavior.

Implement a rulebase-specific look and feel

The following provides a discussion of the steps required and the available options for implementing a rulebase-specific interview look and feel in Web Determinations.

Rulebase custom properties

Oracle Policy Modeling provides a way to attach key/value property pairs to individual screens and controls at rulebase authoring time. These are then exposed to the templates that render the Web Determinations user interface through the platform's screen and controls API.

Sample code

Take for example, a rulebase in which some controls have a custom property called 'template', which maps onto the path of a template to be used instead of the default template to render that particular control. Additionally, in this example, this functionality is to only be available to this one rulebase, perhaps because access to this rulebase is only granted to a small group of trusted rulebase engineers. Call this rulebase 'alternative'.

The following is a fragment of the default template for cycling through the controls on a screen and calling the template for each control type to render the specific control:

#set( $controlList = ${screen.getControls()} )
#foreach( $control in $controlList )
    <div class="control-item">
        #parse( "controls/${control.getControlType()}.vm" )
    </div>
    <span class="control-clear"></span>
#end


The name of the template used to render a particular control is retrieved through the getControlType method on the control object. This is the logic that will be altered for this example: 

#set( $rulebase = ${screen.getInterviewSession().getRulebase().getName()} )
#set( $controlList = ${screen.getControls()} )
#foreach( $control in $controlList )
    <div class="control-item">
         #if( $rulebase == "alternative" && ${control.hasProperty("template")} )
            #set( $alternativeTemplate = ${control.getProperty("template")} )
            #parse( "${alternativeTemplate}" )
        #else
            #parse( "controls/${control.getControlType()}.vm" )
        #end
    </div>
    <span class="control-clear"></span>
#end

Other methods

Templates can be modified to check for a specific rulebase or set of rulebases, and to alter the functionality and/or look and feel of the application for that particular session. This is what we have done above using the specific case of custom properties attached to controls. Another option would be to parse an alternative/extra CSS template for particular rulebase(s) and not for others. There are, however, a couple of things to bear in mind about rulebase-specific configuration:

  1. Be careful about where you insert the rulebase check in the template code; think about which templates may make a #parse call into the current template, and about whether there is a chance that the rulebase-specific code may be executed for all rulebases.
  2. Keep in mind template and property file caching settings.

 

The following describes rulebase management in terms of deploying Oracle Determinations Server for Apache Tomcat V6.x or WebSphere Application Server V6.1.

You can only manage individual rulebases for a determinations-server web application on application servers that deploy web applications in expanded form. Apache Tomcat and IBM WebSphere Application Server do deploy their web applications in expanded form, while Oracle WebLogic does not deploy a web application in expanded form by default.

In order to add, update, or remove a rulebase you need to locate the rulebases directory of the determinations-server web application. By default, this is located at: WEBROOT/WEB-INF/classes/rulebases/. See below for the WEBROOT depending on the different application server.

If you have specified a custom rulebases directory, you can add, update or remove a rulebase at the location of the specified rulebases directory. 

To add a rulebase

Using Oracle Policy Modeling, open and build the rulebase. The rulebase archive, <rulebase name>.zip will be built in the output directory of the rulebase project.

Copy the rulebase archive to Oracle Determinations Server’s rulebase directory. By default, Oracle Determinations Server will automatically add the rulebase.

Note: In addition to building a rulebase by using Oracle Policy Modeling, it can be done from the command line; for information on how to do this, see the topic Build the rulebase from the command line, in the Reference section of the Oracle Policy Modeling User's Guide.

To update a rulebase

Using Oracle Policy Modeling, open and build the rulebase. The rulebase archive, <rulebase name>.zip will be built in the output directory of the Rulebase project.

Copy the rulebase archive to Oracle Determinations Server’s rulebase directory. By default, Oracle Determinations Server will automatically update the rulebase.

To remove a rulebase

Delete the rulebase archive from Oracle Determinations Server’s rulebase directory. By default, Oracle Determinations Server will automatically remove the rulebase, and its operations will no longer be available

The following terminology applies:

Term Definition
WAS Refers to the directory to which the WebSphere Application Server has been installed.
CATALINA_HOME The Apache Tomcat install directory.
WEBROOT

The path to the determinations-server root directory on the deployed server. By default this is:

  • Apache Tomcat (all versions):
    CATALINA_HOME/WebApps/determinations-server.
  • WebSphere Application Server 6.1:
    WAS/profiles/<profile name>/InstalledApps/<node>/determinations-server.war
    Where:
    • <profile name> is the name of the application server instance profile determinations-server is installed to (default is AppSvr01).
    • <node> the node that HDS is installed to (default is <hostname>Node01Cell).

 

Term

Definition

WAS

Refers to the directory that the WebSphere Application Server has been installed to.

CATALINA_HOME

The Apache Tomcat Install Directory

WEBROOT

The path to the HDS root directory on the deployed server. By default this is:

  • Apache Tomcat 5.x: CATALINA_HOME/WebApps/haley-determinations-server.
  • WebSphere Application Server 6.1:
    WAS/profiles/<profile name>/InstalledApps/<node>/haley-determinations-server.war

Where:

  • <profile name> is the name of the application server instance profile HDS is installed to (default is AppSvr01).
  • <node> the node that HDS is installed to (default is <hostname>Node01Cell).
  • BEA WebLogic 9.2: this is the directory that the HDS web application was expanded into in Step 3: Deploy the haley-determinations-server.war file (eg: c:\bea\webapps\haley-determinations-server\)

Note: After a new Rulebase is deployed or deleted, you should Update the haley-determinations-server web application (from the WebLogic console) or restart the server.