Wednesday Jan 22, 2014

Batch Processor in Oracle Policy Automation (OPA)

Adeolu Owokade | Monad Solutions

In this article, we will be exploring the Batch Processor in Oracle Policy Modeling. The Batch Processor allows a large number of cases to be processed in batch. It can take input from comma separated files or from a database and can output to the same.

Let me give an example of where the batch processor may come in handy. Imagine a Telecommunications organization that recently implemented OPA for its customers to check what mobile phone packages they can apply for. However, that organization already has data about its existing customers in a database and will also want to know which packages are applicable to its existing client base. The best way to do this will be by running this data in a batch rather than conducting an interview for each existing customer.

The Batch Processor sees its usefulness in other areas like conducting what-if analysis and generating test scripts from existing Excel data. We will explore input from and output to CSV files. This article assumes you have working knowledge of OPA; I will make it as practical as possible so let us begin by modeling a simple rulebase.

Sample Policy

  • The customer is eligible to apply for the Gold Plan if the customer has been a registered customer for at least 3 years and the total amount spent by the customer is above £3,000.
  • The customer is eligible to apply for the Silver Plan if the customer has been a registered customer for at least 2 years and the total amount spent by the customer is above £2,000.
  • Any registered customer is eligible to apply for the Basic Plan.

The OPA rules for this policy are as shown below:

The data model is as shown below:

Batch Processor Zero-configuration

If you are using CSV files as the input to the Batch Processor, much of the mapping from CSV data to OPA data can be done automatically through the Zero-configuration, by following a few simple guidelines which we will discuss in this section.

Entities

The CSV file name should be the public name of the entity. In our example, we will use two CSV files: "global" and "customer". "customer" is the public name of 'the customer' entity as shown below:

The CSV files are as shown below:

Input Attributes

The columns on the first row in the CSV files should be named with the attribute public names.

Identifier

By default, a column with the heading "#" is assumed to be a unique identifier for that entity.

Output attributes

To represent output attributes, enclose such public names in brackets.

One-to-Many Relationships

One-to-many relationships can also be represented in CSV files by using the public name of the relationship as the column title. For example, the relationship between global and 'the customer' entity is a one-to-many relationship which I can represent  in the customer.csv as shown below:

In the diagram above, customer instances #1 to #4 are instances under global instance #1 while customer instances #5 to #7 are instances under global instance #2.

The full content of the CSV files are shown below. The global.csv file has two instances of 'global'. You can think of this like two separate interviews (or 2 test cases). The customer.csv file has 7 instances representing 7 customers.

Running the Batch Processor

The batch processor is a standalone application that is run from the command line using the parameters listed below:

  • java -jar determinations-batch.jar <command line parameters> (JAVA)
  • Determinations.Batch.exe <command line parameters> (.NET)
