The Portal Rules Service

03/09/2004
WebLogic Portal offers a robust personalization solution through a set of components that provide run-time services for delivering personalized content to end users while browsing a Web site. These personalization components use business rules to match users and groups with appropriate content. The logic encompassed by the rules forms a critical piece of the personalization process.
The Rules Management Framework in WebLogic Portal provides run-time capabilities for providing personalized content based on externalized rules. The Rules Manager EJB is a scalable, stateless J2EE entry point into the underlying BEA Rules Engine. It provides the run-time services necessary to execute the business rules defined by the user. Two Portal controls, the RulesManagerControl and the RulesExecutorControl, provide easy access to the Rules Manager EJB.
Download the examples that accompany this articlehere.Some rules are automatically included with Portal, such as content selectors and campaigns. The user may also create their own customized rules by hand, leveraging Portal‘s Expressions package and using Xml Spy to validate those rules before deploying them into Portal.
Business rules can by dynamically loaded and modified, providing an efficient means of rules testing within a deployed application, via the Workshop IDE.
How the Rules Engine Works
The Rules Engine functions by applying a set of rules to objects in working memory. This working memory is first populated with input from the calling objects, such as the user profile request session, among other things. In this way, a representation of the user‘s profile exists in working memory before any rules are actually fired.
Rules can be executed only within a context, which associates a rule set with working memory. The context provides an interface to the Rules Engine that controls the relationship between the rule part of the application and the working memory.
This working memory is operated on by the production rules, which are contained in rule sets. The left-hand sides (LHS) of these rules are evaluated against the objects in the working memory. If the patterns on the LHS are matched, then the actions contained in the right-hand side (RHS) of the rules are performed. Some of these actions may add new objects into the working memory. For example, if our Classifier rule tests for USER.age > 45, then we might add a new Classification object into working memory.
The production system is executed by performing the following operations:
Match: Evaluates the LHSs of the rules to determine which are satisfied given the current contents of working memory. Conflict resolution: Selects one rule with a satisfied LHS. If no rules have satisfied the LHSs, halts the interpreter. Act: Performs the actions in the RHS of the selected rule. Go to step 1.
Rules will continue to operate on the working memory until the conflict resolution set is zero (that is, no more rules can fire).
After the Rules Engine has halted, the rules manager component returns a list of objects remaining in working memory. A likely scenario will have an object remaining of the type "Classification" or "ContentQuery."
The Rules Manager will then iterate over these remaining objects and filter them using an optional Object filter. The filter can selectively ignore objects or mutate them.
Using the Portal Rules Service
There are several steps involved in using the Portal Rules Service. The rules must first be created, and then deployed into a running instance of WebLogic Server. Next, the rules are evaluated, and the results are optionally filtered before being returned to the user. Finally, the user leverages the results of evaluating those rules in the application code.
Creating Rule Sets
Rulesets are XML files that conform to particular schema (details in the XmlSpy link). The rules ‘language‘ is actually a usage of the Portal expressions package, extended to meet additional requirements for the rules engine.
AddInteger Simple value test java.lang.String Nederland java.lang.Integer 10
Rulesets, which must end in *.rls, consist of several parts:
The tag includes all references to schema used in the document (ruleset) One or more rules, delineated by the tag Within each rule, one or more conditions and one or more actions
Conditions are tests that will be met on the input objects; actions are generally objects to be instantiated into working memory when the rule conditions are met and the rule fires.
By far the easiest way to create a ruleset is to start with an existing one and modify it. There are several rulesets in the examples accompanying this article. Rulesets may be also created by hand using a tool such as XML Spy. The rules and expression schema are located in p13n_ejb.jar, under lib/schema.
Deployment of Rule Sets
Each application is associated with its own instance of data. This data is located in the application‘s META-INF/data folder. Any data in or beneath that folder will be deployable by data sync. As a best practice, I like to create a folder called ‘rulesets‘ into which I drop my rulesets.
The rules service uses Portal Data Sync to deploy its rulesets into the running server. This means the user need only drop the rulesets into the data sync folder to get the rulesets to deploy. If the rulesets are already in the data sync folder, modifying the ruleset will cause those changes to be picked up by data sync and the rules service repository will refresh that instance of the ruleset. Ruleset file names must end with *.rls to be picked up by the rules manager.
So, for example, if my app is drtApp, I put my rulesets in the folder drtApp/META-INF/data/rulesets. Now, when the server first starts and the first invocation of the rules service is made, all the rulesets in this folder will be loaded by data sync and will be available to the rules engine.
Now, to refer to the ruleset URI in the rules controls or EJB APIs, the filenames will be relative to the META-INF/data folder. For example, if I dropped simple.rls into drtApp/META-INF/data/rulesets, I will refer to it with the URI ‘/rulesets/simple.rls‘.
Simply by changing the contents of the data sync ruleset folder, the modified rulesets will be reloaded (if changed) or removed from the rules service (if deleted).
This means you can tweak your rules, or debug parsing errors, as the server is running. You do not have to restart the server to change your rulesets.
The Rules Service Components
Portal controls are easy-to-use components to represent and execute business logic. They are graphical components available in WebLogic Workshop. The RulesExecutorControl is one such control. It allows the execution of named rules and rulesets, and will optionally filter the results after the ruleset has evaluated.
This control has several properties that must be configured before it is used:
The URI of the ruleset containing the rule. This URI is relative to the application‘s META-INF/data folder. The name of the rule to evaluate. If no rule is specified, then all the rules in the ruleset will evaluate. An optional filter parameter, described more in detail below.
Another rules article on dev2dev illustratesusing this control to direct page flows dynamically. This RulesExecutorControl actually wraps the RulesManager EJB, which is available in all Portal applications in the p13n_ejb.jar file and may be used directly to invoke the rules service (though controls are preferred). See the online Portal javadocs for the RulesManager EJB API.
Evaluating the Rules
Evaluation of the ruleset may be considered in these steps:
The Portal rules engine initializes, creating its "working memory." The rules control will describe which ruleset to use, and optionally, which rules to evaluate (defaults to all), and whether to filter results. These are all parameters that may be configured on the Rules control and are passed into the rules engine to evaulate the rule. The developer creates and add objects to the "working memory". Example objects might be the user‘s profile, the Request, etc. These parameters are passed in as an argument to the rule control‘s evaluate() method. The rules engine is invoked via the RulesExecutorControl. The rules engine creates its Rete Network from the input ruleset and input objects. The rules engine fires repeatedly, executing rules according to the state of the input objects and rule conditions. After the rules engine has reached a state where no more rules will fire, the results are in working memory, along with all of the original input objects. Because the input objects are part of the results, you may choose to filter the results based on a class. For example, you can specify that only results of class com.bea.p13n.usermgmt.profile.ProfileWrapper are returned. The examples in the following sections illustrate the creation and use of filters.
Filtering the Rules
Let‘s say you have a rule such as the simple rule example shown above. The objective of your application is to input a user‘s profile, check out some properties on it, fire some rules according to those properties, and instantiate a new Integer if the rule evaluates to true. You‘ll then use that Integer value to make decisions in your page flow.
The rules engine will return an Iterator over all objects that remain in working memory after the rules engine has fired all rules, exhausted its agenda, and halted. It‘s doubtful that you care about the objects that went into working memory, such as the user‘s profile, or the Request object, etc. Perhaps you‘ll want to get only the Integer objects from the results.
The object filter is a parameter that may be passed in as you‘re evaluating the rule. If using the rules control, it‘s an attribute specified on the control. If using the rules manager EJB directly, it‘s an argument to the evaluate() method.
The ObjectFilter can be constructed from any Java class or sets of classes, so in the case us using the RulesManager EJB directly, we‘d create the filter like this:
String rule = "myRule.rls";
Class clazz = java.lang.Integer.class;
ObjectFilter filter = new RuleResultClassFilter(rule, clazz);
See the javadocs for com.bea.p13n.rules.manager.RuleResultClassFilter for more information.
If you‘re using the RulesExecutorControl, the class you‘d like to filter on is specified as a control property, like this:
/** * @common:control * @jc:rules-executor filterClassName="java.lang.Integer" filterResults="true" rulesetUri="/rulesets/myRule.rls" */ private com.bea.p13n.controls.rules.RulesExecutorControl rulesExecutorControl;
Using the Results
So let‘s say you‘ve created the simple rule above, used the RulesExecutorControl to evaluate that rule, and filtered the results. Here‘s how it would all look in a code snippet:
import com.bea.p13n.usermgmt.profile.ProfileWrapper; import com.bea.p13n.controls.*; public class Controller extends PageFlowController { /** * @common:control */ private UserProfileControl profileControl; /** * @common:control * @jc:rules-executor filterClassName="java.lang.Integer" filterResults="true" rulesetUri="/rulesets/myRule.rls" */ private com.bea.p13n.controls.rules.RulesExecutorControl --- other Actions go here --- /** * @jpf:action * @jpf:forward name="success" path="success.jsp" * @jpf:forward name="error" path="error.jsp" */ protected Forward ruleAction() { try { // First, get stuff into the working memory. Let‘s get the user‘s city ProfileWrapper pw = profileControl.getProfileForUser("cindymc"); String city = pw.getProperty("Addresses", "City"); List wmObjects = new ArrayList(); wmObjects.add(city); // Fire the rule. Note all the parameterization above on the control Iterator iter = rulesExecutorControl.evaluateRuleSet(wmObjects.toArray()); // Get the results. We already filtered on Integer for the results, so only Integer will // be in the results. Should be only one. while (iter.hasNext()) { Integer score = (Integer)iter.next(); if (score.intValue() > 100) { pw.setProperty("Scores", score); // or whatever } } } catch (Exception e) { return new Forward("error"); } return new Forward("success"); } }
Summary
The Portal rules service provides access to real-time business intelligence for Portal applications. It may be invoked via the RulesManager EJB, or the RulesExecutorControl. The EJB has been available for some time in Portal, while the control will become fully supported in Portal SP3. In the meantime, that control is available on dev2dev, though its use is not supported until SP3.


Showing messages 1 through 1 of 1.
rules
2005-07-05 11:56:39 cafepost [Reply |View]
I have created an "rls" file with several rules that I want to use. When I omit the rule name so I can use all the rules in the rule setm exactly the way the sample did:
/**
* @common:control
* @jc:rules-executor filterClassName="java.lang.String" filterResults="true" rulesetUri="/rulesets/tmobile.rls"
*/
private com.bea.p13n.controls.rules.RulesExecutorControl rulesExecutorControl;
But I get an error:
"ruleName property cannot be null"
The sample clearly has done it that way to achieve that same effect. What am I missing?
Article Tools
E-mail
Print
Discuss
Blog
Related Products
Check out the products mentioned in this article:WebLogic Portal
_xyz