Creating Personalized Applications with the Advisor

 

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

This section includes the following topics:

• 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

• 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

  • Selecting Content 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 informaton. It can retrieve any type of content from a Document Management system and display it in a JSP or use it in a servlet.

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 Service

• Content Management

• Foundation

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 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 the Javadoc.) Think of the Advisor as sitting on top of the core services to provide a unified personalization API.

The 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.

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" on page 2-5 and "Classifying Users with the Advisor Session Bean" on page 2-10.

• Documents returned by document attribute searches. For more information about searching for content, see "Selecting Content with the <pz:contentQuery> JSP Tag" on page 2-6 and "Selecting Content with the Advisor Session Bean" on page 2-11.

• Documents returned by content selectors using rules-based matching against user profile information. For more information about rules-based matching, see "Matching Content to Users with the <pz:contentSelector> JSP Tag" on page 2-7 and "Matching Content to Users with the Advisor Session Bean" on page 2-13.

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 Service, and turning on or off the supplied content based on the results of the rules execution.

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 bean recommends content to personalized applications by matching advice requests with registered advislets that perform recommendations.

 

---

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 the chapter "Creating and Managing Content."

• 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.

  Note: For information about defining a content selector rule, see "Creating a content selector rule" in the

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" on page 2-8.

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: For information about creating classifier rules, see the topic "Creating a classifier rule" in the chapter Creating and Managing Rules in the WebLogic Personalization Server User's Guide.

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="jdbc://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 directly to classify users. For more information, see the topic "Classifying Users with the Advisor Session Bean" on page 2-10 .

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.

The following 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: 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 Selecting Content 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.

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

Note: For information about creating classifier rules, see the topic "Creating a classifier rule" in the chapter Creating and Managing Rules in the WebLogic Personalization Server User's Guide.

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" ruleSet="jdbc://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 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 and Figure 2-1 provide a general overview of the process involved for an application to get advice from the Advisor.

1. Create an instance of the Advisor session bean.

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

   This method also determines the best advislet to use for the request by mapping theKindOfRequest to the best fit advislet.

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

4. Call the advise method.

   The Advisor calls the best advislet to make the recommendation. The advislet determines the recommendations and the 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 Advisor, the Advisor bean delegates the request to a registered advislet that can handle the request. The Advisor's job is to determine which registered advislet is best suited for making recommendations for the request, based on the advice request type.

The Advisor uses the advice request type to determine which registered advislet to delegate the advice request to. The advislet then makes the recommendations and returns the advice results back to the Advisor. This design encapsulates all of the advice logic into the advislet and allows advislets to be specialized.

Figure 2-1 Mapping a Request to an Adviselet

Table 2-1 shows the logic the Advisor uses to determine how to map a recommendation request to an advislet. Note that some combinations are not valid. For example, you cannot send a <pz:bea.rules> technique request with a ContentQueryAdviceRequest.

Table 2-1 Mapping an Advise Request to an Advislet

Kind of Advice Request	Inferred Advislet
ClassificationAdviceRequest	ClassificationAdvislet Uses rules-based matching with an inference engine that classifies a user.
ContentSelectorAdviceRequest	ContentSelectorAdvislet 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.
ContentQueryAdviceRequest	ContentQueryAdvislet Performs a content attribute search with a content management system.

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: All classes used here reside in the com.beasys.commerce.axiom.* packages.

1. Create an instance of the Advisor session bean.

2. Call the 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 P13NJspHelper.createP13NSession(HttpServletRequest))

   • User object (retrieved from P13NJspHelper.createP13NProfile(HttpServletRequest))

   • Request object (retrieved from P13NJspHelper.createP13NRequest(HttpServletRequest))

   • java.sql.Timestamp object representing now

   • rule set name (For more information, see the topic "What are Rule Sets?" in the chapter Creating and Managing Rules in the WebLogic Personalization Server User's Guide.)

   • rule name (For more information, see the chapter Creating and Managing Rules in the WebLogic Personalization Server User's Guide.)

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

4. Call the advise method on the Advisor.

5. The 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/
advisor/ClassificationExample.java

try
{
    ClassificationAdviceRequest request = null;
    AdviceRequest arequest = anAdvisor.createRequestTemplate
        ("ClassificationAdviceRequest");
    request = (ClassificationAdviceRequest)arequest;
    HttpServletRequest someRequest = (HttpServletRequest)
        pageContext.getRequest();
    ConfigurableEntity user = P13NJspHelper.createP13NProfile(httpRequest);
    request.setUser(user);

    request.setHttpRequest(P13NJspHelper.createP13NRequest(httpRequest));
    request.setHttpSession(P13NJspHelper.createP13NSession(httpRequest));
    request.setNow(new Timestamp(System.currentTimeMillis()));
    request.setRuleSet(ruleset);
    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. (For more information, see "Classifying Users with the JSP <pz:div> Tag" on page 2-5.

Selecting Content with the Advisor Session Bean

For content selection 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 content (refer to the Javadoc for API details).

1. Create an instance of the Advisor session bean.

2. Call the 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 Advisor.

5. The 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(
        "ContentQueryAdviceRequest");

    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. (For more information, see Selecting Content with the <pz:contentQuery> JSP Tag.)

Matching Content to Users with the Advisor Session Bean

For content matching 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: All classes used here reside in the com.beasys.commerce.axiom.p13n.* packages.

1. Create an instance of the Advisor session bean.

2. Call the 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 P13NJspHelper.createP13NSession(HttpServletRequest))

   • User object (retrieved from P13NJspHelper.createP13NProfile(HttpServletRequest))

   • Request object (retrieved from P13NJspHelper.createP13NRequest(HttpServletRequest))

   • java.sql.Timestamp object representing now

   • rule set name (For more information, see the topic "What are Rule Sets?" in the chapter Creating and Managing Rules in the WebLogic Personalization Server User's Guide.)

   • rule name (For more information, see the chapter Creating and Managing Rules in the WebLogic Personalization Server User's Guide.)

   • Successor object (that is, 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 Advisor.

5. The 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: 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/advisor/ContentSelectorExample.java

try
{
    AdviceRequest arequest = anAdvisor.createRequestTemplate
        ("ContentSelectorAdviceRequest");

    request = (ContentSelectorAdviceRequest)arequest;
    HttpServletRequest someRequest =
        (HttpServletRequest)pageContext.getRequest();
    ConfigurableEntity user = P13NJspHelp.createP13NProfile(someRequest);

    request.setUser(user);
    request.setHttpRequest(P13NJspHelper.createP13NRequest(someRequest));
    request.setHttpSession(P13NJspHelper.createP13NSession(someRequest));
    request.setNow(new Timestamp(System.currentTimeMillis()));
    request.setRuleSet(ruleset);
    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. (For more information, see Matching Content to Users with the <pz:contentSelector> JSP Tag.)