Creating Personalized Applications with the Advisor

 

The WLPS Advisor is an easy-to-use and flexible access point for personalization services-including personalized content, user segmentation and the underlying rules engine.

This topic includes the following sections:

• What Is the Advisor?

  • The Advisor Delivers Content to a Personalized Application

  • The Advisor Provides Information About User Classifications

  • You Can Use the Advisor in One of Two Ways

• The WLPS Advisor Architecture

  • Writing a Custom Advislet

  • Understanding the Advislet Registry

  • Registering a Single Advislet

  • Advislet Chaining

  • Registering a Compound Advislet

• Creating Personalized Applications with the Advisor JSP Tags

  • Classifying Users with the JSP <pz:div> Tag

  • Selecting Content with the <pz:contentQuery> JSP Tag

  • Matching Content to Users with the <pz:contentSelector> JSP Tag

• Creating Personalized Applications with the Advisor Session Bean

  • Classifying Users with the Advisor Session Bean

  • Querying a Content Management System with the Advisor Session Bean

  • Matching Content to Users with the Advisor Session Bean

 

---

What Is the Advisor?

Content personalization allows Web developers to tailor applications to users. Based on data gathered from user profile, Request, and Session objects, the Advisor coordinates the delivery of personalized content to the end user.

The Advisor Delivers Content to a Personalized Application

The Advisor delivers content to a personalized application based on a set of rules and user profile information. It can retrieve any type of content from a Document Management system and display it in a JSP.

The Advisor ties together all the services and components in the system to deliver personalized content. The Advisor component includes a JSP tag library and an Advisor EJB (stateless session bean) that access the WebLogic Personalization Server's core personalization services including:

• User Profile Management

• Rules Manager

• Content Management

• Foundation Platform

The tag library and session bean contain personalization logic to access these services, sequence personalization actions, and return personalized content to the application. It is also possible to write your own adivslets and access them with JSP tags you create.

This architecture allows the JSP developer to take advantage of the personalization services using the Advisor JSP tags. In addition, a Java developer can access the underlying Personalization EJB and its features via the public Advisor bean interface. (For more information, see the API documentation in theWebLogic Personalization Server Javadoc.) Think of the Advisor as sitting on top of the core services to provide a unified personalization API.

The Advisor recommends document content for the following items:

• Web content included or excluded as determined by a user's classification using rules-based matching against user profile information. For more information about classifying users, see Classifying Users with the JSP <pz:div> Tag and Classifying Users with the Advisor Session Bean.

• Documents returned by document attribute searches. For more information about searching for content, see Selecting Content with the <pz:contentQuery> JSP Tag and Querying a Content Management System with the Advisor Session Bean.

• Documents returned by content selectors using rules-based matching against user profile information or user's classification. For more information about rules-based matching, see Matching Content to Users with the <pz:contentSelector> JSP Tag and Matching Content to Users with the Advisor Session Bean.

Note: User classification is done in the E-Business Control Center. You will see the term "customer segmentation" used in the GUI tool to refer to user classification and classifier rules.

The Advisor Provides Information About User Classifications

In addition to supplying content to a personalized application, the Advisor can also provide information about user classifications. For example, an application can ask the Advisor if, based on predefined rules, the current user is classified as a Premier Customer or an Aggressive Investor, and take action accordingly. The Advisor accomplishes this classification by gathering relevant user profile information, submitting it to the Rules Manager, and returning the classification to the caller.

For more information about classifying users, see Classifying Users with the JSP <pz:div> Tag and Classifying Users with the Advisor Session Bean.

You Can Use the Advisor in One of Two Ways

• Using the JSP tags. Developers will probably find it most useful to use the JSP tags when building typical pages. The tags provide ways to switch content on and off based on user classification, return content based on a static query, and match content to users based on rules that execute a content query. The JSP tags that perform these tasks are: <pz:div> , <pz:contentSelector>, and <pz:contentQuery>.

• Using the Advisor session bean. The page or application developer may use the Advisor session bean directly in place of the tags, if desired. The Advisor session beans provide ways to switch content on and off based on user classification, return content based on a static query, and match content to users based on rules that execute a content query.

 

---

The WLPS Advisor Architecture

The Advisor is a stateless session EJB and has a simple interface with a getAdvice method on it. The getAdvice method returns Advice objects that contain the detailed result information that was returned from the personalization services.

