Creating Personalized Applications with the Personalization Advisor

 

The following topics are included:

What is the Personalization Advisor?

Creating Personalized Applications with 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 Personalization Advisor Session Bean

Specifying a personalization technique URL

Classifying users with the Personalization Advisor Session Bean

Selecting content with the Personalization Advisor Session Bean

Matching content to users with the Personalization Advisor Session Bean

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

Personalization Advisor recommends content by matching content to user profiles and producing a personalized application for the user. In essence, Personalization Advisor ties together all the other services and components in the system to deliver personalized content.

 

---

What is the Personalization Advisor?

The Personalization Advisor delivers content to a personalized application based on a set of rules and user profile information. The Personalization Advisor, a stateless session bean that gives personalized advice and recommendations, can retrieve any type of content in a Document Management system and display it with a JSP page or use it in a servlet. In the WLPS 2.0 release, it gives advice on user classifications and recommends content.

The Personalization Advisor provides access to dynamic personalization functionality through JSP tags and a stateless session bean. It is a key component of the WebLogic Personalization Server because it ties together the core personalization server services that include:

• Foundation

• User Profile Management

• Rules Service

• Content Management

The Personalization Advisor component includes a JSP tag library and a Personalization Advisor EJB stateless session bean that accesses the core personalization services. The tag library and session bean contain personalization logic to access these services, sequence personalization actions, and return personalized content to the application.

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

Personalization Advisor gathers information from the user profile provided by the User Management component, submits that information to the rules service, runs the resulting queries against the Document Management System used in the Content Management component, and returns the content to the JSP developer.

In addition, Personalization Advisor provides information about user classifications. For example, an application can ask Personalization Advisor if, based on pre-defined 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 Service, and turning on or off the supplied content based on the results of the rules execution.

For WebLogic Personalization Server 2.0, Personalization Advisor recommends document content for the following items:

• Documents returned by content selectors using rules-based matching against user profile information. See Matching content to users with the <pz:contentselector> JSP tag for more information about rules-based matching.

• Web content included or excluded as determined by a user's classification using rules-based matching against user profile information. See Classifying users with the JSP <pz:div> tag for more information about classifying users.

• Documents returned by document attribute searches. See Selecting content with the <pz:contentquery> JSP tag for more information about searching for content.

You get advice from Personalization 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 on and off content 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:contentquery>, and <pz:contentselector>

• Using the Personalization Advisor session bean. The Personalization Advisor session bean recommends content to personalized applications by matching advice requests with registered personalization agents that perform recommendations. The page or application developer may use the PersonalizationAdvisor Session bean directly in place of the tags, if desired.

 

---

Creating Personalized Applications with JSP Tags

Personalization Advisor provides three JSP tags to help developers create personalized applications. These tags provide a JSP view to the Personalization 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 Personalization Advisor's <pz:div> and <pz:contentselector> tags. The <pz:contentquery> tag does not require you to 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> 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: See Creating and Managing Content for more information about how WLPS manages content.

• The <pz:contentselector> 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.

  Note: See Creating a content selector rule for information about defining a content selector rule.

In addition to using JSP tags to create personalized applications, you can work directly with the advisor bean. See Creating Personalized Applications with the Personalization Advisor Session Bean for more information about using the 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: See Creating a classifier rule for information about creating classifier rules.

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 ruleset="ejb://com.beasys.commerce.axiom.reasoning.rules.RulesheetDefinitionHome/AcmeRules" rule="PremierCustomer">
    <p>Please check out our new Premier Customer bonus program<p>
</pz:div>

You can also use the advisor bean to classify users. See Classifying users with the Personalization Advisor Session Bean for more information about using the bean to classify users.

Note: The terms rulesheet and ruleset refer to the same object and are used interchangeably throughout this documentation.

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: See<pz:contentquery> for information about using the <cm:select> JSP tag. This tag currently provides similar functionality to the <cm:select> tag.

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

<%@ taglib uri="pz.tld" prefix="pz" %>
.
.
.
<pz:contentquery id="docs" contenthome="com.beasys.commerce.axiom.document.DocumentManager" query="author = 'Hemmingway'" />

<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: See <cm:printproperty> and <es:foreachinarray> for more information about the <cm:printproperty> and <es:foreachinarray> JSP tags.

You can also use the advisor bean to select content. See Selecting content with the Personalization Advisor Session Bean for more information about using the bean to select content.

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 Personalization Advisor executes the query defined in the rule to retrieve content. See <pz:contentselector> for more information about the <pz:contentselector> tag.

Note: See Creating a content selector rule for more information about using content selector rules.

This example asks the Personalization 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" ruleset="ejb://com.beasys.
    commerce.axiom.reasoning.rules.
    RulesheetDefinitionHome/AcmeRules"
    rule="PremierCustomerSpotlight"
    contenthome="com.beasys.commerce.axiom.document.
    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 to match content to users. See Matching content to users with the Personalization Advisor Session Bean for more information about using the bean to match content to users.

 

---

Creating Personalized Applications with the Personalization 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. Refer to the API documentation for more information about using the session bean to create personalized applications.

