Oracle® Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference
10g Release 2 (10.1.2) B14016-02 |
|
Previous |
Next |
This chapter documents the tag library supplied with OC4J for use with Oracle Application Server Personalization. Use of this library assumes that the OracleAS Personalization product has been properly installed.
The chapter consists of the following section:
For information about OracleAS Personalization itself, see the Oracle Application Server Personalization Administrator's Guide and the Oracle Application Server Personalization 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 OracleAS Personalization tag library exposes two key functions of personalization:
Choosing the most relevant content to deliver, based on past user behavior as collected in the user profile
Embedding this personalized content into application output or Web pages in a flexible manner
A typical personalization scheme might take any or all of the following into account:
User Web-surfing patterns
Past user purchase activities
Past user ratings of items
Anticipated nature and degree of user interest (such as "buy" versus "like")
User demographics, such as age, sex, and income
Note: The concept of personalization is not limited to Web sites and Web applications. You can use personalization in any application where there is appropriate data and a need for personalized recommendations, such as CRM applications. Web applications are the focus of this particular document, however. |
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—local weather, stocks of interest, or favorite sports, for example—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.
OracleAS Personalization uses data mining algorithms in Oracle Database to choose the most relevant content available for a user. Recommendations are calculated by an OracleAS 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 OracleAS Personalization controls data collection, with OracleAS Personalization itself providing targeted data. This process allows the application to avoid collecting large volumes of data of only minimal usefulness.
The OracleAS 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 OracleAS Personalization environment, recommendations are based on one or more factors such as the following:
Past behavior of similar users, according to demographics
Behavior of past users who have shown the same interests, such as a general trend being established that users who look at items 1, 2, and 3 are likely to be interested in items 5 and 6 as well, without considering the demographics or profiles of the users
Behavior of the same user earlier in the current session, allowing user-specific personalization even for first-time users or anonymous visitors, as well as providing a high degree of tuning regarding the purpose of the current visit
Hot picks recommendations, based on current promotions, features of the week, and so on, which might or might not account for user identity
OracleAS Personalization includes the following key components:
Mining table repository (MTR)
Mining object repository (MOR)
Recommendation engine farm, consisting of one or more recommendation engines
Recommendation engine Java API
These are all introduced in upcoming sections.
The OracleAS 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:
Records of previous user behavior
Data collected elsewhere and imported into the repository
User demographics
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 OracleAS 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 OracleAS Personalization Mining Object Repository (MOR) is a database schema that maintains mining meta data and mining model results as defined in the OracleAS Personalization data mining schema. The mining object repository serves as the focus for logging in to the data mining system, logging off, and scheduling OracleAS Personalization events. The building of models out of the mining table repository is accomplished according to OracleAS 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 might 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 OracleAS Personalization Recommendation Engine (RE) is an Oracle Database schema that downloads an OracleAS Personalization model during deployment, then 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:
Loading and holding model data
Processing recommendation requests
Collecting user profile data
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.
OracleAS 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 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 API is wrapped in the functionality of the OracleAS Personalization tag library, so this document does not discuss details of the API. The tag library provides programming convenience, automating features that you must manage explicitly if you use the API directly.
The following sections provide an overview of concepts and features for the OracleAS Personalization recommendation engine:
The recommendation engine has two classifications of users:
Visitor: This is an anonymous user who is not recognized and does not have a demographic profile or a stored history of past behavior, preferences, and actions.
Customer: This is a registered user who is therefore recognized and has a demographic profile and stored history of behavior to be used in generating accurate recommendations.
Note: An anonymous visitor can be converted into a registered user in the middle of a session. See "Personalization setVisitorToCustomer Tag". |
In OracleAS Personalization, item is a generic concept referring to a single article or the smallest unit of information. Following are some examples:
Product
Service to purchase
URL selected by a user
Piece of demographic data such as a user's gender or age
Items are used in several ways:
They can be passed to item-recording tags for the recording of user data. In this situation they are sometimes referred to as data items.
They can be returned as suggestions. In this situation, they are referred to as recommendations. For each item returned as a recommendation, there is also a prediction value, which is either a rating or a ranking. These terms are discussed in "Ratings and Rankings".
They can be passed as input when the application requests recommendations. This is done for cross-selling, where recommended items are based on past items, or to evaluate and rate or rank a particular set of items.
All individual items in an inventory system must belong to a taxonomy. In OracleAS 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
might 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. 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 OracleAS 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:
For a rating item, the prediction value of each item is its rating. This is a predicted measure of user interest.
For a purchasing or navigation item, the prediction value indicates a relative ranking among the returned items, based on the estimated probability of user interest.
A navigation item can represent anything a Web application might consider a "hit", such as viewing a page, selecting a link, or clicking a button.
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, OracleAS 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, by a recommendation tag) is a predicted value, according to OracleAS Personalization algorithms.
In an OracleAS 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). 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. It is relative because ranking is meaningful only for a number of items compared to each other and sorted in a certain order. It is dynamic because ranking of the same item might change for different customers or when ranked against different items.
Web applications can be either stateful or stateless. That is, an application might choose to maintain a user session and user-specific information on the server between requests, or it might 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 therefore behavior of any one anonymous visitor would influence recommendations to the others. You can avoid this problem by assigning each anonymous visitor a temporary ID that is unique within the recommendation engine.
Note: One of the advantages of the tag library, compared to using the recommendation engine API directly, is that tracking of recommendation engine sessions in a stateless application is managed automatically. You must arrange this mapping yourself if you use the API directly.Be aware, however, that recommendation engine session tracking through the tag library requires the client, presumably a browser, to support and accept cookies. If this is not always guaranteed, then you must declare your application as stateful. |
After a recommendation engine session is established and populated with data, an application can request recommendations from it. OracleAS Personalization returns the appropriate recommendations to the calling application, then 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 OracleAS 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. This depends 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 OracleAS 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.
The following sections provide an overview of features and functionality of the OracleAS Personalization tag library. For descriptions and syntax of the individual tags, see "Personalization Tag and Class Descriptions".
Use of Tuning, Filtering, and Sorting for Recommendation and Evaluation Tags
Note: The OracleAS Personalization tag library does not assume that HTML will be the only output format. Other formats, such as XML and JavaScript, are supported as well. |
The actions of creating and closing a recommendation engine session are handled through the startRESession
and endRESession
tags. For a JSP page using OracleAS Personalization, you must ensure that at least one startRESession
tag is executed and that it is the first OracleAS Personalization tag encountered for the particular recommendation engine session.
The OracleAS 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. 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 more 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, 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:
If the application intends to subsequently start a new recommendation engine session with a different recommendation engine user ID from the same browser or within the same HTTP session
To connect to a different recommendation engine from the same browser or within the same HTTP session
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 OracleAS 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.
Note: IfendRESession is not used in a stateful application, the underlying recommendation engine session will be closed automatically when the HTTP session goes out of scope. In a stateless application, the underlying recommendation engine session is allowed to time out.
|
The OracleAS Personalization tag library provides a number of tags for item manipulation. There are 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.
The following section provide an overview of how to use the tag library:
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
Note: 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 aboutREFlushInterval 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 remove
XXX
Record
tags. If you place your record
XXX
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:
selectFromHotPicks
getRecommendations
getCrossSellRecommendations
evaluateItems
For the selectFromHotPicks
, getRecommendations
, and getCrossSellRecommendations
tags, which are 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. The picks to choose from can be specified through a tag attribute. See the Oracle Application Server 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 additional 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 OracleAS Personalization tag library, because the results do not depend on the user. It might 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 that 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? These could be 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 the following section, "Use of Tag-Extra-Info Scripting Variables for Returned Items", 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, either 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 Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide. |
There are two general situations where you must input items:
To provide input items to a 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.
To record an item into the recommendation engine session or, using similar syntax, to remove an item that was previously recorded
This involves a record
XXX
or remove
XXX
Record
tag.
You can specify items in the following general ways:
Specify the type and ID of each desired item, and also the rating value for a rating item. Or, for a demographic item, specify the type and value.
Supply an item array, and the index into the array for each desired item.
Supply an entire array of items (not relevant for record
XXX
and remove
XXX
Record
tags).
For scenarios #2 and #3, see the following section, "Inputting Item Arrays", for more information.
You can input one or more items into a getCrossSellRecommendations
or evaluateItems
tag as follows:
Nest one or more forItem
tags inside the tag, using the type
and ID
attributes of each forItem
tag to specify a desired item (scenario #1 above).
or:
Nest one or more 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).
or:
Specify an 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 record
XXX
or remove
XXX
Record
tag as follows:
Use the 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.
or:
Use the 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 can 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:
Create it in a scriptlet and specify it through a JSP expression:
<% Item[] myList = newItem[] {newItem("shoes", 1)}; %> <op:evaluateItems inputItemList="<%=myList %> .../>
Supply it by using a TEI variable that contains the output from a recommendation tag:
<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 columns you can customize: ATTRIBUTE1
through ATTRIBUTE50
. To use a custom type, you must do the following:
Map the ATTRIBUTEx
column to an existing enterprise database, thus defining what the attribute is.
Define the corresponding value boundaries in the MTR.MTR_BIN_BOUNDARIES
table.
You can currently use one mode of operation for item recording tags: receiving mode. In this mode, if users select something such as an item to purchase or a URL to navigate to, then the page they are sent to, referred to as the receiving page, contains the record
XXX
tag to record the item.
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 Details link that a user can select to get more information and a Purchase link that a user can select to purchase the item. You can place a recordNavigation
tag in the page the user goes to by selecting Details; and you can place a recordPurchase
tag in the page the user goes to by selecting 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 where users 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 he is single, age 44, with an annual salary of $50,000—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 record
XXX
tag along with the index. This approach has at least one advantage, in that 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. The following sections document tuning and filtering settings you can use to more carefully tailor the recommendations that are returned. There is also information about 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.
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 tuning
XXX
attributes of the selectFromHotPicks
, getRecommendations
, getCrossSellRecommendations
, and evaluateItems
tags, as summarized in Table 10-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 (preferred) or the server-wide personalization.xml
file. Also see "Personalization Tag Library Configuration Files".
If there are no attribute settings and no <Tuning>
element, default values will be chosen according to the following steps, in order:
According to a <DefaultTuning>
element in the application-level personalization.xml
file.
According to a <DefaultTuning>
element in the server-wide personalization.xml
file.
According to the following hardcoded settings:
tuningDataSource="ALL" tuningInterestDimension="NAVIGATION" tuningPersonalizationIndex="MEDIUM" tuningProfileDataBalance="BALANCED" tuningProfileUsage="INCLUDE"
Note: To use the hardcoded defaults, do not use any of thetuning XXX attribute settings. If some tuning settings are defined in a tag, then none of the hardcoded values will be used. In this case, if any setting cannot be found in a tag attribute or personalization.xml file, an exception will be thrown.
|
Table 10-1 Tuning Settings for Requesting Recommendations
Attribute | Description | Settings |
---|---|---|
tuningDataSource |
Specify the kind of past user data to be considered in making recommendations. (Do not confuse this kind of data source with the data source concept in the J2EE platform model.) |
|
tuningInterestDimension |
Specify the kind of recommendation to be returned. |
|
tuningPersonalizationIndex |
Choose how generalized or how personalized the recommendation algorithm should be. |
|
tuningProfileDataBalance |
Choose whether to stress historical data, current session data, or both in making recommendations. |
|
tuningProfileUsage |
Choose whether to use data in the user's demographic profile. |
|
For more information about tuning settings, refer to the Oracle Application Server 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 filtering
XXX
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 (preferred) or the server-wide personalization.xml
file. Also see "Personalization Tag Library Configuration Files".
If there are no attribute settings and no <Filtering>
element, default values will be chosen from the <DefaultFiltering>
element in either the application-level personalization.xml
file (preferred) 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 OracleAS 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 10-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 MTR.MTR_CATEGORY
table of the mining table repository.
Note: Do not provide afilteringCategories setting when filteringMethod is ALL_ITEMS or ALL_CATEGORIES .
|
Table 10-2 Filtering Methods for Requesting Recommendations
Filtering Method | Description |
---|---|
|
Recommend items from all leaves in the taxonomy. |
|
Recommend items that belong to the categories specified in |
|
Recommend items in the taxonomy that do not belong to the categories specified in |
|
Recommend items that belong to the subtrees of the categories specified in |
|
Recommend all categories in the taxonomy. |
|
Recommend categories specified in |
|
Recommend categories in the taxonomy that are not specified in |
|
Recommend categories from the subtrees of the categories specified in |
|
Recommend categories of the same level as the categories specified in |
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 Oracle Application Server Personalization 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; 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.
The following sections provide detailed descriptions of syntax and usage for the OracleAS Personalization tags and the Item
public class, concluding with a discussion of tag limitations:
Note the following requirements for the OracleAS Personalization tag library:
Verify that the file ojsputil.jar
is installed and in your classpath. This file is provided with OC4J, in the "well-known" tag library directory.
You will need the classes for the recommendation engine API, which are in the oreapi-rt.jar
file. If you install Oracle 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.
The tag library descriptor, personalization.tld
, must be available to the application, and any JSP page using the library must have an appropriate taglib
directive. In an Oracle Application Server installation, the TLD is in ojsputil.jar
. The uri
value for personalization.tld
is the following:
http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/personalization.tld
You can refer to the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide for information about taglib
directives, the well-known tag library directory, TLD files, and the meaning of uri
values.
Notes:
|
Using some of the tag attributes described here requires some general knowledge of the OracleAS Personalization and recommendation engine implementations. Where information here is incomplete, see the Oracle Application Server Personalization Administrator's Guide or the Oracle Application Server Personalization Programmer's Guide.
The following sections document 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 OracleAS Personalization tag that executes within the same recommendation engine session.
<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" ] />
The startRESession
tag has no body.
Also see "Attribute Usage Notes" following the attribute descriptions.
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 mentioned in the attribute usage notes. See "Personalization Tag Library Configuration Files" for related information.
REURL
: This is the JDBC connection string for the recommendation engine database.
RESchema
: This is the name of the recommendation engine database schema.
REPassword
: This is the password corresponding to the RESchema
name.
If the OC4J jazn-data.xml
file contains a <user>
element for an account, scott
for example, in the recommendation engine database, you can get the de-obfuscated password from there by using special right-arrow syntax with a dash ("-
") and right-carrot (">
") followed by the account name, such as:
password="->scott"
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.
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.
session
: Use a "true
" setting (default) to specify that you want your OracleAS 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 record
XXX
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
".
For the 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 nondefault 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.
Note: WhenREName matches the name of an existing connection, any settings for REURL , RESchema , REPassword , RECacheSize , and REFlushInterval are superfluous and therefore ignored.
|
You can use the 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 mechanism.
Although default values are provided for 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. The default flush interval of 60 seconds (60000 milliseconds) results in a cache incoming rate of 80 items each second. If you increase the flush interval to 120 seconds, you can support only 40 new items being added each second. On the other hand, if you reduce the flush interval to 30 seconds, you can support a cache incoming rate of 160 items each second. A disadvantage in shortening the flush interval, however, is that removing an item (through a remove
XXX
Record
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.
The following example shows a startRESession
tag that establishes the URL and user name, scott
, for the recommendation engine database and gets the de-obfuscated password for the scott
account from the OC4J jazn-data.xml
file. This assumes an entry for scott
in jazn-data.xml
.
<op:startRESession REName = "RE1" REURL = "@jdbc:oracle:thin:@sid" RESchema = "scott" REPassword = "->scott" />
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:
If you started the recommendation engine session with the 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.
If you started the recommendation engine session with 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.
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
is a request-time attribute and must be provided by the application.
The following sections provide 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".
<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>
Also see "Attribute Usage Notes" following the attribute descriptions.
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, then the scope of the variable is AT_BEGIN
, meaning it is 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, then the scope of the variable is AT_BEGIN
, meaning it is 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 tuning
XXX
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 filtering
XXX
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.
You must specify either from
or fromHotPicksGroups
.
Access the output items either through the storeResultsIn
attribute, or through a tag body with nested getNextItem
tags, or optionally both.
Specify tuningName
, corresponding to the name of a <Tuning>
element in personalization.xml
, or specify individual tuning settings through the tuning
XXX
attributes. If you do neither, see "Tuning Settings" for information about how default values are chosen. Also see "Personalization Tag Library Configuration Files".
Specify filteringName
, corresponding to the name of a <Filtering>
element in personalization.xml
, or specify individual filtering settings through the filtering
XXX
attributes. If you do neither, see "Recommendation Filtering" for information about how default values are chosen.
A 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
.
The XXX
_CATEGORIES
filtering methods return categories, as defined in the mining table repository, rather than specific items.
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.
<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>
Also see "Attribute Usage Notes" following the attribute descriptions.
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 mentioned in the attribute usage notes, and the fact that storeResultsIn
is a required attribute for the getCrossSellRecommendations
tag.
For additional information about tuning, filtering, and sorting, see "Tuning Settings", "Recommendation Filtering", and "Sorting Order".
Inputting items requires the 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.
Unlike for the 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.
Specify tuningName
, corresponding to the name of a <Tuning>
element in personalization.xml
, or specify individual tuning settings through the tuning
XXX
attributes. If you do neither, see "Tuning Settings" for information about how default values are chosen. Also see "Personalization Tag Library Configuration Files".
If the tuningInterestDimension
setting is not the same as the tuningDataSource
setting, you might not get any recommendations, depending on how OracleAS Personalization rules are set.
Specify filteringName
, corresponding to the name of a <Filtering>
element in personalization.xml
, or specify individual filtering settings through the filtering
XXX
attributes. If you do neither, see "Recommendation Filtering" for information about how default values are chosen.
A filteringCategories
setting is required, unless filteringMethods
is set to "ALL_ITEMS
". These settings can be through either the tag attributes or personalization.xml
.
The 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
.
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".
<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>
Also see "Attribute Usage Notes" following the attribute descriptions.
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 mentioned in the 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.
The hotPicksGroups
attribute is equivalent to the fromHotPicksGroups
attribute of the getRecommendations
tag, but hotPicksGroups
is required.
Access the output items through the storeResultsIn
attribute or through a tag body with nested getNextItem
tags, or optionally both.
Specify tuningName
, corresponding to the name of a <Tuning>
element in personalization.xml
, or specify individual tuning settings through the tuning
XXX
attributes. If you do neither, see "Tuning Settings" for information about how default values are chosen. Also see "Personalization Tag Library Configuration Files".
Specify filteringName
, corresponding to the name of a <Filtering>
element in personalization.xml
, or specify individual filtering settings through the filtering
XXX
attributes. If you do neither, see "Recommendation Filtering" for information about how default values are chosen.
A 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
.
The XXX
_CATEGORIES
filtering methods return categories, as defined in the mining table repository, rather than specific items.
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".
<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>
Also see "Attribute Usage Notes" following the attribute descriptions.
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 mentioned in the attribute usage notes, and the fact that storeResultsIn
is a required attribute for the evaluateItems
tag.
For additional information about tuning and sorting, see "Tuning Settings" and "Sorting Order".
Inputting items requires the 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.
Unlike for the 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.
Specify tuningName
, corresponding to the name of a <Tuning>
element in personalization.xml
, or specify individual tuning settings through the tuning
XXX
attributes. If you do neither, see "Tuning Settings" for information about how default values are chosen. Also see "Personalization Tag Library Configuration Files".
There are no filtering attributes for the 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
.
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.
<op:forItem [ itemList = "item_array_expression" ] [ index = "index_into_item_array" ] [ type = "type_of_item" ] [ ID = "item_ID_number" ] />
The forItem
tag has no body.
There are two modes of use for this tag:
Use both index
and itemList
.
or:
Use both type
and ID
.
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". Use this attribute together with ID
. Do not use it if you use index
and itemList
.
ID
: This is an identification number, unique for each item of a given type. Use this attribute together with type
. Do not use it 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, then 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.
Be aware of the following:
Using the explicit item array from a 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.
If you use one or more 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 for 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" ] />
The getNextItem
tag has no body.
There are two modes of use for this tag:
Use both storeTypeIn
and storeIDIn
.
or:
Use storeItemIn
.
Also see "Attribute Usage Notes" following the attribute descriptions.
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
.
All TEI variables are of scope AT_END
, meaning they are available from the end-tag to 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.
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>
The following sections provide detailed descriptions of the record
XXX
and remove
XXX
Record
tags. Use the appropriate record
XXX
tag to record an item into the recommendation engine session cache. Use the corresponding remove
XXX
Record
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".
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 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.
<op:recordNavigation [ type = "type_of_item" ] [ ID = "item_ID_number" ] [ itemList = "item_array_expression" ] [ index = "index_into_item_array" ] />
The recordNavigation
tag has no body.
There are two modes of use for this tag:
Use both type
and ID
.
or:
Use both index
and itemList
.
See "Specification of Input Items" for related information.
type
: This is for the type of item, such as "shoes". Use this attribute together with ID
. Do not use it if you use index
and itemList
.
ID
: This is an identification number, unique for each item of a given type. Use this attribute together with type
. Do not use it 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.
<op:recordPurchase [ type = "type_of_item" ] [ ID = "item_ID_number" ] [ itemList = "item_array_expression" ] [ index = "index_into_item_array" ] />
The recordPurchase
tag has no body.
There are two modes of use for this tag:
Use both type
and ID
.
or:
Use both index
and itemList
.
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 selects 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 might 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 rating value must also be specified.
<op:recordRating value = "rating_value" [ type = "type_of_item" ] [ ID = "item_ID_number" ] [ itemList = "item_array_expression" ] [ index = "index_into_item_array" ] />
The recordRating
tag has no body.
There are two modes of use for this tag:
Use both type
and ID
.
or:
Use both index
and itemList
.
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 record
XXX
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
".
<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" />
The recordDemographic
tag has no body.
type
(required): Specify one of the supported demographic types. In addition to the several named types, there are 50 types you can customize: 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.
<op:removeNavigationRecord [ type = "type_of_item" ] [ ID = "item_ID_number" ] [ itemList = "item_array_expression" ] [ index = "index_into_item_array" ] />
The removeNavigationRecord
tag has no body.
There are two modes of use for this tag:
Use both type
and ID
.
or:
Use both index
and itemList
.
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.
<op:removePurchaseRecord [ type = "type_of_item" ] [ ID = "item_ID_number" ] [ itemList = "item_array_expression" ] [ index = "index_into_item_array" ] />
The removePurchaseRecord
tag has no body.
There are two modes of use for this tag:
Use both type
and ID
.
or:
Use both index
and itemList
.
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 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.
<op:removeRatingRecord value = "rating_value" [ type = "type_of_item" ] [ ID = "item_ID_number" ] [ itemList = "item_array_expression" ] [ index = "index_into_item_array" ] />
The removeRatingRecord
tag has no body.
There are two modes of use for this tag:
Use both type
and ID
.
or:
Use both index
and itemList
.
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 that was previously recorded.
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 remove
XXX
Record
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.
<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" />
The removeDemographicRecord
tag has no body.
Attributes are the same as for the recordDemographic
tag. See "Personalization recordDemographic Tag".
The OracleAS 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 must use, and sometimes create, Item
instances directly:
When you want to retrieve type, ID, and prediction values from a recommendation item
For a purchasing or navigation item, the prediction value is a ranking. For a rating item, the prediction value is a rating.
When you want to create instances manually for input item lists for the getCrossSellRecommendations
and evaluateItems
tags
The Item
class provides the following getter methods for the first scenario:
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:
void setType(java.lang.String)
Set the item type.
void setID(long)
Set the item ID number.
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:
Item()
Item(String type, long ID)
Item(String type, 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 the following values for comparisons to values returned in the storeInterestDimensionIn
attribute of the recommendation tags.
INT_DIM_NAVIGATION
: This indicates an item recommended for its high navigation interest.
INT_DIM_PURCHASING
: This indicates an item recommended for its high purchasing interest.
INT_DIM_RATING
: This indicates an item recommended for its high rating interest.
Be aware of the following constraints regarding attribute settings for the OracleAS Personalization tags.
The startRESession
tag has the following limitations:
The REName
attribute has a maximum of 12 characters.
The REURL
attribute has a maximum of 256 characters.
The RESchema
attribute has a maximum of 30 characters.
The REPassword
attribute has a maximum of 30 characters.
The userID
attribute has a 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
.
There can be no more than 1024 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.
For the recommendation tags—getRecommendations
, getCrossSellRecommendations
, and selectFromHotPicks
—a maximum of 1024 hot picks groups can be specified. This applies to the fromHotPicksGroups
attribute of the getRecommendations
and getCrossSellRecommendations
tags, and to the hotPicksGroups
attribute of the fromHotPicksGroups
tag.
Also for the recommendation tags, the 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.
Maximum length of the value
attribute for the recordDemographic
, removeDemographicRecord
, recordRating
, and removeRatingRecord
tags is 60 characters.
The OracleAS Personalization tag library supports the use of configuration files, named personalization.xml
, to specify global and default tag attribute settings. The following sections document personalization.xml
files and their supported elements:
The OracleAS 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 can 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.
ORACLE_HOME
/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 for personalization.xml
elements supported by the OracleAS Personalization tag library. These elements are inside a top-level <personalization-config>
element.
The personalization tags will validate any personalization.xml
file against this DTD.
Note: Also see "Personalization Tag Constraints". Some of these limitations apply topersonalization.xml elements as well as to tag attribute settings.
|
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.
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.
If the OC4J jazn-data.xml
file contains a <user>
element for an account in the recommendation engine database (scott
for example), you can get the de-obfuscated password from there by using special right-arrow syntax with a dash ("-
") and right-carrot (">
") followed by the account name, such as:
Password="->scott"
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 the Oracle Application Server Personalization Programmer's Guide for more information.
Use this element for tuning settings if there are no individual tuning tag attributes and no tuningName
tag attribute (with corresponding <Tuning>
element in personalization.xml
).
Attribute meanings are the same as for the <Tuning>
element discussed immediately above.
<!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 if there are no individual filtering tag attributes and no filteringName
tag attribute (with 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>
Alternatively, if there are jazn-data.xml
entries for the RESCHEMA
and RE2-schema
accounts, you can get the de-obfuscated passwords from there instead of specifying them in clear text in personalization.xml
, as follows:
<RE Name="RE1" URL="jdbc:oracle:thin:@sid" Schema="RESCHEMA" Password="->RESCHEMA" CacheSize="2999" FlushInterval="30000" /> <RE Name="RE2" URL="jdbc:oracle:oci:@acme" Schema="RE2-schema" Password="->RE2-schema" CacheSize="5555" FlushInterval="100000" />