The argument to the getAdvice method is an AdviceRequest object that contains a number of name-value pairs that define the inputs to the Advisor. The AdviceRequest has an interface very similar to the HttpSession object and allows predefined as well as custom input parameters to be stored.

Each incoming AdviceRequest has a URI associated with it. The Advisor uses the URI prefix (the part before the colon) to look up an Advislet using the AdvisletRegistry. Advislets are typically simple Java classes that implement a personalization function such as user segmentation or content retrieval. The AdvisletRegistry maintains the deployment mappings from URI prefixes to Advislet instances.

Note: The relationship between the Advisor and an Advislet is similar to the relationship between the Server and a servlet (though an Advislet is independent of HTTP). An Advislet is registered with a prefix with the Advisor and will be invoked for all incoming AdviceRequests with that prefix.

Figure 2-1 The Advisor Architecture

 

 

---

Writing Custom Advislets and Registering Them Using the Advislet Registry

At the core of the Advisor framework is the Advislet Registry. The Advislet uses the Advislet Registry to determine which Advislets to invoke in the processing of a request.

The WebLogic Commerce Server provides a number of Advislets which support the three personalization JSP tags: <pz:classifier>, <pz:contentselector> and <pz:contentquery>. To extend this functionality or to interface with third-party systems, you can write a custom Advislet and register it with the Advislet Registry.

Writing a Custom Advislet

To write a custom Advislet a developer simply has to implement the Advisor interface, providing implementations of these three methods: getAdvice, getRequiredAttributes and validateAdviceRequest.

When the Advisor receives an AdviceRequest object, it calls validateAdviceRequest before passing it to the registered Advislet's getAdvice method. The validateAdviceRequest method should throw an IllegalArgumentException if some necessary attributes are missing or malformed.

In addition to the Advislet interface, an Advislet implementation must have a public constructor with two parameters. The Advisor will use these parameters when it creates instances of the Advislet.

• The first parameter is of type Advisor. It contains a reference to the Advisor creating this Advislet.

• The second parameter is an implementation of the Metadata interface. It contains the Advislet's name, description, and versioning information as specified in the Advislet Registry.

Note: Unless otherwise indicated, all classes referenced here reside in the com.bea.commerce.platform.advisor package.

A default implementation of Advislet is provided in the AbstractAdvislet abstract class. Simply extend this class, override the getAdvice method and provide the required constructor to create your own Advislet.

Understanding the Advislet Registry

We have already discussed how the Advislet Registry associates uri prefixes with Advislet implementations. Once we look inside the Advislet Registry however, the story becomes a bit more complicated.

In the case of the contentquery:// prefix, all of the work is done in one class- com.bea.commerce.platform.content.advislets.ContentQueryAdvisletImplHowever, other prefixes (such as contentselector://) require a sequence of Advislets to be chained together to produce the required advice. In these cases a CompoundAdvislet is registered against the uri prefix to shield this complexity from the user. The specification of which Advislets to register against which uri prefixes is contained in the advislet-registry.xml which can be found in the WLCS root directory. An understanding of the contents of this file is essential to any customization of the Advislet framework.

Registering a Single Advislet

The following is an extract from the advislet-registry.xml file:

<!-- run a content query -->
<advislet>
<registration-key>contentquery</registration-key>
<metadata>
   <name>ContentQuery</name>
   <description>
   Advislet that can retrieve content from the Content Management
   System based on a content query.
   </description>
   <author>BEA Systems</author>
         
</metadata>
<implementation-class>com.bea.commerce.platform.content.advislets.ContentQueryAdvisletImpl</implementation-class>
</advislet>

The most important tags are <registration-key> and <implementation-class>. In the case of an Advislet, <registration-key> should specify the uri prefix that this Advislet is to be registered against and <implementation-class> should specify the fully qualified class name of the implementing Advislet class. The metadata information is useful for versioning Advislets and should be included.

Advislet Chaining

AdviceTransform objects are used to chain two Advislets together using a CompoundAdvislet. An AdviceTransform object provides the mapping between the outputs of one Advislet and the inputs of the next. The AdviceTransform interface simply specifies one method transform (Advice input, AdviceRequest output ). which should be implemented to create the mapping required. AdviceTransforms are also registered in the AdvisletRegistry.

Registering a Compound Advislet

The following is an extract from the advislet-registry.xml file:

<!-- compound advislet that calls the rules engine and passes results to the content management system -->

<compound-advislet>
   <registration-key>contentselector</registration-key>
   <metadata>
      <name>ContentSelector</name>
      <description>
      Advislet that retrieves Content from the Content Management
      system based on the evaluation of a rule set.
      </description>
      <author>BEA Systems</author>
      
   </metadata>
   <sequence>
      <advice-transform>RulesInputTransform</advice-transform>
      <advislet>unmappedrulesClassifierIgnoreRuleName</advislet>
      <advice-transform>
          ClassifierToContentSelectorTransform
      </advice-transform>
      <advislet>unmappedrulesContentSelector</advislet>
      <advice-transform>
          RulesToContentTransform
      </advice-transform>
      <advislet>contentquery</advislet>
   </sequence>
</compound-advislet>

The <sequence> tag specifies the start of the sequence that makes up the compound. Entries can be either Advislets or AdviceTransforms which can occur in any order. The Advisor will invoke each element of the sequence in turn before proceeding to the next. The final Advice object generated will be returned to the user. In this way the implementation of the Advislet is hidden from the user who does not need to know whether a simple Advislet or a compound Advislet was used to generate the advice.

 

---

Creating Personalized Applications
with the Advisor JSP Tags

The Advisor provides three JSP tags to help developers create personalized applications. These tags provide a JSP view to the Advisor session bean and allow developers to write pages that retrieve personalized data without writing Java source code.

Note: You must insert the following JSP directive into your JSP code to use the Advisor's <pz:div> and <pz:contentSelector> tags. The <pz:contentQuery> tag does not require that you extend the class.

<%@ page extends="com.beasys.commerce.axiom.p13n.jsp.P13NJspBase" %>

• The <pz:div> tag turns user-provided content on or off based on the results of a classifier rule being executed. If the result of the classifier rule is true, it turns the content on; if false, it turns the content off.

  Note: The system turns on the content by inserting the content residing between the start and end <pz:div> tags in the JSP code. This content can include any valid JSP, including HTML tags, other JSP tags, and scriptlets. If the classifier rule returns false, the system skips the content between the start and end <pz:div> tags.

• The <pz:contentQuery> tag provides content attribute searching for content in a Content Manager. It returns an array of Content objects that a developer can handle in numerous ways.

  Note: For more information about how WebLogic Personalization Server manages content, see Creating and Managing Content, in this guide.

• The <pz:contentSelector> tag recommends content if a user matches the classification part of a content selector rule. When a user matches, the personalization engine executes a content query defined in the rule and returns the content back to the JSP page.

For information about defining a content selector rule, see "Retrieving Documents with Content Selectors" inUsing the E-Business Control Center.

In addition to using JSP tags to create personalized applications, you can work directly with the Advisor bean. For more information about using the bean, see Creating Personalized Applications with the Advisor Session Bean.

Classifying Users with the JSP <pz:div> Tag

The <pz:div> tag turns user-provided content on or off based on the results of a classifier rule being executed. If the result of the classifier rule is true, it turns the content on; if false, it turns the content off.

Note: Rules are created in the E-Business Control Center. This GUI tool is designed to allow Business Analysts (BAs) to develop their own classifier rules. Because the Business Analysts are not exposed to the concept of rules, you will see classifer rules referred to as "customer segmentation."

For information about creating classifier rules with the E-Business Control Center, see the topic "Creating a New Customer Segment" in the chapter "Using Customer Segments to Target High-Value Markets" inUsing the E-Business Control Center.

You can also use the Advisor bean directly to classify users. For more information, see Classifying Users with the Advisor Session Bean.

Example

This example executes the PremierCustomer classifier rule and displays an alert to premier customers in the HTML page's output.

<%@ taglib uri="pz.tld" prefix="pz" %>
.
.
.
<pz:div 
rule="PremierCustomer">
    <p>Please check out our new Premier Customer bonus program<p>
</pz:div>

Selecting Content with the <pz:contentQuery> JSP Tag

The <pz:contentQuery> tag provides content attribute searching for content in a Content Manager. It returns an array of Content objects that a developer can handle in numerous ways.

Note: For information about using the <pz:contentQuery> JSP tag, see <pz:contentQuery>. This tag provides similar functionality to the <cm:select> tag.

Example