The Personalization Advisor's agent implementation encapsulates all of the logic and operations required for the request types it handles. It makes recommendations and returns a type of AdviceResults to the Personalization Advisor. In general, the process includes the following steps:

1. Create an instance of the Personalization Advisor Session bean.

2. Use the Personalization Advisor's createTemplate factory method to create a Request object.

   This method also determines the best Advice Agent to use for the request by mapping the AdviceRequestClassName and technique to the best fit Agent. The technique name uses the technique name parameter in the JSP tags <pz:bea.rules> and <pz:bea.query>. See Specifying a personalization technique URL for more information about specifying the request technique.

3. Set the required and optional inputs for the Request object.

4. Call the advise method.

   The Personalization Advisor calls the best agent to make the recommendation. The agent determines the recommendations and the Personalization Advisor then passes the AdviceResults object back to the application.

5. The personalized application extracts the recommendation from the AdviceResults object and uses it in the application.

When a personalized application requests advice from the Personalization Advisor, the Personalization Advisor bean delegates the request to a registered personalization agent that can handle the request. The Personalization Advisor's job is to determine which registered personalization agent is best suited for making recommendations for the request, based on the advice request type and the personalization technique.

The Personalization Advisor uses the advice request type and a personalization technique identifier to determine which registered personalization agent to delegate the advice request to. The agent then makes the recommendations and returns the advice results back to the Personalization Advisor. This design encapsulates all of the advice logic into the agent and allows agents to be specialized.

Specifying a personalization technique URL

To execute a recommendation request, the Personalization Advisor requires that you specify a personalization technique URL. Pass in a personalization technique identifier that specifies the personalization namespace, vendor, and technique. The personalization technique identifier follows the JDBC driver specification:

namespace:vendor.technique

• The namespace represents the personalization namespace. The Personalization Advisor only accepts the pz namespace in WLPS 2.0.

• The vender is the name of the vendor supplying the personalization technique. For the 2.0 release, bea is the vendor name.

• The technique is the name given to the Personalization Advisor to determine which Personalization Agent can best perform the recommendation request.

  Note: For the 2.0 release, the Personalization Advisor accepts the following personalization technique names:

  • rules

  • query

The table shows the logic the Personalization Advisor uses to determine how to map a recommendation request to a Personalization Agent. Note that some combinations are not valid. For example, you cannot send a <pz:bea.rules> technique request with a ContentQueryAdviceRequest.

.

Personalization Technique	Advice Request Type	Inferred Personalization Agent
pz:bea.rules	ClassificationAdviceRequest	ClassificationAgent Uses rules-based matching with an inference engine that classifies a user.
pz:bea.rules	ContentSelectorAdviceRequest	ContentSelectorAgent Uses rules-based matching with an inference engine to classify a user Determines if the user matches the classification Selects content based on a content query.
pz:bea.query	ContentQueryAdviceRequest	ContentQueryAgent Performs a content attribute search with a content management system.

Classifying users with the Personalization Advisor Session Bean

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

Note: All classes used here reside in the com.beasys.commerce.axiom.p13n.* packages.

1. Create an instance of the Personalization Advisor Session bean.

2. Call the Personalization Advisor's createTemplate method to get the correct AdviceRequest object. In this case, it should return a ClassificationAdviceRequest.