To make running the Batch Processor easier especially when using Zero-configuration, I recommend placing all your files and rulebase in one folder. For example, take the rulebase ZIP file (found in the output folder in the Development folder of your OPA project) and place it in a separate folder. In that same folder, create another sub-folder to hold your CSV input files (name it "csv" so you don't have to specify the name of the folder in the CLI parameters).

Then, you can open a command prompt, navigate to this folder and run the batch processor from this location.

Note: If you are not running the Batch Processor from its default location, you must specify the full path e.g. "C:\Program Files (x86)\Oracle\Policy Modeling\bin\determinations-batch.jar"

Batch Processor Output

When the Batch process is complete, a folder (called "csv.out") is automatically created. This folder used to be named "output" in earlier versions of OPA (I'm using version 10.4.4). This folder contains the same CSV files in the input folder but with the generated output values.

Let's view the content of these CSV files. First, the customer.csv:

Notice that the output field – out_cust_years-reg – has been filled out. This is just the number of years between the current date (January 08, 2014) and the dates the customer registered.

Let's also view the global.csv file, where the output should count the number of customers that are eligible for each plan.

Summary

In this article, we have seen how to use CSV as input to the Batch Processor. We have also seen how to ensure that our csv files are properly formatted so that zero-configuration can take place. There are move advanced topics like writing a configuration file to be used for running the batch process and also database connections but this gives a good overview of the Batch processor.

I hope you have found this article insightful.


This article originally appeared on Monad's Commentary on Oracle Policy Automation (OPA) blog on 10 January 2014. Republished with permission.  

Sunday Jan 19, 2014

Ten Minute Tutorial: XDS Logger Plugin for Determinations Server (JDeveloper)

Andrew Higginbottom | Policy Automation Technical Zealot

Welcome to another TMT. This time we will create a plugin for Oracle Determinations Server to log incoming SOAP requests in the Oracle Policy Automation XDS (eXplicit Data Set) format - not to be confused with XSD. You can take this and load it into the Oracle Policy Modeling debugger to track down issues with specific SOAP requests. DISCLAIMER: This might take you longer than 10 minutes, depending on how fast you can click and how fast your PC is!

Last time we used Eclipse but this time we will be using JDeveloper to build and test the plugin. Again there are some prerequisites:
  1. Oracle JDeveloper (I used 11.1.2.4.0)
  2. Oracle Policy Automation Runtime Components for Java (I used v10.4.4.21.0)
  3. SoapUI (I used 4.6.4)

Once downloaded, install JDeveloper, extract the OPA Runtime Components to a convenient location and install SoapUI.

Now we begin. Start JDeveloper and accept the "Studio Developer (All Features)" role.

Select Application > New... from the main menu to create a new application workspace.
Give the application a name "ODSXDSPlugin"

Accept the default Project1 and Finish.

Having set up the Application, we now import the Determinations Server WAR file. File > Import... from the main menu, then select > WAR File. Call the project "determinations server".

At the next step Browse... to the location where you extracted the OPA Runtime and select /determinations-server/determinations-server.war.

Right-click determinations-server project, New..., General > Java Class.
Enter Name "XDSLogger", Package "com.opablog.aeh".

Add the "OnBeforeThinkEventHandler" interface. This event is fired for every request, after the request has been parsed into the session but before the rules are executed.


This time I've provided the code to copy and paste in, replacing the entire contents of the new XDSLogger.java file:

package com.opablog.aeh;

import com.oracle.determinations.engine.SessionUtils;
import com.oracle.determinations.server.assess.extensions.AssessPlugin;
import com.oracle.determinations.server.assess.extensions.AssessPluginRegisterArgs;
import com.oracle.determinations.server.assess.extensions.events.OnBeforeThinkEvent;
import com.oracle.determinations.server.assess.extensions.events.OnBeforeThinkEventHandler;
import java.io.IOException;
import java.io.StringWriter;
import org.apache.log4j.Logger;

public class XDSLogger implements OnBeforeThinkEventHandler {
 
    private Logger log = Logger.getLogger(this.getClass());
 
    public XDSLogger() {
        super();
    }

    @Override
    public void handleEvent(Object object, OnBeforeThinkEvent onBeforeThinkEvent) {
        try {
            StringWriter w = new StringWriter();
            SessionUtils.exportSession(onBeforeThinkEvent.getSession(), w);
            log.debug(w.toString());
        } catch (IOException e) {
            log.error(e);
        }
    }

    @Override
    public AssessPlugin getInstance(AssessPluginRegisterArgs assessPluginRegisterArgs) {
        return this;
    }
}


Edit Application Sources/config/application.properties to configure ODS to load the plugin by updating the plugin.libraries parameter to "plugin.libraries=com.opablog.aeh.XDSLogger"

Edit Application Sources/log4j.xml to increase the logging level by setting <level value="DEBUG"/> under the <root> element. Don't do this in production!

Copy in the PocketMoneyComputation.zip rulebase from the \examples\rulebases\compiled folder in your expanded OPA runtime location. Use Windows Explorer to copy the file into your JDeveloper project. For me the destination folder is located at C:\JDeveloper\mywork\ODSXDSPlugin\determinations-server\src\rulebases.


Now we can deploy the plugin to our local server.
Select Run > Start Server Instance (IntegratedWebLogicServer) from the main menu and enter credentials of your choice to use for server setup.

Wait for domain to build and server to start up. Once completed you should see "IntegratedWebLogicServer started." in the Log window.

Now we can deploy our Determinations Server with XDS logger plugin.

Right-click the determinations-server project and Deploy > "determinations-server...". Select "Deploy to Application Server", click Next, then IntegratedWebLogicServer, then Finish. Ignore any warnings logged during startup - they are only there because we turned the logging up to DEBUG.
In the deployment tab you should see that deployment has finished and you are given the URL in the Deployment - Log window.


Finally we can test our plugin by sending a request using SoapUI.
Open the URL in your favourite browser and you will see the familiar page listing the OPA services available. Grab the full URL to the specific Assess service WSDL.

Start SoapUI and select File > New SOAP Project from the main menu. Give the project a name and paste the WSDL URL for Initial WSDL. Make sure Create Requests is checked.

Open Request1 under the Assess node and paste the following minimal SOAP message to replace the default content:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:typ="http://oracle.com/determinations/server/10.4/PocketMoneyComputation/assess/types">
   <soapenv:Header/>
   <soapenv:Body>
      <typ:assess-request>

         <typ:global-instance>
            <!--You may enter the following 6 items in any order-->
            <!--Optional:-->
            <typ:base_rate>
               <typ:number-val>2.50</typ:number-val>
            </typ:base_rate>
            <typ:person_name>
               <!--You have a CHOICE of the next 3 items at this level-->
               <typ:text-val>Parent</typ:text-val>
            </typ:person_name>
 
            <typ:total_money outcome-style="decision-report"/>
 
            <typ:list-child>
               <typ:child id="1">
                  <typ:child_name>
                     <typ:text-val>Bobby</typ:text-val>
                  </typ:child_name>
                  <typ:child_age>
                     <typ:number-val>7</typ:number-val>
                  </typ:child_age>
                  <typ:child_money outcome-style="value-only"/>
               </typ:child>
               <typ:child id="2">
                  <typ:child_name>
                     <typ:text-val>Betty</typ:text-val>
                  </typ:child_name>
                  <typ:child_age>
                     <typ:number-val>9</typ:number-val>
                  </typ:child_age>
                  <typ:child_money outcome-style="value-only"/>
               </typ:child>
 
            </typ:list-child>
         </typ:global-instance>
      </typ:assess-request>
   </soapenv:Body>
</soapenv:Envelope>

Press "play" (the green arrow pointing to the right) to submit Request1. You should see a response that looks similar to the request, but with calculated values returned along with the inputs used.

In addition to processing the Assess request as normal, our new Determinations Server plugin has logged the inputs to the application log in the OPA XDS format.

You can now copy this XML into a text file and load it up in OPM to debug!

There are obvious improvements that could be made to this, such as logging each request to its own file, but I will leave those as an exercise for the reader. This is supposed to be a TMT after all!



Monday Dec 09, 2013

Ten Minute Tutorial: Web Determinations Plugin (Java in Eclipse)

Andrew Higginbottom | Policy Automation Technical Zealot

Welcome to this TMT, today I will show you how to create a Web Determinations plugin. Plugins provide a mechanism to alter the default behavior throughout the Oracle Policy Automation web applications. You can use plugins to change the way pages and controls are rendered, the way sessions are loaded and saved, where rulebases are loaded from, and the way many other aspects of the applications work. Plugins are developed as Java or .NET classes and packaged and deployed as JARs or DLLs.

In this tutorial we will start from a completely empty workspace and have an event handler plugin up and running in under 10 minutes.

Before we get started there are two prerequisites to download:

  1. Eclipse IDE for Java EE Developers (I used Kepler SR1)
  2. Oracle Policy Automation runtime components for Java (I used v10.4.4.21.0)

Expand the downloads to a convenient location and launch eclipse.exe within the eclipse folder. Create a workspace folder (or accept the default) to hold the eclipse project files and continue to the eclipse IDE. Close the Welcome tab to see the normal eclipse view.

Now we are ready to import the out of the box Web Determinations application via the menu. File > Import, choose Web > WAR file.


On the next screen Browse... to the location where you expanded the OPA runtime download, and navigate to \web-determinations\web-determinations.war. Leave the rest of the field defaults and click Finish.


Once the project has finished importing we are ready to develop our plugin. The first step is to add our plugin class. Right-click the Java Resources > src folder then New > Class.


Enter your desired package name and class name (you will need these later) and use the Add... button to add the interface OnSessionCreatedEventHandler to the class definition. Click Finish to, well, finish.


Within the generated class we will make a few small changes to register the plugin correctly and print a message to System.out every time a session is created.

We need to change line 12 to "return this;" and on line 17 we use a basic println to write something to the output. Go on, type it, it's only one line - but please don't do this in production code!


Now we are finished with building the plugin, we just need to configure Web Determinations to load it. For development we edit the src/configuration/application.properties file to specify the plugin's class name but you can also bundle your plugin into a JAR which will be loaded automatically from the plugins folder. Add the fully qualified name of your plugin class to the "plugin.libraries=" line:


We now copy a rulebase into the src/rulebases folder so we can actually start a session. When a single rulebase is present in the rulebases folder a new session will automatically be launched in that rulebase when the user hits the base URL. Copy in the HealthyEating.zip rulebase from the \examples\rulebases\compiled folder in your expanded OPA runtime location. You can do this by copying from Windows Explorer and pasting via the context menu in eclipse.


Now we are ready to test our new plugin within a Web Deteminations session. We can Run the web-determinations project on the J2EE Preview Server provided in eclipse. Select the project root folder (web-determinations) and from the main menu use Run > Run, then Run on Server. On the next screen select Basic > J2EE Preview and click Finish.


Once the server starts up you should see the summary screen and in the Console window your message printed from the handleEvent method of your class!


This is a very simple example, intended to show how to set up a development environment and develop your first Web Determinations plugin. There a many more things you could do within this event, such as loading some reference data, creating entity instances and so on.

There are also many more event handlers you can implement and other types of plugins for changing the default Web Determinations behaviors, such as Data Adaptors, List Providers and Custom Screen/Control Providers. Check out the Extensions topic in the Oracle Policy Automation 10.4.4 Developer's Guide, starting from the Documentation page on OTN.

Check back soon for a Determinations Server plugin tutorial!


About

Welcome to the OPA blog where Oracle's Policy Automation experts share their views on everything OPA.

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today