The following example executes a query against the content management system to find all content where the author attribute is Hemingway and displays the Document titles found:

<%@ taglib uri="pz.tld" prefix="pz" %>
<%@ page import="com.beasys.commerce.content.ContentHelper"%> 
.
.
.
<pz:contentQuery id="docs" contentHome="<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME %>" query="author = 'Hemingway'" />

<ul>
   <es:forEachInArray array="<%=docs%>" id="aDoc"
   type="com.beasys.commerce.axiom.content.Content">
      <li>The document title is: <cm:printProperty id="aDoc"
      name="Title" encode="html" />
   </es:forEachInArray>
</ul>

Note: For more information about these JSP tags, see <cm:printProperty> and <es:forEachInArray>.

You can also use the Advisor bean directly to select content. For more information, see Querying a Content Management System with the Advisor Session Bean.

Matching Content to Users with the <pz:contentSelector> JSP Tag

The <pz:contentSelector> recommends content if a user matches the classification part of a content selector rule. When a user matches based on a rule, the Advisor executes the query defined in the rule to retrieve content.

Notes: For more information about this tag, see <pz:contentSelector>.

For information about creating classifier rules, see the chapter "Using Customer Segments to Target High-Value Markets" inUsing the E-Business Control Center.

Example

The following example asks the Advisor for content specific to premier customers and then displays the Document titles as the results.

<%@ taglib uri="pz.tld" prefix="pz" %>
.
.
.
<pz:contentSelector id="docs" 
    rule="PremierCustomerSpotlight"
    contentHome="<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME %>" 
    DocumentManager" />
<ul>
   <es:forEachInArray array="<%=docs%>" id="aDoc"
   type="com.beasys.commerce.axiom.content.Content">
      <li>The document title is: <cm:printProperty id="aDoc"
      name="Title" encode="html" />
   </es:forEachInArray>
</ul>

You can also use the Advisor bean directly to match content to users. For more information, see Matching Content to Users with the Advisor Session Bean.

 

---

Creating Personalized Applications with the Advisor Session Bean

Java developers can work directly against the Advisor bean through a set of APIs to create personalized applications. This process provides an alternative to using the JSP tags to call into the bean.

Note: Refer to the API documentation in the Javadoc for more information about using the session bean to create personalized applications.

The following steps provide a general overview of the process involved for an application to get content recommendations from the Advisor.

1. Look up an instance of the Advisor session bean.

2. Use the AdvisorFactory's static createAdviceRequest method to create an AdviceRequest object.

Note: You must provide this method with the uri representing the request. The Advisor uses the uri prefix to determine which Advislet to invoke to recommend content.

1. Set the required and optional attributes for the AdviceRequest object.

2. Call the Advisor's getAdvice method.

   The Advisor calls the best Advislet to make the recommendation. The Advislet determines the recommendations and the Advisor then passes the Advice object back to the application.

   The Advisor uses the Advislet Registry to choose the Advislet to invoke.

3. The personalized application extracts the recommendation from the Advice object and uses it in the application.

When a personalized application requests advice from the Advisor, the Advisor bean delegates the request to a registered Advislet that can handle the request. The Advisor uses the uri prefix to determine which registered Advislet will receive the advice request. The Advislet then makes the recommendations and returns the Advice object back to the Advisor. This design encapsulates all of the advice logic into the Advislet and allows developers to create custom Advislets for more specialized purposes.

Attributes objects act as parameters for the request. Attributes objects can be set on the AdviceRequest object and are associated with a String object representing the name of the attribute.

Three Advislets are supplied with the sytem: Classifier Advislet, ContentQuery Advislet and ContentSelector Advislet. Names for the attributes that need to be set on the supplied Advislets are defined as static Strings in the AdviceRequestConstants interface.

Table 2-1 shows the logic the Advisor uses to determine how to map a recommendation request to an Advislet.

Table 2-1 Mapping a URI Prefix to an Advislet

Uri Prefix	Inferred Advislet
classifier	Uses a rules-based inference engine to classify a user based on rules written using the E-Business Control Center.
contentselector	Uses a rules-based inference engine to classify a user. Determines if the user matches the classification. Uses a rules-based inference engine to obtain a content query. Selects content based on the content query obtained.
contentquery	Performs a content attribute search on a specified content management system.

 

The following sections demonstrate how to directly access the Advisor to provide the same functionality as that provided by the JSP tags.

