Skip Headers

Oracle9iAS Containers for J2EE JSP Tag Libraries and Utilities Reference
Release 2 (9.0.2)

Part Number A95883-01
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

9
Oracle9iAS Personalization Tags

This chapter documents the tag library supplied with OC4J for use with Oracle9iAS Personalization. Use of this library assumes that the Oracle9iAS Personalization product has been properly installed.

This chapter covers the following topics:

For information about Oracle9iAS Personalization itself, see the Oracle9iAS Personalization Administrator's Guide and the Oracle9iAS Personalization Recommendation Engine API Programmer's Guide.


Note:

The Oracle9iAS Personalization tag library is certified to run on the OC4J JSP container.


Overview of Personalization

This section introduces personalization, first covering general concepts and then providing an overview of the Oracle implementation in particular.

General Overview of Personalization

This overview covers general personalization concepts and describes the differences between personalization and customization, concepts that are sometimes confused.

Personalization Concepts

Personalization is a mechanism to tailor recommendations to application users, based on behavioral, purchasing, rating, and demographic data. Recommendations are made in real-time, during a user's application session. User behavior is saved to a profile in a database repository for use in building models to predict future user behavior.

In future user sessions, the models are used to predict behavior and desires of similar users (or, within a single session, the same user), such as products or services to purchase or Web sites to visit. The user will receive recommendations based on these predictions.

The Oracle9iAS Personalization tag library exposes two key functions of personalization:

A typical personalization scheme may take any or all of the following into account:

Personalization Versus Customization

Personalization, as implemented by Oracle and described in this chapter, is a complex and dynamic set of features that result in content being chosen automatically and implicitly. It should not be confused with simpler and more static Web site mechanisms that are often referred to as "personalization", but are really simply "customization".

Many sites offer customization such as giving a user a set of possible topics of interest--such as local weather, stocks of interest, or favorite sports--then displaying output based on the chosen topic. Although it is true that this personalizes the content that is delivered, the process is static and requires explicit user involvement. The focus of the content does not change until the user has an opportunity to change it explicitly through another topic selection.

Personalization chooses content for the user automatically, without direct user request. The process of choosing content is hidden. Moreover, as the system becomes more familiar with user habits by observing behavior, it achieves increased accuracy in predicting future behavior and interests.

Introduction to Oracle9iAS Personalization

Oracle9iAS Personalization uses data mining algorithms in the Oracle database to choose the most relevant content available for a user. Recommendations are calculated by an Oracle9iAS Personalization recommendation engine (defined in "Introduction to Recommendation Engines"), typically using large amounts of data regarding past and current user behavior. This approach is superior to others that rely on "common sense" heuristics and require manual definition of rules in the system.

The application that uses Oracle9iAS Personalization controls data collection, with Oracle9iAS Personalization itself providing targeted data. This process allows the application to avoid collecting large volumes of data of only minimal usefulness.

The Oracle9iAS Personalization tag library brings this functionality to a wide audience of JSP developers for use in HTML, XML, or JavaScript pages. The tag interface is layered on top of the lower-level Java API of the recommendation engine.

Basis for Recommendations

Depending on the configuration and "tuning" of an Oracle9iAS Personalization environment, recommendations may be based on one or more factors such as the following:

Key Components

Oracle9iAS Personalization includes the following key components:

These are all introduced in upcoming sections.

Introduction to Mining Table Repository

The Oracle9iAS Personalization Mining Table Repository (MTR) contains the schema and data to be used for data mining. It is a set of database tables and views containing the following:

These factors are taken together for use in building models to predict future user preferences.

Introduction to Models

A model is essentially a collection of rules, deduced from user data. A simplified example of a rule is "female over 55, income between $150,000 and $200,000, recently purchased scuba tank and mask, likely to buy fins and thermal suit".

In Oracle9iAS Personalization, a model is developed according to recorded facts gathered from the mining table repository. Rules in the model are deduced strictly from available data, not from general or common-sense assumptions of what might be typical for a certain classification of person. How close a particular user's characteristics are to the rules of the best available model determines the likelihood of the resulting recommendation being correct or appropriate.

Introduction to Mining Object Repository

The Oracle9iAS Personalization Mining Object Repository (MOR) is a database schema that maintains mining metadata and mining model results as defined in the Oracle9iAS Personalization data mining schema. The mining object repository serves as the focus for logging in to the data mining system, logging off, and scheduling Oracle9iAS Personalization events. The building of models out of the mining table repository is accomplished according to Oracle9iAS Personalization data mining algorithms.

It is possible to build different models out of the same data by tuning the relevant algorithm to weigh different characteristics of the data more or less heavily. Therefore, there may be multiple models in the mining object repository for a given situation, but only one model is deployed into a recommendation engine at any particular time.

Introduction to Recommendation Engines

An Oracle9iAS Personalization Recommendation Engine (RE) is an Oracle database schema that downloads an Oracle9iAS Personalization model during deployment, and fetches appropriate user profile data from the mining table repository when processing a request for recommendations. Each engine is responsible for activities such as the following:

A recommendation engine processes recommendation requests at runtime and produces personalized recommendations. It also tracks current user behavior at the Web site, collecting user profile data during a session. This latter features allows session-specific personalization for anonymous users and registered users alike.

Populating a recommendation engine involves building a model and then deploying it to a recommendation engine schema, steps that happen behind the scenes. The calculation of particular recommendations is accomplished by PL/SQL stored procedures in the schema.

Introduction to Recommendation Engine Farms

A recommendation engine must be part of a recommendation engine farm. All engines in a farm are loaded with the same model and can be used interchangeably. It is permissible for a farm to consist of only one engine; however, for load-balancing and "failover" purposes, it is advisable to have multiple engines in the farm. To accomplish the desired effect, these engines would reside in different databases on different physical systems.

Overview of Recommendation Engine API Concepts and Features

Oracle9iAS Personalization provides a Java API for use with recommendation engines. The primary use of the API is for requesting recommendations for appropriate items for a given user. The API essentially acts as a client interface to the stored procedures of a recommendation engine database schema. Calculation of recommendations is accomplished through JDBC calls to the stored procedures, using JDBC connection pooling.

The Java API also provides short-term storage, referred to as the data collection cache, for collecting user profile data. These data are periodically flushed to recommendation engine tables, and from there to the mining table repository. Caching the data in this way, instead of immediately writing user data to the recommendation engine as it is gathered, minimizes the number of JDBC calls required. Be aware, however, that each time a recommendation is requested, this does result in a synchronous JDBC call. Results of recommendation requests are not cached, because of their unique and personalized nature.

For JSP programmers, the functionality of the recommendation engine Java API is wrapped in the functionality of the Oracle9iAS Personalization tag library, so this document does not discuss details of the Java API. The tag library provides programming convenience, automating features that you must manage explicitly if you use the Java API directly.

The rest of this section provides an overview of the following concepts and features for the Oracle9iAS Personalization recommendation engine:

Visitors Versus Customers

The recommendation engine has two classifications of users:

Items, Recommendations, Taxonomies, and Categories

In Oracle9iAS Personalization, item is a generic concept referring to a single article or the smallest unit of information. Following are some examples:

Items are used in several ways:

All individual items in an inventory system must belong to a taxonomy. In Oracle9iAS Personalization, a taxonomy refers to a structural organization of items. Typically, the organization of items has a hierarchical structure like a tree or collection of trees, branching from broader groups at the trunk to individual items at the leaves. Item membership in a taxonomy is not exclusive--it is possible to include the same item in multiple taxonomies. A taxonomy is represented by a taxonomy ID, which is a long integer.

Catalog or Web site hosting applications can distinguish among their client data sets by using different taxonomy IDs for different client catalogs or Web sites. Appropriate processing is used to distinguish between classifications of users so that an appropriate taxonomy can be used in each case. For example, a customer at www.oracle.com may indicate that she is a DBA or Web developer. This will determine the taxonomy used in personalizing her future visits. The offering of promotional campaigns, banners, and available books and training, for example, would be drawn either from a Web productivity tools taxonomy or a database administration tools taxonomy.

Individual items within a taxonomy can be grouped into categories. In the structure of a taxonomy, categories are intermediate nodes, consisting of groups of related items. Note, however, that any given item can belong to multiple categories. As an example, the movie The English Patient might belong to categories such as "Screen Adaptations of Novels", "Oscar Winners", "Foreign", and "Drama".

