Custom Control - BenefitCode Walkthrough Example

This example demonstrates a custom control plugin for Web Determinations.  For more general information on constructing and debugging custom control plugins, see Create a Custom Control

In our example, we have a kind of attribute in the rulebase (a benefit code) where the attribute is stored as a single text string, but the string has multiple parts that we want the end-user to edit with separate HTML widgets.

The example custom control provider replaces any text input control where the screen author in Oracle Policy Modeling has set the control's HTML class to 'BenefitCode'.

The example includes two re-usable abstract classes, InterviewControlWrapper and InputInterviewControlWrapper, which delegate as much as possible to the source control in the rule engine runtime layer, allowing your custom formatter to concentrate on special cases.

To construct this example:

Build a rulebase

 First create a rulebase which defines our attributes and will use the default controls.

  1. In Oracle Policy Modeling, choose File->NewProject... and name the project, "BenefitCodeExample".
  2. Right-click the Rules folder, and select, "Add New Word Document"
  3. Name the new word document "rules.doc" and double-click to edit.
  4. Microsoft Word will open.  In Word, add the following rule:



  5. Select, "The benefit code" and type alt-G to add a text variable.  You should now have something like this:



  6. Compile the rules (alt-R) and close the document, returning to the Oracle Policy Modeling application.

 

Now we want to test that the rulebase is working correctly.

  1. In Oracle Policy Modeling, choose Build->Build and Debug..., With screens.
  2. An interview should open, in which you can determine if a benefit code will be paid by direct deposit by entering any random benefit code:

 

You should now have a functioning rulebase.  If your rulebase is not working correctly so far, you should fix any problems before proceeding to the customization steps.

Build a custom control plugin

The next task is to build a plugin.  Our plugin has four classes.  Java source code is provided, but the .NET source code is very similar:

  1. Create the java files with the source code from this page, and compile them to a JAR file in your favorite Java development environment.  You will need to tell your java compiler how to find the needed Oracle Policy Automation dependencies, as detailed in Create a Plugin.  Call the resulting JAR file, "BenefitCodeExample.jar"
  2. Copy the BenefitCodeExample.jar file you have created to your rulebase's plugins directory, where Oracle Web Determinations can find it.  If your rulebase is at <...>\BenefitCodeExample, the correct directory for your plugin is <...>\BenefitCodeExample\Release\web-determinations\WEB-INF\classes\plugins.  If the Release directory does not exist, Build and Debug your rulebase once to create it.
  3. Create a velocity template file BenefitCodeControl.vm in your rulebase's templates directory, and copy the velocity source into it.  If your rulebase is at <...>\BenefitCodeExample, the correct directory for your control template is <...>\BenefitCodeExample\Release\web-determinations\WEB-INF\classes\templates\controls\BenefitCodeControl.vm
    The file name is important here - it must match the name of the custom control class exactly or the file will not be found.
  4. Build and Debug again.  Your plugin should now be loading, but it won't be doing anything visible yet.

Customize the rulebase to use the plugin

Now we want to invoke our plugin to use our custom control. The plugin is looking for an HTML class, "BenefitCode" so we need to create a screen and put that class on the control.

  1. In Oracle Policy Modeling, right-click the "Screens" folder, and choose "Add New Screens File".  Call it "screens".
  2. By default, screens files are created with an empty summary screen.  A real application would carefully customize this screen, but in our simple example we will delete it to use the automatic summary screen instead.



  3. Right-click the Question Screens folder and select, "New Question Screen"
  4. On the new screen, add a control for our benefit code attribute, and set the HTML class of the attribute to "BenefitCode"



  5. Click OK, save, and build and debug again.  Your custom control should now be working! 



  6. Note that when you view a decision report or data review screen, the raw text value will be printed, e.g. "RET-1234" in this case.  If you want your attribute values to be formatted specially even when printed outside of your custom control, you will need to implement a custom formatter as well.  See Formatter Plugin

Plugin Source Code