Classifying Users with the Advisor Session Bean

For classification requirements beyond what the JSP tags provide, or to use classification in a servlet, developers can use the Advisor EJB directly. The following sequence describes the process of asking the Advisor for a classification (refer to the Javadoc for API details).

Note: Unless otherwise indicated, all classes used here reside in the com.bea.commerce.platform.advisor package.

1. Look up an instance of the Advisor session bean.

2. Use the AdvisorFactory's static createAdviceRequest method to create an AdviceRequest object. In this case,the uri argument should be "classifier://".

3. Set the required attributes on the AdviceRequest object (see AdviceRequestConstants). These include:

   • HTTP_SESSION - the session object (retrieved from P13NJspHelper.createP13NSession(HttpServletRequest)).

   • USER - the user object (retrieved from P13NJspHelper.createP13NProfile(HttpServletRequest)).

   • HTTP_REQUEST - the request object (retrieved from P13NJspHelper.createP13NRequest(HttpServletRequest)).

   • NOW - a java.sql.Timestamp object representing now.

   • RULES_RULESET_NAME - (optional) the name of the segmentation rule to fire. (For more information about customer segment rules, see Introducing the Rules Manager, in this guide.)

4. Call the getAdvise method on the Advisor.

5. The Advisor returns an instance of Advice. The getResult method is called to obtain the classification object. If a classification object is returned, then the classification is considered to be true. If the return value is null, the classification is considered to be not true.

Note: If the optional Advise Request parameter RULES_RULESET_NAME is not supplied, there may be multiple classifications returned for the user.

Querying a Content Management System with the Advisor Session Bean

For content selection requirements beyond what the JSP tags provide, or to use Content selection in a servlet, developers can use the Advisor EJB directly. The following sequence describes the process of asking the Advisor for content (refer to the Javadoc for API details).

Note: Unless otherwise indicated, all classes used here reside in the com.bea.commerce.platform.advisor package.

1. Look up an instance of the Advisor session bean.

2. Use the AdvisorFactory's static createAdviceRequest method to create an AdviceRequest object In this case, the uri argument should be "contentquery://"

3. Set the required attributes on the AdviceRequest object (see AdviceRequestConstants). These include:

   • CONTENT_MANAGER_HOME (required) - the JNDI name to find a content manager home interface.

   • CONTENT_QUERY_STRING (required) - the query to run against the system.

   • CONTENT_QUERY_SORT_BY (optional) - the order in which to sort the returned results.

   • CONTENT_QUERY_MAX_ITEMS (optional) - the maximum instances to return.

4. Call the getAdvise method on the Advisor.

5. The Advisor returns an instance of Advice. The getResult method is called to obtain the array of Content objects representing the recommendation.

Matching Content to Users with the Advisor Session Bean

For content selection requirements beyond what the JSP tags provide, or to use content selection in a servlet, developers can use the Advisor EJB directly. The following sequence describes the process of asking the Advisor for content (refer to the Javadoc for API details).

Note: Unless otherwise indicated, all classes used here reside in the com.bea.commerce.platform.advisor package.

1. Look up an instance of the Advisor session bean.

2. Use the AdvisorFactory's static createAdviceRequest method to create an AdviceRequest object. In this case the uri argument should be "contentselector://"

3. Set the required attributes on the AdviceRequest object (see AdviceRequestConstants). These include:

   • HTTP_SESSION - the session object (retrieved from P13NJspHelper.createP13NSession).

   • USER - the user object (retrieved from P13NJspHelper.createP13NProfile).

   • HTTP_REQUEST - the request object (retrieved from P13NJspHelper.createP13NRequest).

   • NOW - a java.sql.Timestamp object representing now.

   • RULES_RULESET_NAME - the name of the segmentation rule to fire. (For more information about customer segments, see the chapter Introducing the Rules Manager in this guide. )

   • CONTENT_MANAGER_HOME (required) - the JNDI name to find a content manager home interface.

   • CONTENT_QUERY_STRING (required) - the query to run against the system.

   • CONTENT_QUERY_SORT_BY (optional) - the order in which to sort the returned results.

   • CONTENT_QUERY_MAX_ITEMS (optional) - the maximum instances to return.

4. Call the getAdvise method on the Advisor.

5. The Advisor returns an instance of Advice. The getResult method is called to obtain the array of Content objects representing the recommendation.