Generally, an item is uniquely identified by a type parameter and an ID parameter, although a rating item also requires a parameter for the rating value itself. It is assumed that an application will be able to rely on some sort of inventory system that determines a type and ID for each item. A type might be something like "shoes" or "sporting events". An ID is an identifying number, and within any single taxonomy no two items can have the same ID.

Be aware that for some personalization filtering settings, a recommendation will represent a category, such as "Drama", rather than an item, such as a specific movie title. In this case, the item type of the recommendation is "Category". Also see "Recommendation Filtering".

The Oracle9iAS Personalization tag library provides a convenient public class to simplify the use of items and recommendations in JSP pages--the oracle.jsp.webutil.personalization.Item class. Use this class to access type, ID, and prediction values. See "Item Class Description" for more information.

Ratings and Rankings

Items returned as recommendations include a prediction value, as follows:

A navigation item can represent anything a Web application might consider a "hit", such as viewing a page, clicking a link, clicking an icon, and so on.

About Ratings

Rating is a quantitative measure of customer preference on a predefined scale. For movies, for example, you might adopt a five-star system where a user gives his or her favorite movie five stars, which can be thought of as a rating of 5.0. In future sessions, Oracle9iAS Personalization would anticipate a high level of interest in this movie for this user and other users with similar interests and backgrounds. A movie that a user likes somewhat, but not as much, might get a rating of three-and-a-half stars, or 3.5.

A definitive rating value is recorded when a user interactively rates an item on the Web site. Rating is a floating point number, to allow as much granularity as desired.

A rating that is returned by the recommendation engine API or, for JSP pages, a recommendation tag, is a predicted value, according to Oracle9iAS Personalization algorithms.

In an Oracle9iAS Personalization rating system, the boundaries are configurable--such as 0.0 to 5.0 in the preceding example. This is specified in the MTR.MTR_BIN_BOUNDARY table of the mining table repository.

About Rankings

Ranking is a whole number indicating the relative rank of an item among a group of items. The items are sorted according to the estimated probabilities of being purchased (for commodities to purchase) or being picked (for URL links to visit) by the user. The probability is calculated using the data mining model and a customer's profile data.

As an example, presume three items--item A, item B, and item C--are returned as recommendations. If A has a 0.9 probability of user interest, B has a 0.55 probability, and C has a 0.83 probability, then A would have a ranking of 1, C would be ranked 2, and B would be ranked 3.

The ranking of an item is relative and dynamic--relative because ranking is meaningful only for a number of items compared to each other and sorted in a certain order; dynamic because ranking of the same item may change for different customers or when ranked against different items.

Stateful Versus Stateless Recommendation Engine Sessions

Web applications can be either stateful or stateless--that is, an application may choose to maintain a user session and user-specific information on the server between requests, or it may not. The recommendation engine API and tag library are designed to handle both situations. Although there are obvious benefits to maintaining user information on the server between requests, there are also high-volume sites that rely on stateless applications for better throughput.

Note, however, that the recommendation engine will always track open user sessions in the recommendation engine database schema, regardless of the session behavior of the Web application.

The recommendation engine tracks a user session by its user ID. Therefore, care must be taken in assigning temporary user IDs to anonymous visitors. If the same ID is used for all anonymous visitors, and their behavior is being tracked, then data collected from all such visitors will be attributed to a single recommendation engine session, and behavior of any one anonymous visitor would influence recommendations to the others. You can avoid this problem by assigning each anonymous visitor a temporary ID that is unique within the recommendation engine.


Note:

One of the advantages of the tag library, compared to using the recommendation engine Java API directly, is that tracking of recommendation engine sessions in a stateless application is managed automatically. You must arrange this mapping yourself if you use the API directly.

Be aware, however, that recommendation engine session tracking through the tag library requires the client, presumably a browser, to support and accept cookies. If this is not always guaranteed, then you must declare your application as stateful.


Requests for Recommendations

After a recommendation engine session is established and populated with data, an application can request recommendations from it. Oracle9iAS Personalization returns the appropriate recommendations to the calling application, and the application decides what to pass to the user and how to pass it.

In JSP pages, an application can request recommendations through one of several "recommendation tags". The recommendation engine returns a set of suggested items according to user data, with respect to tuning and filtering settings. In using the Oracle9iAS Personalization tag library, you can specify tuning and filtering settings through tag attributes or in a configuration file.

A set of recommendations is generated in the recommendation engine database schema through a JDBC call. The time spent in the call may vary, depending on the criteria, how many data records must be processed, and such factors as the size of the rules table, the size of the user profile data, and specifics of the recommendation request. Recommendations will be chosen according to the personalization model, which is deployed into the recommendation engine that the application is connected to. When you use Oracle9iAS Personalization tags, use attributes of the startRESession tag to specify the recommendation engine to use.

For cross-sell recommendations, the application must pass in as input one or more purchasing or navigation items of past user interest. The cross-sell recommendations will be based on the item or items passed in, and perhaps on past or current user data as well.

Recommendation items are returned in an array, with a prediction value for each recommendation--either a rating or a ranking, as described in "Ratings and Rankings"--and an interest dimension value for the array as a whole. For items returned as recommendations, the interest dimension indicates how the items will be of interest to the user--as purchasing items, navigation items, or rating items.

The recommendation engine API allows filtering of recommendations before they are returned, based on the taxonomy.

Overview of Personalization Tag Functionality

This section provides an overview of the features and functionality of the Oracle9iAS Personalization tag library. For descriptions and syntax of the individual tags, see "Personalization Tag and Class Descriptions".

Discussion of the functionality of the tag library is organized as follows:

Recommendation Engine Session Management

Creating and closing a recommendation engine session is handled through the startRESession and endRESession tags. For a JSP page using Oracle9iAS Personalization, you must ensure that at least one startRESession tag is executed, and that it is the first Oracle9iAS Personalization tag encountered for the particular recommendation engine session.

The Oracle9iAS Personalization tag library can support either stateful applications, which maintain state information through HTTP session objects, or stateless applications, which do not. You can use the session attribute of startRESession to specify which mode to use--a "true" setting to allow the tag library to use HTTP session objects, or a "false" setting if you do not want the tags to participate in HTTP sessions.

Setting the session attribute of a startRESession tag to "true" produces effects similar to those of setting session to "true" in a JSP page directive. The difference is that by setting the attribute to "true" in a startRESession tag, you are affecting not only the page containing the tag, but also any other pages that contain personalization tags that execute within the same recommendation engine session.

After the startRESession tag is executed, the personalization tags maintain the relationship of the Web client to the recommendation engine database session so that subsequent personalization tags apply to the same user, as appropriate.

Starting a Recommendation Engine Session

The startRESession tag takes the recommendation engine name and other information from some combination of tag attribute settings and personalization.xml configuration file settings.

A startRESession tag will result in no operation if the recommendation engine session was previously started for the same Web client, with no endRESession tag executed in between. This is for convenience; it allows flexibility regarding the order in which JSP pages are executed. You can place startRESession tags in multiple pages of an application without negative consequences.

See "Personalization startRESession Tag" for detailed information about this tag. Also see "Personalization Tag Library Configuration Files".

Using a Stateful Application

For a stateful application, which uses HTTP sessions, session information is maintained in the JSP implicit session object, a standard HttpSession instance.

When the startRESession tag is encountered, if its session attribute is set to "true" (the default), then the session object is created automatically if it does not already exist.

Using a Stateless Application

For a stateless application, the tag library will maintain internal session tracking through the use of cookies. Therefore, be aware that if you want to use a stateless application, personalization tags will work only if the client browser accepts cookies. If that is not the case, either because the browser chooses to decline cookies or due to lack of capability (such as for wireless protocol browsers), then stateful functionality is required (session="true" for the startRESession tag).

Ending a Recommendation Engine Session

When a stateful application no longer needs a given recommendation engine session, you can use the endRESession tag. As with startRESession tags, repeated executions of endRESession tags result in no further operations, so you can place them in multiple pages of your application without negative consequences.

The endRESession tag has no effect in stateless applications.

Using endRESession tags in stateful applications is sometimes optional, but is necessary in the following circumstances:

In these cases, the endRESession tag must be executed before the next startRESession tag.

Use of endRESession tags is also advisable if an application stops using its Oracle9iAS Personalization tags significantly before the HTTP session is over, so that recommendation engine resources can be released.

See "Personalization endRESession Tag" for detailed information about this tag.


Notes:

If endRESession is not used in a stateful application, the underlying recommendation engine session will be closed automatically when the HTTP session goes out of scope. In a stateless application, the underlying recommendation engine session is allowed to time out.


