Setting Up Personalization and Interaction Management

WebLogic Portal comes with robust authentication and personalization features that allow administrators to determine what content a visitor can interact with and how that information will appear to the specific visitor. Visitors themselves can leverage WebLogic Portals personalization features to select their own content and create their own look and feel. A major component of the portal development process is to create the resources by using such tools as the Advisor, the Rules Framework, and content selectors to make such authorization and personalization possible.

This section includes information on the following subjects:

Using the Advisor to Personalize a Portal Application

The WebLogic Portal Advisor is an easy-to-use and flexible access point for personalization services-including personalized content, user segmentation, and the underlying rules engine. 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 Portal's core personalization services including:

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 Advisor plug-ins 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 WebLogic Portal personalization features via the public Advisor bean interface. For more information, see the WebLogic Portal Javadoc API documentation.

You can use the Advisor in one of two ways:

Creating a Personalized Portal Application with Advisor JSP Tags

Classifying Users with the JSP <pz:div> Tag

The <pz:div> tag to 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. The E-Business Control Center letsusers develop their own classifier rules. Because users are not exposed to the concept of rules, you will see classifier rules referred to as "customer segments."

Listing 12-1 Using <pz:dev> to Execute a Classifier Rule

<%@ 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

Use the <pz:contentQuery> tag to provide content attribute searching of content in a content management system. It returns an array of Content objects that you can handle in numerous ways.

Listing 12-2 Executing a Query Against a CMS to Find Specified Content

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

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

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.

Listing 12-3 Asking the Advisor to Display Specific Customers

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

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: See the WebLogic Portal 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.

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.

Attribute objects act as parameters for the request. Attribute 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 system: 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.

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, use the Advisor EJB directly.

To ask the Advisor for a classification, use this procedure. (See the Javadoc API documentation for API details.)

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

Note: If the optional AdviceRequest parameter RULES_RULENAME_TO_FIRE 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.

To ask the Advisor for a content, use this procedure. (See the Javadoc API documentation for API details.)

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

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.

To ask the Advisor for a content, use this procedure. (See the Javadoc API documentation for API details.)

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

Working with the Rules Framework

Rules Management forms a key part of the personalization process by prescribing a flexible and powerful mechanism for expressing business rules. The business logic encompassed by these rules allows robust delivery of personalized content marketed specifically to each end user type.

The various components of the Rules Framework are configured with an external configuration file called rules.properties. This file resides in the p13n_util.jar file (within the com/bea/p13n/rules directory) that can be found in the root directory of any WebLogic Portal application. This section explains each of the configuration properties that can be set in this file.

Changes to the rules.properties file are only seen by the application in which the file resides. That is, this configuration file is scoped to the application. This makes it possible to configure the Rules Framework differently for different applications.

Validating Rules Expressions

Listing 12-4 Setting the rules.engine.expression.validation Property

##
# Rules engine expression validation:
#
# If this property is set to true, the rules engine
# will validate expressions the first time they are
# executed.
##
rules.engine.expression.validation=true

Rules Engine Error Handling and Reporting

The rules.engine.throw.expression.exceptions and rules.engine.ignorable.exceptions properties determine the type of exceptions that will be propagated to the user during Rules engine execution.

Listing 12-5 Rules Engine Pattern Expression Execution Error Handling

##
# Rules engine pattern expression execution error handling:
#
# rules.engine.throw.expression.exceptions
#
# If this property is set to true, pattern expression
# execution exceptions will be thrown. Otherwise, a pattern
# expression exception will cause the pattern condition to
# evaluate to false.
#
# Defaults to true.
#
# rules.engine.throwable.exceptions (list of class names)
#
# If the previous property is set to true, expression exceptions
# with embedded exceptions of a type other than the listed classes
# will be thrown. If no class types are specified, all expression
# exceptions will be thrown.
#
# Defaults to all exception class types.
##
rules.engine.throw.expression.exceptions=true
rules.engine.ignorable.exceptions=java.lang.NullPointerException

Personalization with Content Selectors

A content selector is one of several mechanisms that WebLogic Portal provides for retrieving documents from a content management system. By using content selectors, you can personalize a portal or portlet by specifying conditions under which WebLogic Portal retrieves one or more documents. For example, you can personalize a portlet that displays data from a content management system by specifying such information as a date range, the status of the user, and the user's e-mail address. The content selector would only retrieve documents that fit the selection criteria.

