Oracle9iAS Containers for J2EE JSP Tag Libraries and Utilities Reference Release 2 (9.0.2) Part Number A95883-01 |
|
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.
This section introduces personalization, first covering general concepts and then providing an overview of the Oracle implementation in particular.
This overview covers general personalization concepts and describes the differences between personalization and customization, concepts that are sometimes confused.
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, 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.
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.
Depending on the configuration and "tuning" of an Oracle9iAS Personalization environment, recommendations may be based on one or more factors such as the following:
Oracle9iAS Personalization includes the following key components:
These are all introduced in upcoming sections.
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.
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.
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.
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.
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.
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:
The recommendation engine has two classifications of users:
An anonymous visitor can be converted into a registered user in the middle of a session--at the time of registration, for example. See "Personalization setVisitorToCustomer Tag".
Note:
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.
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.
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.
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.
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.
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.
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:
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.
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".
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.
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)
.
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.
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:
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.
recordNavigation
and removeNavigationRecord
recordPurchase
and removePurchaseRecord
recordRating
and removeRatingRecord
recordDemographic
and removeDemographicRecord
During the session, recorded items are periodically flushed to the recommendation engine. Removing an item after that point still works, but requires a database round-trip. See related information about
Note:
REFlushInterval
in "Personalization startRESession Tag".
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".
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.
Following is some further information about each of the recommendation tags. For detailed tag descriptions, see "Recommendation and Evaluation Tag Descriptions".
selectFromHotPicks
--The items returned are from a set of hot picks groups. Use the hotPicksGroups
attribute to specify the hot picks groups to choose from. In a sense, this as a "non-personal" tag in the Oracle9iAS Personalization tag library, because the results do not depend on the user. It may still be useful in personalized applications, however, for displaying promotions for a first-time visitor or for a particular geographical area or interest group, for example.
getRecommendations
--The items returned are based on the user, but you can also specify that they must be from a set of hot picks groups specified through the fromHotPicksGroups
attribute.
getCrossSellRecommendations
--The items returned are based on input items. You can also specify that the items returned must be from a set of hot picks groups specified through the fromHotPicksGroups
attribute. The input items are assumed to be of previous interest to one user. Functionality of this tag attempts to answer the following question: Assuming a user bought or navigated to the input items in the past, what are the most likely additional items of interest to that user in the future--additional items to purchase or navigate to (according to the interest dimension)?
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".
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.
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. |
There are two general situations where you must input items:
getCrossSellRecommendations
or evaluateItems
tag
In addition to the getCrossSellRecommendations
or evaluateItems
tag, this can involve one or more nested forItem
tags. The forItem
tags are used to select desired input items.
This involves a recordXXX
or removeXXXRecord
tag.
You can specify items in the following general ways:
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:
forItem
tags inside the tag, using the type
and ID
attributes of each forItem
tag to specify a desired item (scenario #1 above).
forItem
tags inside the tag, using the itemList
attribute of each forItem
tag to specify an item array, and using the index
attribute to specify a desired element of the array (scenario #2).
Item[]
array through the inputItemList
attribute of the tag (scenario #3). The entire array is taken as input.
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:
type
and ID
attributes of the tag, and the value
attribute for recordRating
or removeRatingRecord
, to specify the item (scenario #1 above). Or, for recordDemographic
or removeDemographicRecord
, use the type
and value
attributes.
itemList
attribute of the tag to specify an item array, and the index
attribute of the tag to specify the desired element of the array (scenario #2).
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:
getCrossSellRecommendations
or evaluateItems
, when you use the inputItemList
attribute to input an entire array
forItem
(inside getCrossSellRecommendations
or evaluateItems
), recordPurchase
, recordNavigation
, recordRating
, removePurchaseRecord
, removeNavigationRecord
, or removeRatingRecord
, when you use the itemList
and index
attributes to input an array and specify one element of it for use
You can supply the array in the following ways:
<% Item[] myList = newItem[] {newItem("shoes", 1)}; %> <op:evaluateItems inputItemList="<%=myList %> .../>
<op:getRecommendations storeResultsIn="myRecs" .../> <!-- First tag is closed, but TEI variable is still in scope. Later use it in second tag. --> <op:getCrossSellRecommendations inputItemList="<%=myRecs %>" />
Note: See "Recommendation and Evaluation Tag Descriptions" for detailed syntax information for the tags shown here. |
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:
GENDER
AGE
MARITAL_STATUS
PERSONAL_INCOME
HOUSEHOLD_INCOME
IS_HEAD_OF_HOUSEHOLD
HOUSEHOLD_SIZE
RENT_OWN_INDICATOR
There are also 50 customizable columns: ATTRIBUTE1
through ATTRIBUTE50
.
To use a customizable type, you must do the following:
ATTRIBUTEx
column to an existing enterprise database, thus defining what the attribute is.
MTR.MTR_BIN_BOUNDARIES
table.
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.
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:
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:
<DefaultTuning>
element in the application-level personalization.xml
file.
<DefaultTuning>
element in the server-wide personalization.xml
file.
tuningDataSource="ALL" tuningInterestDimension="NAVIGATION" tuningPersonalizationIndex="MEDIUM" tuningProfileDataBalance="BALANCED" tuningProfileUsage="INCLUDE"
For more information about tuning settings, refer to the Oracle9iAS Personalization Administrator's Guide.
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:
filteringTaxonomyID
--This is a Java string representing an integer, where the integer is the ID of an item taxonomy in the Oracle9iAS Personalization environment.
filteringMethod
--This is one of ALL_ITEMS
, INCLUDE_ITEMS
, EXCLUDE_ITEMS
, SUBTREE_ITEMS
, ALL_CATEGORIES
, INCLUDE_CATEGORIES
, EXCLUDE_CATEGORIES
, SUBTREE_CATEGORIES
, and CATEGORY_LEVEL
. Table 9-2 summarizes the meanings. These methods always apply to the taxonomy specified through the filteringTaxonomyID
value.
For the getCrossSellRecommendations
tag, only the ALL_ITEMS
, INCLUDE_ITEMS
, EXCLUDE_ITEMS
, and SUBTREE_ITEMS
settings are supported.
filteringCategories
--This is a Java string of integer IDs, delimited by a single plus sign (+) after each ID, identifying existing item categories in the given taxonomy. Categories are defined in the mining table repository, in the MTR.MTR_CATEGORY
table.
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.
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.
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:
|
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.
This section documents the following tags for starting, ending, and managing recommendation engine sessions:
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". |
<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" ] />
startRESession
tag to work, REName
is a required attribute, and you must define REURL
, RESchema
, and REPassword
through tag attributes or through one of the personalization.xml
files. (Also see "Personalization Tag Library Configuration Files".)
REName
specifies the name of a recommendation engine connection in a recommendation engine farm. Multiple user sessions should share the same connection whenever possible, for greater efficiency. To accomplish this, use the same REName
value whenever you want to use the same connection. After the recommendation engine connection is created, it is cached, using the REName
value as a key.
If REURL
, RESchema
, or REPassword
is not set through attributes of the startRESession
tag that first establishes a connection, then the settings of all three must come from a personalization.xml
file with an <RE>
element whose Name
attribute matches the REName
value of the startRESession
tag. In this case, you must also set RECacheSize
and REFlushInterval
in the <RE>
element if you want non-default values. In this scenario, the application-wide personalization.xml
is searched first; the server-wide personalization.xml
is searched only if the application-wide file did not have an <RE>
element with the REName
value as its name.
REName
attribute together with <RE>
element settings to facilitate load-balancing among recommendation engines in a farm. Each <RE>
element points to a different recommendation engine in the farm. The JSP page can rotate among different recommendation engines in the farm by assigning different values to the REName
attribute of different startRESession
tags, according to some load-balancing heuristic.
RECacheSize
and REFlushInterval
, these are intended only to get you started. Once you have experience in running the application, you can tune these values according to Web site conditions. The settings of RECacheSize
and REFlushInterval
should be in coordination with each other, and according to your estimate of how quickly items might be added to the recommendation engine session cache as the result of user actions. The default cache size is 3234 KB, the maximum possible, which is enough space to store approximately 4800 items. With the default flush interval of 60 seconds (60000 msec), that allows a cache incoming rate of 80 items per second. If you increase the flush interval to 120 seconds, you can support only 40 new items being added per second. On the other hand, if you reduce the flush interval to 30 seconds, you can support a cache incoming rate of 160 items per second. A disadvantage in shortening the flush interval, however, is that removing an item (through a removeXXXRecord
tag) after it has been flushed requires a database round-trip.
Be aware that all sessions sharing the same recommendation engine connection within the same JVM are also sharing the same session cache. The cache incoming rate is cumulative across all such sessions.
REName
(required)--Use this to specify the name of a recommendation engine connection in a recommendation engine farm. Under some circumstances, it must also match the name of an <RE>
element in personalization.xml
so that settings can be retrieved from there, as noted in the attribute usage notes above. See "Personalization Tag Library Configuration Files" for related information.
REURL
--This is for the JDBC connection string for the recommendation engine database.
RESchema
--This is for the name of the recommendation engine database schema.
REPassword
--This is the password corresponding to the RESchema
name.
RECacheSize
--Use this to specify the size of the recommendation engine session cache, in kilobytes. The default is 3234 KB. This should be adjusted in coordination with REFlushInterval
, as described in the attribute usage notes above.
REFlushInterval
--Use this to specify how often the data in the recommendation engine session cache is flushed into the recommendation engine schema. The unit is milliseconds, with a default of 60000 (1 minute). This should be adjusted in coordination with RECacheSize
, as described in the attribute usage notes above.
session
--Use a "true" setting (default) to specify that you want your Oracle9iAS Personalization JSP pages to act in a stateful manner, through the use of HTTP session objects. Use a "false" setting for pages to act in a stateless manner, using cookies instead.
userType
--This indicates whether the Web site user is an anonymous "visitor" (default) or a registered "customer".
userID
--This is the user name for the Web site user. If not provided, such as for an anonymous visitor, the ID is generated automatically by the tag handler.
storeUserIDIn
--If you want to store the userID
value for later use, storeUserIDIn
can specify the name of a TEI String
variable in which to store it. This attribute is useful for automatically generated user IDs.
disableRecording
--Use a "true" setting to disable the actions of any recordXXX
tags. This is to allow for the possibility, for example, of a Web site that permits users to specify that their activities should not be recorded. It is also a way to improve site performance during peak hours. This attribute can be set at request-time, based on the current user ID, for example. This permits recording to be disabled for appropriate users only, or at appropriate times, without changing your JSP code. The default setting is "false".
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:
session
attribute of the startRESession
tag set to "true", then the recommendation engine session will be closed implicitly at the end of the HTTP session.
session
set to "false", then the recommendation engine session will be allowed to time out once it has been inactive for a sufficient period of time. The timeout interval is specified as a configuration parameter of the recommendation engine schema. The endRESession
tag has no effect.
The endRESession
tag has no attributes and no body.
<op:endRESession />
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.
<op:setVisitorToCustomer customerID = "registered_customer_name" />
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".
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". |
<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>
Be aware of the following:
from
or fromHotPicksGroups
.
storeResultsIn
attribute, or through a tag body with nested getNextItem
tags, or optionally both.
tuningName
, corresponding to the name of a <Tuning>
element in personalization.xml
, or specify individual tuning settings through the tuningXXX
attributes. If you do neither, see "Tuning Settings" for information about how default values are chosen. Also see "Personalization Tag Library Configuration Files".
filteringName
, corresponding to the name of a <Filtering>
element in personalization.xml
, or specify individual filtering settings through the filteringXXX
attributes. If you do neither, see "Recommendation Filtering" for information about how default values are chosen.
filteringCategories
setting is required, unless filteringMethods
is set to ALL_ITEMS
or ALL_CATEGORIES
. These settings can be through either the tag attributes or personalization.xml
.
XXX_CATEGORIES
filtering methods return categories, as defined in the mining table repository, rather than specific items.
from
--Use this if you want items to be selected from the entire taxonomy of items. A "top" setting, which is the default and is typical, displays the N (or less) most desirable items, where N is the maximum number of recommendations to display (maxQuantity
). A "bottom" setting displays the N (or less) least desirable items. This is useful, for example, if Product Management wants to know which items are least favored by customers.
fromHotPicksGroups
--Use this if you want items to be selected from one or more hot picks groups. The application must determine a series of hot picks group ID numbers, from the same recommendation engine that was specified in the startRESession
tag. In the fromHotPicksGroups
attribute, you must list the group ID numbers in a string, delimited by plus signs (+), such as "10+20+30".
storeResultsIn
--Optionally specify the name of a TEI variable of type Item[]
in which to store the resulting recommendations. (This is a required attribute for getCrossSellRecommendations
, but not for getRecommendations
.) If a variable name is provided, the scope of the variable is AT_BEGIN
--available from the start tag to the end of the page. Note that the value is a variable name, not a JSP expression. You must provide the variable name for translation; this is not a request-time attribute.
storeInterestDimensionIn
--Optionally specify the name of a TEI string variable in which to store the interest dimension, which is either NAVIGATION
, PURCHASING
, or RATING
. Use the Item
class defined constant INT_DIM_NAVIGATION
, INT_DIM_PURCHASING
, or INT_DIM_RATING
for comparisons. If a variable name is provided, the scope of the variable is AT_BEGIN
--available from the start tag to the end of the page. You must provide the variable name for translation; this is not a request-time attribute. The value returned will be the same as the tuningInterestDimension
setting used in the tag.
maxQuantity
--Use this if you want to specify a maximum number of recommendations that can be returned. This is optional if there is a general default specified in the <RecommendationSettings>
element of the application personalization.xml
file or the server-wide personalizaton.xml
file. Also see "Personalization Tag Library Configuration Files".
tuningName
--Use this to specify the name of a <Tuning>
element in personalization.xml
, so that tuning settings can be retrieved from there. Alternatively, use the individual tuningXXX
attributes.
tuningDataSource
--See "Tuning Settings".
tuningInterestDimension
--See "Tuning Settings".
tuningPersonalizationIndex
--See "Tuning Settings".
tuningProfileDataBalance
--See "Tuning Settings".
tuningProfileUsage
--See "Tuning Settings".
filteringName
--Use this to specify the name of a <Filtering>
element in personalization.xml
, so that filtering settings can be retrieved from there. Alternatively, use the individual filteringXXX
attributes.
filteringTaxonomyID
--See "Recommendation Filtering".
filteringMethod
--See "Recommendation Filtering".
filteringCategories
--See "Recommendation Filtering". Integers in the string are delimited by plus signs (+), such as "101+200+35".
sortOrder
--Use this to specify whether items are sorted in ascending order ("ASCEND", best match first) or descending order ("DESCEND"). The default is neither ("NONE"), for no sorting requirement. See "Sorting Order" for more information.
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.
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". |
<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>
Be aware of the following:
inputItemList
attribute, or a body with nested forItem
tags, or optionally both. If you use both mechanisms, then the forItem
tags will be executed first and the indicated items will be placed in an item list. Then the inputItemList
entries are considered and appended to the list.
getRecommendations
tag, storeResultsIn
is a required attribute for the getCrossSellRecommendations
tag--you must specify the name of a TEI variable of type Item[]
for storage of the resulting recommendations.
tuningName
, corresponding to the name of a <Tuning>
element in personalization.xml
, or specify individual tuning settings through the tuningXXX
attributes. If you do neither, see "Tuning Settings" for information about how default values are chosen. Also see "Personalization Tag Library Configuration Files".
tuningInterestDimension
setting is not the same as the tuningDataSource
setting, you might not get any recommendations, depending on how Oracle9iAS Personalization rules are set.
filteringName
, corresponding to the name of a <Filtering>
element in personalization.xml
, or specify individual filtering settings through the filteringXXX
attributes. If you do neither, see "Recommendation Filtering" for information about how default values are chosen.
filteringCategories
setting is required, unless filteringMethods
is set to ALL_ITEMS
. These settings can be through either the tag attributes or personalization.xml
.
getCrossSellRecommendations
tag cannot use category-based filtering; therefore, it supports only a limited set of filtering methods--ALL_ITEMS
, INCLUDE_ITEMS
, EXCLUDE_ITEMS
, and SUBTREE_ITEMS
.
inputItemList
--If you want to supply the input items through an Item[]
array, use this attribute with a JSP expression that returns the array. The item array in the expression can come from a prior recommendation tag. See "Inputting Item Arrays" for more information.
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".
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.
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". |
<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>
Be aware of the following:
hotPicksGroups
attribute is equivalent to the fromHotPicksGroups
attribute of the getRecommendations
tag, but hotPicksGroups
is required.
storeResultsIn
attribute, or through a tag body with nested getNextItem
tags, or optionally both.
tuningName
, corresponding to the name of a <Tuning>
element in personalization.xml
, or specify individual tuning settings through the tuningXXX
attributes. If you do neither, see "Tuning Settings" for information about how default values are chosen. Also see "Personalization Tag Library Configuration Files".
filteringName
, corresponding to the name of a <Filtering>
element in personalization.xml
, or specify individual filtering settings through the filteringXXX
attributes. If you do neither, see "Recommendation Filtering" for information about how default values are chosen.
filteringCategories
setting is required, unless filteringMethods
is set to ALL_ITEMS
or ALL_CATEGORIES
. These settings can be through either the tag attributes or personalization.xml
.
XXX_CATEGORIES
filtering methods return categories, as defined in the mining table repository, rather than specific items.
hotPicksGroups
(required)--You must use this to specify one or more hot picks groups from which the recommendations will be selected. The application must determine one or more hot picks group ID numbers, for the same recommendation engine that was specified in the startRESession
tag. In the hotPicksGroups
attribute, you must list the group ID numbers in a string, delimited by plus signs (+), such as "1+20+35".
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.
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". |
<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>
Be aware of the following:
inputItemList
attribute, or a body with nested forItem
tags, or optionally both. If you use both mechanisms, then the forItem
tags will be executed first, and the indicated items will be placed in an item list. Then the inputItemList
entries will be considered and appended to the list.
getRecommendations
tag, storeResultsIn
is a required attribute for the evaluateItems
tag--you must specify a TEI variable of type Item[]
for storage of the rated items.
tuningName
, corresponding to the name of a <Tuning>
element in personalization.xml
, or specify individual tuning settings through the tuningXXX
attributes. If you do neither, see "Tuning Settings" for information about how default values are chosen. Also see "Personalization Tag Library Configuration Files".
evaluateItems
tag, because the items to be rated are simply the items that are input. Therefore, you must specify the taxonomy through a separate attribute--taxonomyID
.
taxonomyID
(required)--This is an integer specifying the ID of the taxonomy the items are from.
inputItemList
--If you want to supply the input items through an Item[]
array, use this attribute with a JSP expression that returns the array. The item array in the expression can come from a prior recommendation tag. See "Inputting Item Arrays" for more information.
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".
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)); %>
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". |
<op:forItem [ itemList = "item_array_expression" ] [ index = "index_into_item_array" ] [ type = "type_of_item" ] [ ID = "item_ID_number" ] />
There are two modes of use for this tag:
or:
itemList
--Use a JSP expression that returns an Item[]
array. The item array in the expression can come from a prior recommendation tag. Use this attribute together with index
, which specifies a desired element of the array. Do not use this attribute if you use type
and ID
. See "Inputting Item Arrays" for more information.
index
--Use this to specify the index number of the desired element of an item array. Specify the item array in the itemList
attribute. Do not use this attribute if you use type
and ID
.
type
--This is for the type of items, such as "shoes". Do not use this attribute if you use index
and itemList
.
ID
--This is an identification number, unique for each item of a given type. Do not use this attribute if you use index
and itemList
.
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) %>
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:
getRecommendations
or selectFromHotPicks
tag, through the storeResultsIn
attribute, does not preclude the use of getNextItem
tags. The item array accessible through storeResultsIn
is unaffected by processing through getNextItem
tags.
getRecommendations
tags nested inside another getRecommendations
tag, or one or more selectFromHotPicks
tags inside another selectFromHotPicks
tag, then only one of the tags can use nested getNextItem
tags to access implicit tag results. Other tags in the nesting chain must use the storeResultsIn
attribute. No such restriction exists for a getRecommendations
tag inside a selectFromHotPicks
tag, or a selectFromHotPicks
tag inside a getRecommendations
tag.
<op:getNextItem [ storeTypeIn = "TEI_variable_for_item_type" ] [ storeIDIn = "TEI_variable_for_item_ID" ] [ storeItemIn = "TEI_variable_for_Item_instance" ] />
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.
storeTypeIn
--Specify the name of a TEI String
variable to store the type of the next item. Use this in conjunction with storeIDIn
; do not use it if you use storeItemIn
.
storeIDIn
--Specify the name of a TEI String
variable to store the ID of the next item. Use this in conjunction with storeTypeIn
; do not use it if you use storeItemIn
.
storeItemIn
--Specify the name of a TEI variable of type Item
to store the next item. Do not use this if you use storeTypeIn
and storeIDIn
.
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>
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:
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". |
<op:recordNavigation [ type = "type_of_item" ] [ ID = "item_ID_number" ] [ itemList = "item_array_expression" ] [ index = "index_into_item_array" ] />
There are two modes of use for this tag:
or:
See "Specification of Input Items" for related information.
type
--This is for the type of item, such as "shoes". Do not use this attribute if you use index
and itemList
.
ID
--This is an identification number, unique for each item of a given type. Do not use this attribute if you use index
and itemList
.
itemList
--Use a JSP expression that returns an Item[]
array. The item array in the expression can come from a prior recommendation tag. Use this attribute together with index
, which specifies a desired element of the array. Do not use this attribute if you use type
and ID
. See "Inputting Item Arrays" for more information.
index
--Use this to specify the index number of the desired element of an item array. Specify the item array in the itemList
attribute. Do not use this attribute if you use type
and ID
.
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". |
<op:recordPurchase [ type = "type_of_item" ] [ ID = "item_ID_number" ] [ itemList = "item_array_expression" ] [ index = "index_into_item_array" ] />
There are two modes of use for this tag:
or:
See "Specification of Input Items" for related information.
Attributes are the same as for the recordNavigation
tag--see "Personalization recordNavigation Tag".
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.
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". |
<op:recordRating value = "rating_value" [ type = "type_of_item" ] [ ID = "item_ID_number" ] [ itemList = "item_array_expression" ] [ index = "index_into_item_array" ] />
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.
value
(required)--This is a string representing the user rating value. An integer or floating point number can be entered. The number should be in the appropriate rating range, according to boundaries in the MTR.MTR_BIN_BOUNDARIES
table in the mining table repository.
The other attributes are the same as for the recordNavigation
tag--see "Personalization recordNavigation 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". |
<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" />
type
(required)--Specify one of the supported demographic types. In addition to the several named types, there are 50 customizable types--ATTRIBUTE1
, ATTRIBUTE2
, ..., ATTRIBUTE50
. See "Demographic Items" for additional information.
value
(required)--Specify an appropriate value, given the demographic type, such as "MALE" or "FEMALE" for a GENDER
item.
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". |
<op:removeNavigationRecord [ type = "type_of_item" ] [ ID = "item_ID_number" ] [ itemList = "item_array_expression" ] [ index = "index_into_item_array" ] />
There are two modes of use for this tag:
or:
See "Specification of Input Items" for related information.
Attributes are the same as for the recordNavigation
tag--see "Personalization recordNavigation 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". |
<op:removePurchaseRecord [ type = "type_of_item" ] [ ID = "item_ID_number" ] [ itemList = "item_array_expression" ] [ index = "index_into_item_array" ] />
There are two modes of use for this tag:
or:
See "Specification of Input Items" for related information.
Attributes are the same as for the recordNavigation
tag--see "Personalization recordNavigation 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". |
<op:removeRatingRecord value = "rating_value" [ type = "type_of_item" ] [ ID = "item_ID_number" ] [ itemList = "item_array_expression" ] [ index = "index_into_item_array" ] />
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.
The other attributes are the same as for the recordNavigation
tag--see "Personalization recordNavigation 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". |
<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 are the same as for the recordDemographic
tag--see "Personalization recordDemographic Tag".
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:
For a purchasing or navigation item, the prediction value is a ranking. For a rating item, the prediction value is a rating.
getCrossSellRecommendations
and evaluateItems
tags
The Item
class provides the following getter methods for the first scenario:
java.lang.String getType()
--Return the item type, such as "shoes", for example, or one of the supported demographic types for demographic items. A value of "CATEGORY" indicates that an entire category is being recommended.
long getID()
--Return the item ID number.
float getPrediction()
--Return either the rating, for a rating item, or the ranking, for a purchasing or navigation item. Rankings are always integers, but this attribute must be floating point because ratings can be floating point.
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:
void setCategory()
--Set the item type to "CATEGORY".
boolean isCategory()
--Returns true
if the item type is "CATEGORY".
The Item
class provides the following public constructors:
new Item()
new Item(java.lang.String type, long ID)
new Item(java.lang.String type, java.lang.String ID)
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:
INT_DIM_NAVIGATION
--for an item recommended for its high navigation interest
INT_DIM_PURCHASING
--for an item recommended for its high purchasing interest
INT_DIM_RATING
--for an item recommended for its high rating interest
Be aware of the following constraints regarding attribute settings for the Oracle9iAS Personalization tags:
startRESession
tag has the following limitations:
REName
attribute--maximum of 12 characters
REURL
attribute--maximum of 256 characters
RESchema
attribute--maximum of 30 characters
REPassword
attribute--maximum of 30 characters
userID
attribute--maximum of 32 characters
The same restrictions apply to the corresponding attributes of the <RE>
element of a personalization.xml
file, except for userID
, which is not used in personalization.xml
.
Item
elements passed into any tag or returned by any tag. This is not only the maximum size of any single Item[]
array passed to or from a tag, but is also a combined maximum if any tag receives input from both an item list and one or more forItem
tags.
getRecommendations
, getCrossSellRecommendations
, and selectFromHotPicks
--a maximum of 1024 hot picks groups can be specified. This applies to the fromHotPicksGroups
attribute of the getRecommendations
tag and the getCrossSellRecommendations
tag, and to the hotPicksGroups
attribute of the fromHotPicksGroups
tag.
filteringCategories
attribute can specify a maximum of 256 categories.
Equivalently, there can be a maximum of 256 <Category>
subelements in the <Filtering>
element of a personalization.xml
file.
value
attribute for the recordDemographic
, removeDemographicRecord
, recordRating
, and removeRatingRecord
tags is 60 characters.
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 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:
/WEB-INF/personalization.xml
Use this file for the particular application only, for any defaults or settings that are application-wide.
j2ee/home/config/personalization.xml
This is a server-wide configuration file. It is accessed for any required settings that cannot be found in tag attributes or in the personalization.xml
file for the particular application.
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 |
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.
<!ELEMENT RecommendationSettings EMPTY> <!ATTLIST RecommendationSetting maxQuantity CDATA #REQUIRED>
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.
<!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.
Use this element to define named tuning settings. See "Tuning Settings" for information about the attributes.
<!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.
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.
<!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" >
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.
<!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 >
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
).
<!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 >
<?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>
|
Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|