Use of Items in Personalization Tags

The Oracle9iAS Personalization tag library provides a number of tags for item manipulation--tags to record user behavior information, tags to remove user behavior information that was previously recorded, tags for outputting items as recommendations, and a tag for inputting a specific set of items to be evaluated and rated or ranked.

This section covers the following topics:

Overview of Item Recording and Removal Tags

The following tags are for recording data items into the recommendation engine session cache, or for removing items that were recorded earlier in the session.

To record or remove a purchasing, navigation, or rating item, you must specify the item to record or remove by providing either a type and ID (and a value, for a rating item), or an item array and an index into that array. See "Specification of Input Items" for more information. To record or remove a demographic item, which implicitly applies to the current user, you must specify the demographic type, such as AGE, and a value, such as 44. See "Demographic Items".

There is typically little need to use the removeXXXRecord tags. If you place your recordXXX tags in "receiving pages", there should be no need to use removePurchaseRecord or removeNavigationRecord tags. Using removeRatingRecord and removeDemographicRecord tags would be necessary only in situations where users changed their minds after their initial input had been recorded. See "Mode of Use for Item Recording Tags" for related information.

For detailed tag information, see "Item Recording and Removal Tag Descriptions".

Overview of Recommendation and Evaluation Tags

The following tags return an array of items as recommendations:

For the selectFromHotPicks, getRecommendations, and getCrossSellRecommendations tags--referred to in this document as recommendation tags--the array of items is a set of recommendations returned from an entire taxonomy or from hot picks groups within a taxonomy. The getCrossSellRecommendations tag must also take a set of purchasing items or navigation items as input, on which to base the recommendations (known as cross-selling).

Hot picks might be promotional items or other specially selected groups of items, and the picks to choose from can be specified through a tag attribute. See the Oracle9iAS Personalization Administrator's Guide for more information about hot picks.

For evaluateItems, you must input a particular set of items for which you want evaluations. Some or all (or in some cases, none) of the same items are then returned, either rated or ranked depending on the interest dimension. See "Ratings and Rankings" for background information.

For the getRecommendations and evaluateItems tags, the results are based on the particular user. The user identity is specified through the startRESession tag and is implicitly applied to all subsequent personalization tags. The getCrossSellRecommendations tag depends on the set of input items.

More About the Recommendation Tags

Following is some further information about each of the recommendation tags. For detailed tag descriptions, see "Recommendation and Evaluation Tag Descriptions".

Input Items

For the tags that take items as input--the getCrossSellRecommendations and evaluateItems tags--you can use one or more nested forItem tags to specify desired items, or you can input an entire array of items through a tag attribute. For more information about inputting items, see "Specification of Input Items".

Output Items

For the evaluateItems and getCrossSellRecommendations tags, there is a required tag attribute to specify the name of a tag-extra-info (TEI) variable for the output array of items. For the getRecommendations and selectFromHotPicks tags, this attribute is optional--alternatively or additionally, the items are available sequentially to any getNextItem tags nested within the getRecommendations or selectFromHotPicks tag.

For the recommendation tags, you can use the maxQuantity attribute to specify the maximum number of output items. To determine the actual number of items returned, use the length attribute of the TEI array variable for the returned items. No separate TEI variable is provided for the array size. See "Use of Tag-Extra-Info Scripting Variables for Returned Items" below for information about TEI variables.

Use of Tag-Extra-Info Scripting Variables for Returned Items

For each tag that returns an array of items, there is a tag-extra-info (TEI) class that provides functionality allowing you to use a scripting variable of the following array type:

oracle.jsp.webutil.personalization.Item[]

The array of items is returned in this variable. Each of these tags has a storeResultsIn attribute that you use to specify a variable name. You can loop through the array in your application to display all the items, such as in an HTML table. Use the length attribute of the array to determine how many items were returned.

The selectFromHotPicks, getRecommendations, and getCrossSellRecommendations tags can also return a TEI String variable indicating the interest dimension for the items in the array--NAVIGATION, PURCHASING, or RATING. Use the storeInterestDimensionIn tag attribute to specify a variable name for the interest dimension.


Note:

For general information about tag-extra-info classes and scripting variables, refer to the Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference.


Specification of Input Items

There are two general situations where you must input items:

You can specify items in the following general ways:

  1. Specify the type and ID of each desired item, and also the rating value for a rating item. Or, for a demographic item, specify the type and value.

  2. Supply an item array, and the index into the array for each desired item.

  3. Supply an entire array of items (not relevant for recordXXX and removeXXXRecord tags).

For scenarios #2 and #3, see "Inputting Item Arrays" below for more information.

You can input one or more items into a getCrossSellRecommendations or evaluateItems tag as follows:

Note that you can use more than one of these procedures simultaneously. The getCrossSellRecommendations and evaluateItems tags can take input from multiple sources.

You can specify an item for a recordXXX or removeXXXRecord tag as follows:

Inputting Item Arrays

For situations where you input an array of Item[] objects to a tag, you must specify the array through a JSP expression. This may apply to any of the following tags:

You can supply the array in the following ways:

Demographic Items

Demographic data items, consisting of background information about the user such as gender and age, are used in only the recordDemographic and removeDemographicRecord tags. Because they do not contain purchasing, navigation, or rating information, they cannot be returned by a recommendation tag or input to a getCrossSellRecommendations or evaluateItems tag.

Demographic items, instead of being identified by type and ID as for purchasing and navigation items, are identified by type and value. These are the only two attributes for the recordDemographic and removeDemographicRecord tags. There are several pre-defined types, which exist as columns in the mining table repository in the MTR.MTR_CUSTOMERS table:

There are also 50 customizable columns: ATTRIBUTE1 through ATTRIBUTE50.

To use a customizable type, you must do the following:

  1. Map the ATTRIBUTEx column to an existing enterprise database, thus defining what the attribute is.

  2. Define the corresponding value boundaries in the MTR.MTR_BIN_BOUNDARIES table.

Mode of Use for Item Recording Tags

In Oracle9iAS 9.0.2, you can use one mode of operation for item recording tags: receiving mode. In this mode, when users click on something--such as an item to purchase or a URL to navigate to--the page they jump to, referred to as the "receiving page", contains the recordXXX tag to record the item.

(Future releases will support on-click mode. In this case, the item is recorded as soon as a user clicks on something--the recordXXX tag is in the originating page.)

As a general example, assume that a page uses a getRecommendations tag to generate a list of recommendations that are displayed in a sequence. Each recommended item has a clickable "Details" link to get more information and a clickable "Purchase" link to purchase the item. You can place a recordNavigation tag in the page the user goes to by clicking on "Details"; and you can place a recordPurchase tag in the page the user goes to by clicking on "Purchase" (a purchase confirmation page, for example). In either case, the type and ID of the item are likely already known on the receiving pages, which are devoted specifically to that item.

Similarly, you might place a recordDemographic tag in a JSP page that users jump to when they enter demographic information. For example, there might be a page that allows users to enter marital status, age, and personal income. Once a user enters the information--suppose single, age 44, and earning $50,000 per year--the target of the action behind the HTML form is an advertising page tailored to that profile. This page would have recordDemographic tags for types MARITAL_STATUS, AGE, and PERSONAL_INCOME. You can use multiple recordDemographic tags in a single page.

It is typical to identify items by specifying the appropriate attributes, such as type and ID for purchasing and navigation items. Alternatively, you can use a previously created item list, and an index value into that list, to specify an item. The application can copy an item list array object into a session or request object and also pass the index as a parameter to the receiving page. On the receiving page, the item list can be retrieved from the session or request object and passed to the recordXXX tag along with the index. This approach has at least one advantage: the sending page or pages can collect more than one index before invoking the receiving page, then simultaneously record numerous items from the same item list.

Use of Tuning, Filtering, and Sorting for Recommendation and Evaluation Tags

As summarized earlier, the selectFromHotPicks, getRecommendations, getCrossSellRecommendations, and evaluateItems tags all return an array of items. This section provides information about tuning and filtering settings you can use to more carefully tailor the recommendations that are returned, and a setting to sort the recommendations. Filtering settings do not apply to the evaluateItems tag, however, because the items output are always from the set of items input.

This section is organized as follows:

Tuning Settings

Several tuning settings determine some of the qualifications and logic used by the recommendation engine in returning recommendations. There must be a value for each setting, determinable in one of the ways described here.