Use the E-Business Control Center to define the conditions that activate a content selector and to define the query the content selector uses to find and retrieve documents. Then, use the content selector JSP tags and a set of other JSP tags to retrieve and display the content targeted by the content selector.

To use the E-Business Control Center to define the conditions that activate a content selector and the query criteria, use this procedure:

The new content selector is ready to use.

Using an Edit .jsp to Personalize a Portlet

Visitors can personalize portlets by providing the necessary personalization attributes or preferences to an Edit JSP. An Edit JSP is a JSP that collects personalization data and uses it to render a personalized view of requested date.

Enabling a visitor to personalize a portlet by using an Edit JSP is a two-step process:

Step 1. Create the Edit JSP

Create the Edit JSP (or JSPs, if a Webflow is required) as you would any other JSP. You can name it anything you want and give it any appropriate look and feel. The important features of the JSP are those that allow the visitor to enter and retrieve personalized content.

For example:

As you can see, there are few restrictions as to what you need to include in an Edit JSP, so long as it meets visitor personalization requirements.

Step 2. Enable Portlet Editing

Next, you need to enable visitors to edit a portlet to add personalization information. To do this, use this procedure:

Personalizing a Portal or Portlet by Using Placeholders

Placeholders are devices that represent an area in a portal or portlet to which content is provided when certain criteria are met that define what content can appear. A placeholder is a named entity that contains one or more queries. When a visitor requests a JSP that contains a placeholder tag, the placeholder selects a single query to run—usually based upon established rules or customer properties—and generates the HTML that the browser requires to display the results of the query.

This section includes information on the following subjects:

How Placeholders are Used

Placeholders are used primarily in campaigns to direct a visitor's attention to programs, merchandise, or other information in which the visitor's behavior has indicated an interest. For example, an online sporting goods store notices that a visitor has purchased a number of fishing lures from a specific manufacturer. A rule exists that tells the portal to display information about discounts available when the visitor has spent more than a certain amount of money on products by that particular manufacturer. The visitor will see that information in the area specified as the placeholder for that content. Another visitor has shown interest in camping equipment (measured by the number of times that visitor has accessed the "Camping" pages for the sporting goods store's catalog). Instead of fishing lure discounts, the camper will see information about camping gear in the area specified as the placeholder.

The above example demonstrates how ad placeholders are used to personalize information for a specific visitor. In the same manner, non-ad placeholders can offer the same level of personalization. For example, a doctor researching drugs at a pharmaceutical company Website shows a tendency for studying a certain family of drugs. The company's portal can track his behavior and display, in a placeholder, information about, or links to, related drugs that he hasn't yet researched.

Placeholders are created by using a JSP tag and defining the placeholder queries in the E-Business Control Center. This section describes how to use those features to set up placeholders to personalize portal and portlet content.

Placeholder JSP Tag: <ph:placeholder>

Note: In the following tables, the Required column specifies if the attribute is required (yes) or optional (no). In the R/C column, C means that the attribute is a Compile time expression, and R means that the attribute can be either a Request time expression or a Compile time expression.

Multiple placeholder tags can refer to the same placeholder. Each instance of a placeholder tag invokes its placeholder definition separately. If the placeholder definition specifies multiple queries, each placeholder tag instance can display different ads, even though each instance shares the same definition.

When WebLogic Portal receives a request for a JSP that contains an ad placeholder, the placeholder tag contacts the Ad Service, a session EJB that invokes business logic to determine which ad to display.

Example

This example displays the ad specified in the MainPageBanner placeholder.

<%@ taglib uri="ph.tld" prefix="ph" %>
. . .
<ph:placeholder name="/placeholders/MainPageBanner.pla"/>

Implementing the Placeholder

To implement a placeholder, use this procedure:

Listing 12-6 <ph:placeholder> Tag

<table class="homebackground" width="100%" height="100%"
   border="0" cellspacing="0" cellpadding="0">

   <tr>
      <td align="center">
         <ph:placeholder name="PrimaryCampaign"/>
      </td>
   </tr>

</table>

Creating Placeholder Files

Use the E-Business Control Center to define placeholder files that match the placeholders in your site's JSPs. The following procedure shows you how to create a placeholder file in the E-Business Control Center and how to set up default—not campaign—queries in that placeholder.

Note: Before beginning this procedure, you must define attributes for the documents in your content management system

To create a placeholder file: