6 RE Batch API Overview

The OracleAS Personalization RE Batch API (Recommendation Engine Batch Application Programming Interface) enables an application written in Java to request OracleAS Personalization-style recommendations in bulk mode.

RE Batch API was designed to be extensible, to minimize the number of API functions, to be uniform, and to keep the number of arguments to a minimum.

Chapter 9 contains examples of how to perform common tasks using RE Batch API.

Appendix B contains a complete example of RE Batch API usage.

RE Batch API classes and methods are described in detail in the Javadoc in the OracleAS Personalization section of the Oracle Application Server 10g Documentation Library

Note: RE Batch API is installed on the system where Oracle Application Server is installed.

6.1 RE Batch API Prerequisites

Before you can use RE Batch API methods, OracleAS Personalization must be installed and the appropriate tables must be created and populated. Your database tables must be converted to the OracleAS Personalization schemas. It is important that the OracleAS Personalization MTR is populated with customer profiles. You should also create tables or views containing the customer IDs for which you want recommendations.

If you are using one or more taxonomies, they must be properly specified.

At least one OracleAS Personalization package must have been built and deployed. Use the OracleAS Personalization administrative interface to do this. For an example of how to create and deploy a package, see Oracle Application Server Personalization User's Guide.

Note: Do not deploy a package while an RE Batch call is in progress; do not start an RE Batch call while a deployment is in progress. Either of these activities causes an exception.

6.2 RE Batch API Definitions and Concepts

This section describes the collections of methods that make up the RE Batch API and concepts and terms used in the description of the API.

6.2.1 RE Batch API End Users (Customers)

End users (users of a Web site that uses OracleAS Personalization for recommendations) are divided into two groups: customers and visitors. A customer is a registered user, who can be identified by a unique customer ID assigned by the Web application. The RE Batch API makes recommendations for customers only.

6.2.2 RE Batch API Recommendations

Recommendations are based on historical data, which is stored in the database and retrieved when the customer profiles are loaded.

6.3 Using RE Batch API

Before you execute an RE Batch program, you must

• Set up the OracleAS Personalization environment (create an RE, and create and deploy an OracleAS Personalization package)

• Create the tables used by the RE Batch methods

6.3.1 Setting Up the RE Batch API Environment

Before you can execute RE Batch API methods, the following must be true:

• Properly formatted customer profile data must be available in the Mining Table Repository (MTR)

• A recommendation engine (RE) farm containing at least one recommendation engine must exist.

• A package must have been successfully built and then deployed in the recommendation engine farm.

The Oracle Application Server Personalization Administrator's Guide and the online help for the OracleAS Personalization Administrative GUI explain how to perform these steps.

6.3.1.1 Customer Profile Data

Customer profile data resides in the MTR.

6.3.1.2 Deploy a Package to an RE

You cannot get recommendations until there is an existing deployed package, which is created using the OracleAS Personalization administrative interface. You must build a package before you deploy it. You cannot build a package until there is some data available; data is converted from existing data collected by your Web application and stored in an Oracle database.

When you design an OracleAS Personalization application, you must decide if there should be more than one RE and, if there are several REs, how to use them. We recommend that the REs used for bulk recommendations not be used for any other purpose. For a discussion of the design considerations, see Section 9.2, "Recommendation Engine Usage" in Chapter 9.

Note: If you try to deploy a package to an RE while a batch program is running, the deployment will fail.

Recommendations may want to take income level (salary) into consideration; for example, you may want to recommend items that the user can afford to buy. If the items that are recommended have prices in several currencies (for example, items are sold in Japan and India), see Section 5.8, "Handling Multiple Currencies".

6.3.2 Sample RE Batch API Usage

OracleAS Personalization includes a sample Java program that illustrates the use of many of the RE Batch API methods; the program is in Appendix B. There are also some examples of how to perform typical tasks in Chapter 9.

6.3.3 Creating an REBatchProxy Object

Before you can use any of the RE Batch API methods, you must create at least one REBatchProxy object; see Chapter 9 for details. The object establishes a JDBC connection to a specified database and schema. The connection exists until it is explicitly destroyed.

6.3.4 Creating Instances of RE Batch API Objects

To use the API, you must create instances of the objects used by the API method signatures. Use the RE Batch API supporting classes, described in Chapter 8, to create these instances. It is always necessary, for example to create filtering settings and tuning sessions. For examples, see Chapter 9.

6.3.5 Converting Data for RE Batch API

OracleAS Personalization generates recommendations based on data describing past user behavior.

User data stored in an Oracle table must be transformed and stored in the Mining Table Repository (MTR) before it can be used to generate recommendations.

6.3.6 Managing Customer Profiles for RE Batch API

OracleAS Personalization stores customer profiles in the Mining Table Repository (MTR). The profiles to be used must be loaded into an RE before any recommendation requests are made. The following methods manage load and unload customer profiles from an RE:

• loadCustomerProfiles()

• purgeCustomerProfiles()

Before you load a set of customer profiles, you must create a table or a view containing a list of the customer IDs that identify the profiles that you wish to load, that is, a list of the customer IDs for which you want a recommendation.

6.3.7 Getting RE API Batch Recommendations

To get a recommendation, the application calls one of the following recommendation methods:

• crossSellForItem()

• rateItem()

• recommendTopItems()

These methods are used for getting recommendations for customers (registered users).

6.3.7.1 Ratings in OracleAS Personalization

Ratings in OracleAS Personalization are in "ascending order of goodness", that is, the higher the rating, the more the user prefers the item. Low-rated items are items that the user does not prefer. OracleAS Personalization algorithms use these assumptions, so it is important that ratings are in ascending order of goodness.

6.3.7.2 Creating Recommendations

OracleAS Personalization uses rule tables stored in the RE to calculate the recommendations requested by the methods listed above. The specific rule table used depends upon the RE Batch API method used. In general, the antecedents of the rules are matched against the historical data and the probabilities of the various consequents are computed. These items are then ordered by probability, and numberOfItems (an API argument) items are returned. The recommendations are written to a database table.

If there is enough memory in the RE database, the RE caches all rules associated with a particular package deployed from the MTR to the RE, not just the most recent rules.

Scoring:

For scoring, all available historical data is used.

The OracleAS Personalization Mining Table Repository (MTR) contains historical rating, transactional data, and navigational data stored in both detailed and aggregated formats. The MTR also contains demographic data. When scoring for customers, the RE retrieves the demographic data and the aggregated version of the other data source types.

6.3.8 Making RE Batch Recommendations

RE Batch API methods that make recommendations write the recommendations to a database table. The schema used for the output depends on the method used. You can extract the recommendations in many ways, for example, with an appropriate SQL query, and then decide which recommendations to pass to the user.

6.3.9 Removing the REBatchProxy Object

Before you exit the application, you should destroy any proxy objects that you no longer need.