You can specify these settings through the tuningXXX attributes of the selectFromHotPicks, getRecommendations, getCrossSellRecommendations, and evaluateItems tags, as summarized in Table 9-1. Alternatively, you can use the tuningName attribute to get the settings from the specified <Tuning> element in either the application-level personalization.xml file (first choice) or the server-wide personalization.xml file. Also see "Personalization Tag Library Configuration Files".

If there are no attribute settings or <Tuning> element, default values will be chosen according to the following steps, in order:

  1. According to a <DefaultTuning> element in the application-level personalization.xml file.

  2. According to a <DefaultTuning> element in the server-wide personalization.xml file.

  3. According to the following hardcoded settings:

    tuningDataSource="ALL"
    tuningInterestDimension="NAVIGATION"
    tuningPersonalizationIndex="MEDIUM"
    tuningProfileDataBalance="BALANCED"
    tuningProfileUsage="INCLUDE"
    
    


    Note:

    To use the hardcoded defaults, do not use any of the tuningXXX attribute settings. If some tuning settings are defined in a tag, then none of the hardcoded values will be used. In this case, if any setting cannot be found in a tag attribute or personalization.xml file, an exception will be thrown.


Table 9-1 Tuning Settings for Requesting Recommendations  
Attribute Description Settings

tuningDataSource

Specify the kind of past user data to be considered in making recommendations. (Do not confuse this kind of data source with the data source concept in the J2EE platform model.)

ALL
NAVIGATION
PURCHASE
RATING
DEMOGRAPHIC

tuningInterestDimension

Specify the kind of recommendation to be returned.

RATING
PURCHASING
NAVIGATION

tuningPersonalizationIndex

Choose how generalized or how personalized the recommendation algorithm should be.

LOW
MEDIUM
HIGH

tuningProfileDataBalance

Choose whether to stress historical data, current session data, or both in making recommendations.

HISTORY
CURRENT
BALANCED

tuningProfileUsage

Choose whether to use data in the user's demographic profile.

INCLUDE
EXCLUDE

For more information about tuning settings, refer to the Oracle9iAS Personalization Administrator's Guide.

Recommendation Filtering

In addition to tuning settings, there are filtering settings that you can specify for a recommendations request. There must be a value for each setting, determinable in one of the ways described here.

You can specify these settings through the filteringXXX attributes of the getRecommendations, getCrossSellRecommendations, and selectFromHotPicks tags. (Filtering is not relevant to the evaluateItems tag.) Alternatively, you can use the filteringName attribute to get the settings from the specified <Filtering> element in either the application-level personalization.xml file (first choice) or the server-wide personalization.xml file. Also see "Personalization Tag Library Configuration Files".

If there are no attribute settings or <Filtering> element, default values will be chosen from the <DefaultFiltering> element in either the application-level personalization.xml file (first choice), or the server-wide personalization.xml file.

These are the filtering parameters:

Table 9-2 Filtering Methods for Requesting Recommendations  
Filtering Method Description

ALL_ITEMS

Recommend items from all leaves in the taxonomy.

INCLUDE_ITEMS

Recommend items that belong to the categories specified in filteringCategories.

EXCLUDE_ITEMS

Recommend items in the taxonomy that do not belong to the categories specified in filteringCategories.

SUBTREE_ITEMS

Recommend items that belong to the subtrees of the categories specified in filteringCategories.

ALL_CATEGORIES

Recommend all categories in the taxonomy.

INCLUDE_CATEGORIES

Recommend categories specified in filteringCategories.

EXCLUDE_CATEGORIES

Recommend categories in the taxonomy that are not specified in filteringCategories.

SUBTREE_CATEGORIES

Recommend categories from the subtrees of the categories specified in filteringCategories.

CATEGORY_LEVEL

Recommend categories of the same level as the categories specified in filteringCategories.

For any of the XXX_CATEGORIES settings, recommendations are returned in the form of categories, such as "drama", rather than specific items, such as a particular movie title. The item type is "Category" in this case, and categories must first be defined in the mining table repository.

For more information about filtering settings, refer to the Oracle9iAS Personalization Recommendation Engine API Programmer's Guide.

Sorting Order

You can sort returned items according to the prediction field of each item, which is either a rating or a ranking. See "Ratings and Rankings" for information about how to use this field.

Use the sortOrder attribute of the selectFromHotPicks, getRecommendations, getCrossSellRecommendations, or evaluateItems tag to specify a sorting order of ASCEND, DESCEND, or NONE (default). Ascending order lists the best match first, and descending order does the opposite. An ascending order of five ranked items would be 1, 2, 3, 4, then 5, because 1 is the highest rank. An ascending order of five rated items would be something like 4.5, 3.9, 2.5, 2.2, then 1.8, because a higher number means a higher rating.

Personalization Tag and Class Descriptions

This section provides detailed descriptions of syntax and usage for the Oracle9iAS Personalization tags and the Item public class, concluding with a discussion of tag limitations. It is organized as follows:

To use the Oracle9iAS Personalization tag library, verify that the file ojsputil.jar is installed and in your classpath. This file is provided with OC4J. You will also need the classes for the recommendation engine API, which are in the oreapi-rt.jar file. If you install the Oracle9i Application Server with the "Business Intelligence" option, this file will be installed in the [SRCHOME]/dmt/jlib directory. Copy it to a location that is accessible to your application.

In an Oracle9iAS installation, the personalization tag library description file, personalization.tld, is located in the [Oracle_Home]/j2ee/tlds directory. To use this TLD file, you must deploy it with your application, and you will need a taglib directive such as the following in your JSP pages:

<%@ taglib uri="/WEB-INF/personalization.tld" prefix="op" %>

You must also copy the personalization.tld file into the appropriate location (presumably /WEB-INF, as above) before producing an EAR file for your application and subsequently deploying it. See the Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference for general information about tag library usage, and the Oracle9iAS Containers for J2EE User's Guide for general information about OC4J deployment.


Notes:

  • The prefix "op:" is used in the tag syntax here. This is by convention but is not required. You can specify any desired prefix in your taglib directive.

  • See "Tag Syntax Symbology and Notes" for general information about tag syntax conventions in this manual.

  • Where there is a fixed number of supported attribute settings, such as "true" or "false", entries are not case-sensitive.


Use of some of the tag attributes described here requires some general knowledge of the Oracle9iAS Personalization and recommendation engine implementations. Where information here is incomplete, see the Oracle9iAS Personalization Administrator's Guide or the Oracle9iAS Personalization Recommendation Engine API Programmer's Guide.

Session Management Tag Descriptions

This section documents the following tags for starting, ending, and managing recommendation engine sessions:

Personalization startRESession Tag

This section provides syntax and attribute descriptions for the startRESession tag, which you use to start a recommendation engine session. Also see "Recommendation Engine Session Management" for related information.

The startRESession tag must be executed before any other Oracle9iAS Personalization tag that executes within the same recommendation engine session.

The startRESession tag has no body.


Note:

Also see "Personalization Tag Constraints".


Syntax

<op:startRESession REName = "recommendation_engine_connection_name"
                 [ REURL = "rec_engine_database_connection_URL" ]
                 [ RESchema = "rec_engine_schema_name" ]
                 [ REPassword = "rec_engine_schema_password" ]
                 [ RECacheSize = "kilobytes_of_cache" ]
                 [ REFlushInterval = "milliseconds_to_flush" ]
                 [ session = "true" | "false" ]
                 [ userType = "visitor" | "customer" ]
                 [ UserID = "user_ID_for_site_login" ]
                 [ storeUserIDIn = "variable_name" ]
                 [ disableRecording = "true" | "false" ] />

Attribute Usage Notes

Attributes

Personalization endRESession Tag

Use this tag to explicitly end a recommendation engine session in a stateful application. This is usually optional, but is required under some circumstances--see "Ending a Recommendation Engine Session". It is also advisable to use this tag in a stateful application if application logic determines that the recommendation engine session is no longer required--this will free unneeded resources.

For situations where you do not use endRESession, note the following behavior:

The endRESession tag has no attributes and no body.

Syntax

<op:endRESession />

Personalization setVisitorToCustomer Tag

Use this tag for situations where an anonymous visitor creates a registered customer account. Upon execution of this tag, the existing recommendation engine session is converted from a visitor session to a customer session. Previous data gathered in the session will be retained. This tag does not actually create the new customer, nor does it execute a new login. It only converts the ongoing recommendation engine session.

The customerID value is a request-time attribute and must be provided by the application.

The setVisitorToCustomer tag has no body.

Syntax

<op:setVisitorToCustomer customerID = "registered_customer_name" />