3. Set the required objects on the ClassificationAdviceRequest. These include the:

   • Session object (retrieved from P13NJspBase.createP13NSession(HttpServletSession))

   • User object (retrieved from P13NJspBase.createP13NProfile(HttpServletSession))

   • Request object (retrieved from P13NJspBase.createP13NRequest(HttpServletSession))

   • java.sql.Timestamp object representing now

   • rulesheet name (see What are Rulesheets? for more information)

   • rule name (see Creating and Managing Rules for more information)

   • optional Successor object (for example, the user's group).

4. Call the advise method on the Personalization Advisor.

5. The Personalization Advisor returns a subclass of AdviceResults. In this case, it should return a ClassificationAdviceResults object. If the classification object exists in the results, the classification is true. If the object is null, the classification is not true.

A basic example of using the bean for classification might look like the following:

Note: This code is just a model and is not complete. The complete example resides in the following files:
<WLPS_installation_directory>/server/public_html/portals/repository/portlets/advisor_ejb_example.jsp
<WLPS_installation_directory>/src/examples/
p13nadvisor/ClassificationExample.java

try
{
    ClassificationAdviceRequest request = null;
    AdviceRequest arequest = anAdvisor.createRequestTemplate
        ("com.beasys.commerce.axiom.p13n.agents.ClassificationAdviceRequest",
        "pz:bea.rules");
    request = (ClassificationAdviceRequest)arequest;
    HttpServletRequest someRequest = (HttpServletRequest)
        pageContext.getRequest();
    P13NJspBase page = (P13NJspBase)pageContext.getPage();
    ConfigurableEntity user = page.createP13NProfile(httpRequest);
    request.setUser(user);

    request.setHttpRequest(page.createP13NRequest(httpRequest));
    request.setHttpSession(page.createP13NSession(httpRequest));
    request.setNow(new Timestamp(System.currentTimeMillis()));
    request.setRuleSheet(rulesheet);
    request.setRule(rule);

    AdviceResults result = anAdvisor.advise(request);
    Classification classification = ((ClassificationAdviceResults)result).
        getClassification();
    return classification != null;
    }
catch(Exception e)
{
    e.printStackTrace();
}

Note: You can also use the JSP <pz:div> tag to classify users. See Classifying users with the JSP <pz:div> tag for more information about using the tag to classify users.

Selecting content with the Personalization Advisor Session Bean

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

1. Create an instance of the Personalization Advisor Session bean.

2. Call the Personalization Advisor's createTemplate method to get the correct AdviceRequest object. In this case, it should return a ContentQueryAdviceRequest.

3. Set the parameters on the ContentQueryAdviceRequest, including:

   • contentHome (required): the JNDI name to find a content home

   • query (required): the query to run against the system

   • sortBy (optional)

   • max (optional)

4. Call the advise method on the Personalization Advisor.

5. The Personalization Advisor returns a subclass of AdviceResults. In this case, it should return a ContentQueryAdviceResults object, from which you can retreive an array of Content objects.

A basic example of using the bean for a content query might look like the following:

try
{
    AdviceRequest arequest = anAdvisor.createRequestTemplate(
        "com.beasys.commerce.axiom.p13n.agents.ContentQueryAdviceRequest",
        "pz:bea.query");

    request = (ContentQueryAdviceRequest)arequest;
    request.setQuery(query);
    request.setMax(max);
    request.setSortBy(sortby);
    request.setContentHome(home);

    AdviceResults result = anAdvisor.advise(request);
    Collection docs = ((ContentQueryAdviceResults)result).getContent();
    if (docs==null)
    {
        return new Content [0];
    }
    return (Content[])docs.toArray(new Content[docs.size()]);

}
catch(Exception e)
{
    e.printStackTrace();
}

Note: You can also use the JSP <pz:contentquery> tag to select content. See Selecting content with the <pz:contentquery> JSP tag for more information about using the tag to select content.

Matching content to users with the Personalization Advisor Session Bean

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

Note: All classes used here reside in the com.beasys.commerce.axiom.p13n.* packages.

1. Create an instance of the Personalization Advisor Session bean.

2. Call the Personalization Advisor's createTemplate method to get the correct AdviceRequest object. In this case, it should return a ContentSelectorAdviceRequest.

3. Set the required objects on the ClassificationAdviceRequest. These include the:

   • Session object (retrieved from P13NJspBase.createP13NSession(HttpServletSession))

   • User object (retrieved from P13NJspBase.createP13NProfile(HttpServletSession))

   • Request object (retrieved from P13NJspBase.createP13NRequest(HttpServletSession))

   • java.sql.Timestamp object representing now

   • rulesheet name (see What are Rulesheets? for more information)

   • rule name (see Creating and Managing Rules for more information)

   • optional Successor object (e.g., the user's group).

   • contentHome (required): the JNDI name to find a content home

   • query (required): the query to run against the system

   • sortBy (optional)

   • max (optional)

4. Call the advise method on the Personalization Advisor.

5. The Personalization Advisor returns a subclass of AdviceResults. In this case, it should return a ContentQueryAdviceResults object, from which you can retreive an array of Content objects.

A basic example of using the bean for content selection might look like the following (note that this code is just a model and not complete):

Note: This code is just a model and is not complete. The complete example resides in the following files:
The complete example resides in the following files:
<WLPS_installation_directory>/server/public_html/portals/
repository/portlets/advisor_ejb_example.jsp
<WLPS_installation_directory>/src/examples/p13nadvisor/ContentSelectorExample.java

try
{
    AdviceRequest arequest = anAdvisor.createRequestTemplate
        ("com.beasys.commerce.axiom.p13n.agents.ContentSelectorAdviceRequest",
        "pz:bea.rules");

    request = (ContentSelectorAdviceRequest)arequest;
    HttpServletRequest someRequest =
        (HttpServletRequest)pageContext.getRequest();
    P13NJspBase page = (P13NJspBase)pageContext.getPage();
    ConfigurableEntity user = page.createP13NProfile(someRequest);

    request.setUser(user);
    request.setHttpRequest(page.createP13NRequest(someRequest));
    request.setHttpSession(page.createP13NSession(someRequest));
    request.setNow(new Timestamp(System.currentTimeMillis()));
    request.setRuleSheet(rulesheet);
    request.setRule(selector);
    request.setMax(max);
    request.setSortBy(sortby);
    request.setContentHome(home);
    request.setQuery(query);

    AdviceResults result = anAdvisor.advise(request);
    Collection docs = ((ContentQueryAdviceResults)result).getContent();
}
catch(Exception e)
{
    e.printStackTrace();
}

Note: You can also use the JSP <pz:contentselector> tag to match content to users. See Matching content to users with the <pz:contentselector> JSP tag for more information about using the tag to match content to users.