Attributes

Recommendation and Evaluation Tag Descriptions

This section provides detailed descriptions of the recommendation tags, the evaluation tag, and related subtags.

The following tags are covered:

Also see "Overview of Recommendation and Evaluation Tags".

Personalization getRecommendations Tag

Use this tag to request a set of recommendations for purchasing, navigation, or ratings. Items from a particular taxonomy are considered, with tuning and filtering as specified. Recommendations are returned in an array of the following type:

oracle.jsp.webutil.personalization.Item[]

Although other tags, such as getCrossSellRecommendations and evaluateItems, require items to be input for use as a basis for recommendations, the getRecommendations tag does not. Recommendations are based on user identity and profile (user session and historical data), not on specific items.

The resulting recommendations can optionally be stored in a TEI variable of type Item[], with the variable name specified in the storeResultsIn attribute of the tag. The recommendations are also available implicitly within the getRecommendations tag. You can optionally use a tag body with nested getNextItem tags for any desired processing of the items. See "Personalization getNextItem Tag".


Note:

Also see "Personalization Tag Constraints".


Syntax

<op:getRecommendations 
  [ from = "top" | "bottom" ]
  [ fromHotPicksGroups = "string_of_Hot_Picks_group_numbers" ]
  [ storeResultsIn = "TEI_variable_name" ]
  [ storeInterestDimensionIn = "TEI_variable_name" ]
  [ maxQuantity = "integer_value" ]
  [ tuningName = "name_from_config_file_Tuning_element" ]
  [ tuningDataSource = "ALL"|"NAVIGATION"|"PURCHASE"|"RATING"|"DEMOGRAPHIC" ]
  [ tuningInterestDimension = "NAVIGATION"|"PURCHASING"|"RATING" ]
  [ tuningPersonalizationIndex = "LOW"|"MEDIUM"|"HIGH" ]
  [ tuningProfileDataBalance = "HISTORY"|"CURRENT"|"BALANCED" ]
  [ tuningProfileUsage = "INCLUDE"|"EXCLUDE" ] 
  [ filteringName = "name_from_config_file_Filtering_element" ]
  [ filteringTaxonomyID = "integer_value" ]
  [ filteringMethod = "ALL_ITEMS"|"EXCLUDE_ITEMS"|"INCLUDE_ITEMS"|
            "SUBTREE_ITEMS"|"ALL_CATEGORIES"|"INCLUDE_CATEGORIES"|
            "EXCLUDE_CATEGORIES"|"SUBTREE_CATEGORIES"|CATEGORY_LEVEL" ]
  [ filteringCategories = "string_of_integers" ]
  [ sortOrder = "ASCEND"|"DESCEND"|"NONE" ] >

...

</op:getRecommendations>

Attribute Usage Notes

Be aware of the following:

Attributes

Example

Following is an example of basic usage of the getRecommendations tag. The storeResultsIn attribute defines an Item[] array for receiving and displaying results.

<op:getRecommendations storeResultsIn="myRecs">
<% for(int i = 0; i< myRecs.length; i++) {
   Render(myRecs(i).getType(),myRecs(i).getID());
} %>
</op:getRecommendations>

Also see "Personalization getNextItem Tag" for an example of a getRecommendations tag that uses a nested getNextItem tag.

Personalization getCrossSellRecommendations Tag

Like the getRecommendations tag, the getCrossSellRecommendations tag returns a set of recommendations, in an array of type Item[], for purchasing, navigation, or ratings. Items from a particular taxonomy are considered, with tuning and filtering as specified.

To use getCrossSellRecommendations, however, you must input a set of purchasing or navigation items of past user interest that are used as a basis for the resulting recommendations. The items must all be from the same taxonomy.

You can input items through a specified item array or through a tag body with nested forItem tags. See "Specification of Input Items" for more information. Also see "Personalization forItem Tag".

The recommendations from the getCrossSellRecommendations tag are stored in a TEI variable of type Item[], with the variable name specified in the storeResultsIn attribute of the tag.


Note:

Also see "Personalization Tag Constraints".


Syntax

<op:getCrossSellRecommendations 
    storeResultsIn = "TEI_variable_name" 
  [ storeInterestDimensionIn = "TEI_variable_name" ]
  [ fromHotPicksGroups = "string_of_Hot_Picks_group_numbers" ]
  [ inputItemList = "item_array_expression" ]
  [ maxQuantity = "integer_value" ]
  [ tuningName = "name_from_config_file_Tuning_element" ]
  [ tuningDataSource = "ALL"|"NAVIGATION"|"PURCHASE"|"RATING"|"DEMOGRAPHIC" ]
  [ tuningInterestDimension = "NAVIGATION"|"PURCHASING"|"RATING" ]
  [ tuningPersonalizationIndex = "LOW"|"MEDIUM"|"HIGH" ]
  [ tuningProfileDataBalance = "HISTORY"|"CURRENT"|"BALANCED" ]
  [ tuningProfileUsage = "INCLUDE"|"EXCLUDE" ] 
  [ filteringName = "name_from_config_file_Filtering_element" ]
  [ filteringTaxonomyID = "integer_value" ]
  [ filteringMethod = "ALL_ITEMS"|"EXCLUDE_ITEMS"|"INCLUDE_ITEMS"|
                      "SUBTREE_ITEMS" ]
  [ filteringCategories = "string_of_integers" ]
  [ sortOrder = "ASCEND"|"DESCEND"|"NONE" ] >
...

</op:getCrossSellRecommendations>

Attribute Usage Notes

Be aware of the following:

Attributes

All other attributes of the getCrossSellRecommendations tag are used as for the getRecommendations tag, as described in "Personalization getRecommendations Tag", except for any limitations noted in "Attribute Usage Notes" immediately above.

For additional information about tuning, filtering, and sorting, see "Tuning Settings", "Recommendation Filtering", and "Sorting Order".

Example

The following example uses a getCrossSellRecommendations tag to suggest follow-up DVD titles to a user who rented or purchased certain titles in the past.

<% long[] ids = ApplicationPackage.getUserHistory("Smith01");
   Item[] DVDs = new Item[ids.length];
   for(int i=0; i<ids.length; i++) {
      DVDs[i] = new Item("DVD", ids[i] );
   }
   pageContext.setAttribute("pastInterest", DVDs);
%>
<op: getCrossSellRecommendations inputItemList="pastInterest"
                                 storeResultsIn="moreDVDs"
                                 maxQuantity = "4"
                                 sortOrder="ASCEND" />
<!-- display 4 best cross-sell items -->
<h1> You will also enjoy these titles! </h1>

ApplicationSupport.displayItem(moreDVDs[1].getType(), moreDVDs[1].getID() );
ApplicationSupport.displayItem(moreDVDs[2].getType(), moreDVDs[2].getID() );
ApplicationSupport.displayItem(moreDVDs[3].getType(), moreDVDs[3].getID() );
ApplicationSupport.displayItem(moreDVDs[4].getType(), moreDVDs[4].getID() );

Also see "Personalization forItem Tag" for an example of a getCrossSellRecommendations tag that uses a nested forItem tag.

Personalization selectFromHotPicks Tag

Use this tag to request recommendations from a set of hot picks groups only, instead of from the taxonomy as a whole, and without considering the user profile. Tuning and filtering are still applied, to items in the specified groups.

Other than the fact that selectFromHotPicks does not consider user identity and profile, it works in essentially the same way as the getRecommendations tag with a specified fromHotPicksGroups setting. See "Personalization getRecommendations Tag" for detailed information about that tag.

You can optionally store the resulting recommendations in a TEI variable of type Item[], with the variable name specified in the storeResultsIn attribute of the tag. The recommendations are also available implicitly within the selectFromHotPicks tag. You can optionally use a tag body with nested getNextItem tags for any desired processing of the items. See "Personalization getNextItem Tag".


Note:

Also see "Personalization Tag Constraints".


Syntax

<op:selectFromHotPicks 
    hotPicksGroups = "string_of_Hot_Picks_group_numbers"
  [ storeResultsIn = "TEI_variable_name" ]
  [ storeInterestDimensionIn = "TEI_variable_name" ]
  [ maxQuantity = "integer_value" ]
  [ tuningName = "name_from_config_file_Tuning_element" ]
  [ tuningDataSource = "ALL"|"NAVIGATION"|"PURCHASE"|"RATING"|"DEMOGRAPHIC" ]
  [ tuningInterestDimension = "NAVIGATION"|"PURCHASING"|"RATING" ]
  [ tuningPersonalizationIndex = "LOW"|"MEDIUM"|"HIGH" ]
  [ tuningProfileDataBalance = "HISTORY"|"CURRENT"|"BALANCED" ]
  [ tuningProfileUsage = "INCLUDE"|"EXCLUDE" ] 
  [ filteringName = "name_from_config_file_Filtering_element" ]
  [ filteringTaxonomyID = "integer_value" ]
  [ filteringMethod = "ALL_ITEMS"|"EXCLUDE_ITEMS"|"INCLUDE_ITEMS"|
            "SUBTREE_ITEMS"|"ALL_CATEGORIES"|"INCLUDE_CATEGORIES"|
            "EXCLUDE_CATEGORIES"|"SUBTREE_CATEGORIES"|CATEGORY_LEVEL" ]
  [ filteringCategories = "string_of_integers" ]
  [ sortOrder = "ASCEND"|"DESCEND"|"NONE" ] >

...

</op:selectFromHotPicks>

Attribute Usage Notes

Be aware of the following:

Attributes

Use all other attributes as for the getRecommendations tag, as described in "Personalization getRecommendations Tag", except for any limitations noted in the preceding "Attribute Usage Notes".

For additional information about tuning, filtering, and sorting, see "Tuning Settings", "Recommendation Filtering", and "Sorting Order".

See "Personalization getNextItem Tag" for an example of a selectFromHotPicks tag that uses a nested getNextItem tag.

Personalization evaluateItems Tag

Use the evaluateItems tag to evaluate the set of items that are input to the tag. The items must all be from the same taxonomy. For an interest dimension of PURCHASING or NAVIGATION, the items are ranked. For an interest dimension of RATING, the items are rated. A subset of the evaluated items--anywhere from none to all of the items, depending on effects of the tuningDataSource setting--are returned in a TEI array variable of type Item[]. You must specify the name of the variable through the storeResultsIn attribute. For each item in the array, the prediction attribute contains the ranking or rating value.

See "Ratings and Rankings" for background information about item ratings and rankings.

You can input items through a specified item array or through a tag body with nested forItem tags. See "Specification of Input Items" for more information. Also see "Personalization forItem Tag".


Note:

Also see "Personalization Tag Constraints".


Syntax

<op:evaluateItems 
    storeResultsIn = "TEI_variable_name" 
    taxonomyID = "integer_value"
  [ inputItemList = "item_array_expression" ]
  [ tuningName = "name_from_config_file_Tuning_element" ]
  [ tuningDataSource = "ALL"|"NAVIGATION"|"PURCHASE"|"RATING"|"DEMOGRAPHIC" ]
  [ tuningInterestDimension = "NAVIGATION"|"PURCHASING"|"RATING" ]
  [ tuningPersonalizationIndex = "LOW"|"MEDIUM"|"HIGH" ]
  [ tuningProfileDataBalance = "HISTORY"|"CURRENT"|"BALANCED" ]
  [ tuningProfileUsage = "INCLUDE"|"EXCLUDE" ] 
  [ sortOrder = "ASCEND"|"DESCEND"|"NONE" ] >

...

</op:evaluateItems>

Attribute Usage Notes

Be aware of the following:

Attributes

Use all other evaluateItems attributes as for the getRecommendations tag, as described in "Personalization getRecommendations Tag", except for any limitations noted in the preceding "Attribute Usage Notes".

For additional information about tuning and sorting, see "Tuning Settings" and "Sorting Order".

Example

This example takes sale items as input, uses the evaluateItems tag to put them in order of highest interest to the user, then displays the most interesting one.

<% Item[] saleItems = ApplicationSupport.getSaleItems(); %>
<!-- Choose the sale items of greatest interest to this user -->
<op:evaluateItems storeResultsIn="bestItems"  taxonomyID="1"
                             inputItemList="<%=saleItems%>" />

<% ApplicationSupport.displayItem(bestItems(1)); %>

Personalization forItem Tag

Use this tag to specify individual items for input to a getCrossSellRecommendations tag or an evaluateItems tag.

See "Specification of Input Items" for conceptual information about how to use the forItem tag.

The forItem tag has no body.


Note:

Also see "Personalization Tag Constraints".


Syntax

<op:forItem 
          [ itemList = "item_array_expression" ]
          [ index = "index_into_item_array" ]
          [ type = "type_of_item" ]
          [ ID = "item_ID_number" ] />

Attribute Usage Notes

There are two modes of use for this tag:

or:

Attributes

Example

The following example uses several specified shoe purchasing items as input for a cross-sell recommendation, then displays the resulting recommendations.

<op: getCrossSellRecommendations storeResultsIn="shoeItems" >
   <op:forItem type="shoes" ID="20" />
   <op:forItem type="shoes" ID="26" />
   <op:forItem type="shoes" ID="45" />
   <op:forItem type="shoes" ID="93" />
   <op:forItem type="shoes" ID="101" />
</op:getCrossSellRecommendations>
<p> Based on past shoe purchases, here are the shoes we recommend! </p>
<%= ApplicationSupport.displayItemArray(shoeItems) %>

Personalization getNextItem Tag

You can optionally use nested getNextItem tags within a getRecommendations or selectFromHotPicks tag body to access the recommendations that the outer tag returns. (The alternative is to access the items through the storeResultsIn attribute of the getRecommendations or selectFromHotPicks tag.)

The first time a getNextItem tag is executed, it accesses the first item, and subsequent getNextItem executions proceed through the item array one by one, with each getNextItem execution taking the next item. When the end of the item array is reached, the tag puts null values into each of its tag attributes.

Use tag attributes to store either the type and ID of the next item, or the Item instance itself.

The getNextItem tag has no body.

Be aware of the following:

Syntax

<op:getNextItem 
          [ storeTypeIn = "TEI_variable_for_item_type" ]
          [ storeIDIn = "TEI_variable_for_item_ID" ]
          [ storeItemIn = "TEI_variable_for_Item_instance" ] />

Attribute Usage Notes

There are two modes of use for this tag:

or:

All TEI variables are of scope AT_END, meaning they are available from the end of the tag until the end of the JSP page. All TEI variables must be declared in scriptlet code earlier in the page and must be visible in the scope of the getNextItem tag. Unlike TEI variables in other personalization tags, these variables will not be declared by the JSP container.

Attributes

Examples

The following example shows a getNextItem tag being used in a loop inside a getRecommendations tag. The loop terminates when getNextItem returns null.

<op:getRecommendations from="top"
                       tuningName="BalancedTuning"
                       filteringName="GeneralFiltering" >
<p> Top Picks selected especially for you: </p>
        <% String type=null;
           String ID=null;
           while(true) { %>
             <op:getNextItem storeTypeIn="type" storeIDIn="ID" />
             <% if(type==null) break;%>
             <li> type: <%=type%> ID: <%=ID%> </li>
        <% } %>
</op:getRecommendations>

And this next example shows a getNextItem tag in a loop inside a selectFromHotPicks tag:

<op:selectFromHotPicks hotPicksGroups="1+5"
                       tuningName="HotPicksTuning"
                       filteringName="GeneralFiltering" >
<p> We know you enjoy Horror and Musical movies. Look what we have on
sale this week! </p>
        <% Item item=null;
           while(true) { %>
             <op:getNextItem storeItemIn="item" />
             <% if(item==null) break;%>
             <li> <%= ApplicationSupport.displayItem(item) %> </li>
        <% } %>

</op:selectFromHotPicks>

Item Recording and Removal Tag Descriptions

This section provides detailed descriptions of the recordXXX and removeXXXRecord tags. Use the appropriate recordXXX tag to record an item into the recommendation engine session cache. Use the corresponding removeXXXRecord tag if you want to remove an item that was recorded earlier in the session. Items in the cache are periodically flushed to the recommendation engine session; removing an item after that point requires a database round-trip.

Also see "Overview of Item Recording and Removal Tags".

The following tags are covered here:

Personalization recordNavigation Tag

Use this tag to record a navigation item into the recommendation engine session. This is to record that a user demonstrated an interest in the item by navigating to it. For example, he or she may see an icon that represents something of interest, then click on a "Tell Me More" button next to the icon. See "Personalization removeNavigationRecord Tag" for information about the tag to remove a navigation item.

You can disable actions of the recordNavigation tag by setting the disableRecording attribute of the startRESession tag to "true". See "Personalization startRESession Tag" for more information.

The recordNavigation tag has no body.


Note:

Also see "Personalization Tag Constraints".


Syntax

<op:recordNavigation
          [ type = "type_of_item" ]
          [ ID = "item_ID_number" ] 
          [ itemList = "item_array_expression" ] 
          [ index = "index_into_item_array" ] />

Attribute Usage Notes

There are two modes of use for this tag:

or:

See "Specification of Input Items" for related information.

Attributes

Personalization recordPurchase Tag

Use this tag to record a purchasing item into the recommendation engine session. This is to record a purchase the user has made. See "Personalization removePurchaseRecord Tag" for information about the tag to remove a purchasing item.

You can disable actions of the recordPurchase tag by setting the disableRecording attribute of the startRESession tag to "true". See "Personalization startRESession Tag" for more information.

The recordPurchase tag has no body.


Note:

Also see "Personalization Tag Constraints".


Syntax

<op:recordPurchase
          [ type = "type_of_item" ]
          [ ID = "item_ID_number" ] 
          [ itemList = "item_array_expression" ] 
          [ index = "index_into_item_array" ] />

Attribute Usage Notes

There are two modes of use for this tag:

or:

See "Specification of Input Items" for related information.

Attributes

Attributes are the same as for the recordNavigation tag--see "Personalization recordNavigation Tag".

Example

Consider the following excerpts from two JSP pages.

Page 1:

<%@ page session="true" %>
<op:getRecommendations storeResultsIn "myRecs" />
...display recommendations...
<% session.setAttribute("recommendationList", myRecs); %>

Page 2:

<%@ page session="true" %>
<op:recordPurchase itemList="<%=session.getAttribute(\"recommendationList\") %>"
                 index="<%=request.getParameter(\"index\" %>" />

Page 1 obtains a list of recommendations and displays them, along with a "Buy" link for each item. The item array is stored in the session object for subsequent pages to use.

Page 2 is executed when the user clicks a link to buy a particular recommendation. The item list is retrieved from a session attribute; the index of the item selected is retrieved from a request parameter. Page 2 may be a Shopping Cart page, for example.

Personalization recordRating Tag

Use this tag to record a rating item into the recommendation engine session. This would be based on a user rating of the item. See "Personalization removeRatingRecord Tag" for information about the tag to remove a rating item.

This tag differs from recordNavigation and recordPurchase in that a value--the rating value--must also be specified.

The recordRating tag has no body.


Note:

Also see "Personalization Tag Constraints".


Syntax

<op:recordRating value = "rating_value"
          [ type = "type_of_item" ]
          [ ID = "item_ID_number" ] 
          [ itemList = "item_array_expression" ] 
          [ index = "index_into_item_array" ] />

Attribute Usage Notes

There are two modes of use for this tag:

or:

The value attribute is required in either case.

See "Specification of Input Items" for related information.

Attributes

The other attributes are the same as for the recordNavigation tag--see "Personalization recordNavigation Tag".

Personalization recordDemographic Tag

Use this tag to record a demographic item into the recommendation engine session. A demographic item consists of a piece of personal information about a particular user. See "Personalization removeDemographicRecord Tag" for information about the tag to remove a demographic item.

This tag differs from the other recordXXX tags in that it has only two attributes--type and value. The type attribute indicates what kind of information the item contains, such as "AGE". The value attribute contains the corresponding value, such as "44".

The recordDemographic tag has no body.


Note:

Also see "Personalization Tag Constraints".


Syntax

<op:recordDemographic 
        type = "GENDER"|"AGE"|"MARITAL_STATUS"|"PERSONAL_INCOME"|
               "HOUSEHOLD_INCOME"|"IS_HEAD_OF_HOUSEHOLD"|"HOUSEHOLD_SIZE"|
               "RENT_OWN_INDICATOR"|"ATTRIBUTE1"|...|"ATTRIBUTE50"
        value = "item_value" />

Attributes

Personalization removeNavigationRecord Tag

Use this tag to remove a navigation item that had been recorded into the recommendation engine session earlier in the session. See "Personalization recordNavigation Tag" for information about the tag to record a navigation item.

To remove an item, you must use the removeNavigationRecord tag during the same recommendation engine session in which the item was recorded. The session cache is periodically flushed to the recommendation engine database schema during the course of a session. If you remove an item after it has been flushed, execution of the removal tag will require a database round-trip.

The removeNavigationRecord tag has no body.


Note:

Also see "Personalization Tag Constraints".


Syntax

<op:removeNavigationRecord
          [ type = "type_of_item" ]
          [ ID = "item_ID_number" ] 
          [ itemList = "item_array_expression" ] 
          [ index = "index_into_item_array" ] />

Attribute Usage Notes

There are two modes of use for this tag:

or:

See "Specification of Input Items" for related information.

Attributes

Attributes are the same as for the recordNavigation tag--see "Personalization recordNavigation Tag".

Personalization removePurchaseRecord Tag

Use this tag to remove a purchasing item that had been recorded into the recommendation engine session earlier in the session. See "Personalization recordPurchase Tag" for information about the tag to record a purchasing item.

To remove an item, you must use the removePurchaseRecord tag during the same recommendation engine session in which the item was recorded. The session cache is periodically flushed to the recommendation engine database schema during the course of a session. If you remove an item after it has been flushed, execution of the removal tag will require a database round-trip.

The removePurchaseRecord tag has no body.


Note:

Also see "Personalization Tag Constraints".


Syntax

<op:removePurchaseRecord
          [ type = "type_of_item" ]
          [ ID = "item_ID_number" ] 
          [ itemList = "item_array_expression" ] 
          [ index = "index_into_item_array" ] />

Attribute Usage Notes

There are two modes of use for this tag:

or:

See "Specification of Input Items" for related information.

Attributes

Attributes are the same as for the recordNavigation tag--see "Personalization recordNavigation Tag".

Personalization removeRatingRecord Tag

Use this tag to remove a rating item that had been recorded into the recommendation engine session earlier in the session. See "Personalization recordRating Tag" for information about the tag to record a rating item.

This tag differs from removeNavigationRecord and removePurchaseRecord in that a value--the rating value--must also be specified.

To remove an item, you must use the removeRatingRecord tag during the same recommendation engine session in which the item was recorded. The session cache is periodically flushed to the recommendation engine database schema during the course of a session. If you remove an item after it has been flushed, execution of the removal tag will require a database round-trip.

The removeRatingRecord tag has no body.


Note:

Also see "Personalization Tag Constraints".


Syntax

<op:removeRatingRecord value = "rating_value"
          [ type = "type_of_item" ]
          [ ID = "item_ID_number" ] 
          [ itemList = "item_array_expression" ] 
          [ index = "index_into_item_array" ] />

Attribute Usage Notes

There are two modes of use for this tag:

or:

The value attribute is required in either case.

See "Specification of Input Items" for related information.

Attributes

The other attributes are the same as for the recordNavigation tag--see "Personalization recordNavigation Tag".

Personalization removeDemographicRecord Tag

Use this tag to remove a demographic item that had been recorded into the recommendation engine session earlier in the session. See "Personalization recordDemographic Tag" for information about the tag to record a demographic item.

This tag differs from the other removeXXXRecord tags in that it has only two attributes--type and value. The type attribute indicates what kind of information the item contains, such as "AGE". The value attribute contains the corresponding value, such as "44".

To remove an item, you must use the removeDemographicRecord tag during the same recommendation engine session in which the item was recorded. The session cache is periodically flushed to the recommendation engine database schema during the course of a session. If you remove an item after it has been flushed, execution of the removal tag will require a database round-trip.

The removeDemographicRecord tag has no body.


Note:

Also see "Personalization Tag Constraints".


Syntax

<op:removeDemographicRecord 
        type = "GENDER"|"AGE"|"MARITAL_STATUS"|"PERSONAL_INCOME"|
               "HOUSEHOLD_INCOME"|"IS_HEAD_OF_HOUSEHOLD"|"HOUSEHOLD_SIZE"|
               "RENT_OWN_INDICATOR"|"ATTRIBUTE1"|...|"ATTRIBUTE50"
        value = "item_value" />

Attributes

Attributes are the same as for the recordDemographic tag--see "Personalization recordDemographic Tag".

Item Class Description

The Oracle9iAS Personalization tag library offers the following convenient wrapper class to facilitate the use of items, categories, and recommendations in JSP pages:

oracle.jsp.webutil.personalization.Item

Tag handlers create Item instances as necessary. There are two particular scenarios where you will need to use, and sometimes create, Item instances directly:

The Item class provides the following getter methods for the first scenario:

The class provides the following setter methods for the second scenario:

There are also methods to define the item as a category and to determine if it has already been defined as a category:

The Item class provides the following public constructors:

The type attribute must be a string; the ID attribute can be a string or a long value.

The Item class also defines the following String constant values for interest dimensions. Use these values for comparisons to values returned in the storeInterestDimensionIn attribute of the recommendation tags:

Personalization Tag Constraints

Be aware of the following constraints regarding attribute settings for the Oracle9iAS Personalization tags:

Personalization Tag Library Configuration Files

The Oracle9iAS Personalization tag library supports the use of configuration files, named personalization.xml, to specify global and default tag attribute settings. This section documents personalization.xml files and their supported elements, and is organized as follows:

The personalization.xml Files

The Oracle9iAS Personalization tag library supports configuration files named personalization.xml. These files are useful in specifying default settings for optional tag attributes and for specifying default and named tuning and filtering settings. Using personalization.xml for tuning and filtering settings is particularly useful, because the settings can be quite involved, and it would be inconvenient to have to set them in multiple tags or multiple pages.

There may be two personalization.xml files relevant to a given application:

Element Descriptions for personalization.xml

This section documents the XML DTD syntax for personalization.xml elements supported by the Oracle9iAS Personalization tag library.

These elements are inside a top-level <personalization-config> element.

The personalization tags will validate any personalization.xml file against the DTD.


Note:

Also see "Personalization Tag Constraints". Some of these limitations apply to personalization.xml elements as well as to tag attribute settings.


RecommendationSettings Element

Use this element to set a default value for maxQuantity, the maximum number of recommendations that can be returned, for the getRecommendations, getCrossSellRecommendations, and selectFromHotPicks tags.

The maxQuantity setting must be a string representing a positive integer.

Definition

<!ELEMENT RecommendationSettings EMPTY>
    <!ATTLIST RecommendationSetting  maxQuantity  CDATA #REQUIRED>

RE Element

Use this element to specify the name of a recommendation engine connection and to make the connection. See "Personalization startRESession Tag" for information about the attributes.

Definition

<!ELEMENT RE EMPTY>
   <!ATTLIST RE Name CDATA #REQUIRED>
   <!ATTLIST RE URL CDATA #REQUIRED>
   <!ATTLIST RE Schema CDATA #REQUIRED>
   <!ATTLIST RE Password CDATA #REQUIRED>
   <!ATTLIST RE CacheSize CDATA #REQUIRED>
   <!ATTLIST RE FlushInterval CDATA #REQUIRED>

You can refer to the Name attribute in startRESession tag REName attributes.

Tuning Element

Use this element to define named tuning settings. See "Tuning Settings" for information about the attributes.

Definition

<!ELEMENT Tuning EMPTY>
   <!ATTLIST Tuning Name CDATA #REQUIRED>
   <!ATTLIST Tuning  DataSource 
             (NAVIGATION|PURCHASING|RATING|DEMOGRAPHIC|ALL) "ALL" >
   <!ATTLIST Tuning InterestDimension (NAVIGATION|PURCHASING|RATING)
             #REQUIRED >
   <!ATTLIST Tuning PersonalizationIndex (LOW|MEDIUM|HIGH) #REQUIRED >
   <!ATTLIST Tuning  ProfileDataBalance (HISTORY|CURRENT|BALANCED)
             #REQUIRED >
   <!ATTLIST Tuning ProfileUsage (INCLUDE|EXCLUDE) "INCLUDE" >

The Name attribute is required and must give a unique name to this set of tuning settings so that the name can be referred to in recommendation tag tuningName attributes.

Other attributes are also required to fully define tuning settings for a recommendation request, except for ProfileUsage, which has a default value of "INCLUDE". See Oracle9iAS Personalization Recommendation Engine API Programmer's Guide for more information.

DefaultTuning Element

Use this element for tuning settings in the absence of individual tuning tag attributes or a tuningName tag attribute (and corresponding <Tuning> element in personalization.xml).

Attribute meanings are the same as for the <Tuning> element.

Definition

<!ELEMENT DefaultTuning EMPTY>
   <!ATTLIST DefaultTuning  DataSource 
             (NAVIGATION|PURCHASING|RATING|DEMOGRAPHIC|ALL) "ALL" >
   <!ATTLIST DefaultTuning InterestDimension (NAVIGATION|PURCHASING|RATING)
             #REQUIRED >
   <!ATTLIST DefaultTuning PersonalizationIndex (LOW|MEDIUM|HIGH)
             #REQUIRED >
   <!ATTLIST DefaultTuning ProfileDataBalance (HISTORY|CURRENT|BALANCED)
             #REQUIRED >
   <ATTLIST! DefaultTuning ProfileUsage (INCLUDE|EXCLUDE) "INCLUDE" >

Filtering Element and Category Elements

Use these elements to define named filtering settings. See "Recommendation Filtering" for information about the attributes.

Use the filtering Name attribute to provide a unique name to be referenced from personalization tags.

One or more <Category> elements must be nested within a filtering subelement, except for the AllItems and AllCategories subelements. Contents of a <Category> element must be a string representing a long integer.

Definition

<!ELEMENT Filtering   (ExcludeItems|IncludeItems|ExcludeCategories|
                       IncludeCategories|CategoryLevel|SubTreeItems|
                       SubTreeCategories|AllItems|AllCategories) >
   <!ATTLIST Filtering Name CDATA #REQUIRED>
   <!ATTLIST Filtering TaxonomyID CDATA #REQUIRED>

<!ELEMENT Category (#PCDATA) >
<!ELEMENT ExcludeItems ( Category+ ) >
<!ELEMENT IncludeItems ( Category+ ) >
<!ELEMENT ExcludeCategories ( Category+ ) >
<!ELEMENT IncludeCategories ( Category+ ) >
<!ELEMENT CategoryLevel ( Category+ ) >
<!ELEMENT SubTreeItems ( Category+ ) >
<!ELEMENT SubTreeCategories ( Category+ ) >
<!ELEMENT AllItems EMPTY >
<!ELEMENT AllCategories EMPTY >

DefaultFiltering Element

Use this element for filtering settings in the absence of individual filtering tag attributes or a filteringName tag attribute (and corresponding <Filtering> element in personalization.xml).

Definition


<!ELEMENT DefaultFiltering (ExcludeItems|IncludeItems|ExcludeCategories|
                            IncludeCategories|CategoryLevel|SubTreeItems
                            SubTreeCategories|AllItems|AllCategories) >
   <!ATTLIST DefaultFiltering TaxonomyID CDATA #REQUIRED>

<!ELEMENT Category (#PCDATA) >
<!ELEMENT ExcludeItems ( Category+ ) >
<!ELEMENT IncludeItems ( Category+ ) >
<!ELEMENT ExcludeCategories ( Category+ ) >
<!ELEMENT IncludeCategories ( Category+ ) >
<!ELEMENT CategoryLevel ( Category+ ) >
<!ELEMENT SubTreeItems ( Category+ ) >
<!ELEMENT SubTreeCategories ( Category+ ) >
<!ELEMENT AllItems EMPTY >
<!ELEMENT AllCategories EMPTY >

Sample personalization.xml File

<?xml version="1.0" ?>
<personalization-config>
    <description> Sample personalization config file </description>
   <RecommendationSettings maxQuantity="5" />
   <RE Name="RE1" URL="jdbc:oracle:thin:@sid" Schema="RESCHEMA"
       Password="secret" CacheSize="2999" FlushInterval="30000" />
   <RE Name="RE2" URL="jdbc:oracle:oci:@acme" Schema="RE2-schema"
       Password="RE2-pwd" CacheSize="5555" FlushInterval="100000" />
   <Tuning Name = "tuning1" DataSource="ALL"
           InterestDimension="NAVIGATION"
           PersonalizationIndex="HIGH" ProfileDataBalance="BALANCED"
           ProfileUsage="INCLUDE" />
   <DefaultTuning DataSource="PURCHASING" InterestDimension="RATING"
           PersonalizationIndex="MEDIUM" ProfileDataBalance="CURRENT"
           ProfileUsage="EXCLUDE" />
   <Filtering Name = "filter1" TaxonomyID="25" >
      <CategoryLevel>
         <Category>10</Category>
         <Category>11</Category>
         <Category>15</Category>
      </CategoryLevel>
   </Filtering>
   <DefaultFiltering  TaxonomyID="1" >
      <AllItems/>
   </DefaultFiltering>
</personalization-config>


Go to previous page Go to next page
Oracle
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index