3
Using the REAPI Demo

This chapter presents several exercises using the REAPI Demo.

Running the REAPI Demo accomplishes the following:

• You can verify that OP was installed correctly by using the REAPI to get recommendations. To run REAPI Demo, OP must be installed properly and the REAPI Demo must be configured to access RE. The demo data must also be loaded into the MTR.

• To follow the exercises in this chapter, you need to have installed a populated MTR (installed if you selected "Install demo data" when you installed OP).

• You can experiment with configuration so that you can learn how best to configure RE to suit your Web site.

• You can familiarize yourself with OP's Java operations and see how the calls work and how they interact.

• You can view the source code to see how the program uses the REAPI calls.

  Note: When you are finished using REAPI demo, you should remove the accounts associated with it. Leaving the accounts can result in security problems.

For detailed information about the REAPI, see the Oracle9iAS Personalization Recommendation Engine API Programmer's Guide.

For details about installing REAPI, see the Oracle9i Application Server Administrator's Guide.

In a production environment, the REAPI calls are used to "instrument" a Web site so that you can collect the data needed to create good models and generate recommendations.

The REAPI and the REAPI Demo are installed on the system where Oracle9iAS is installed.

Before Running REAPI Demo

Before running the REAPI Demo, you need to have created and deployed a package to the recommendation engine so that there is data available for making recommendations.

When you install OP, choose the option to install the demo data into the MTR.

Next, use the OP Administrative UI (described in Chapter 2) to perform the following steps:

1. Create a movies MTR connection, using the sample movies MTR database supplied with OP.

2. Create a package using the movies MTR connection created in step 1.

3. Create a recommendation engine farm (RE Farm) with one recommendation engine (RE).

4. Build a package.

5. Deploy the movies package to the farm created in step 3.

After the movies package is successfully deployed to the RE Farm, you can begin experimenting with the REAPI demo to see how the REAPI calls work.

Start REAPI Demo

When you are ready to begin working with the REAPI Demo, point your browser to the following URL:

   http://<hostname>/OP/redemo/

where <hostname> is the name of the system on which Oracle9iAS is installed. This will bring up the REAPI Demo user interface. The first page that appears is the Welcome to OP REAPI Demo page.

Proxies

REAPI calls execute in the context of a proxy, which specifies the environment in which the calls execute. One of the important elements of the environment is the default RE schema. You must create a proxy before you execute any calls, as shown in the steps outlined below.

View Source Code

While you are running the REAPI Demo, you can view the source code for the demo by clicking the View Source Code link.

REAPI Demo is implemented as a Java servlet consisting the following classes:

• REDemoServlet.java

• REUtil.java

• REDemoException.java

• REDemoConstants.java

You can view the source code for each of these classes; you can also download the classes to your desktop.

Exercises

This section provides exercises that you can work through to get a feel for how the REAPI Demo works. The exercises cover the following tasks:

• Creating a proxy

• Collecting data

• Making recommendations

• A sessionful exercise

• A sessionless exercise

• Changing a visitor to a customer

Values and Results

To get meaningful results from these examples, you must enter valid values (that is, values for which there are recommendations) to REAPI Demo. All the values in this demo produce useful results. You can determine other values by examining the populated MTR provided with OP.

The results returned when you execute the calls will be similar to but not identical to the results displayed in this document.

Exercise 1: Creating a Proxy

You must create a proxy before you execute any calls. Here's how: In the frame on the left of the REAPI Demo screen, click createProxy, and enter these values:

• RE Name: The name of the recommendation engine schema that you will use.

• JDBC URL: jdbc:oracle:thin:<host>:<port>:<sid> Enter the values that were specified during OP installation for host, port, and SID.

• User name: The user name for the database. Enter the RE user name that was specified during OP installation.

• Password: The password for the RE user. Enter the password that was specified during OP installation.

• Cache Size: 3242 KB (default).

• Archive Interval: 10,000 milliseconds (default).

Click Create RE Proxy.

REAPI Demo displays a message indicating success or failure. (REAPI Demo does this for every action.)

Exercise 2: A Sessionful Web Application

Follow these steps to experiment with any of the methods listed under the heading "Sessionful." (These are the methods that are valid with a sessionful Web application.)

A sessionful Web application starts a session for each customer when the customer logs in to the site.

1. To create a session, specify a customer ID and a session ID. At the left, under Sessionful, click createSession to bring up the Create RE Session page, and enter these values:
   • User Type: Customer

   • User ID: 1

   • App Session ID: 1011 (You must enter a unique number; this number cannot be used more than once.)

   Click Create Session.

2. You can now execute any of the methods listed under Sessionful, for example, to obtain recommendations. To do this, click recommendTopN to bring up the Recommend Top Items page, and enter these values:
   • Number of recommendations to display: 10

   • Tuning Settings
     • Data Source Type: PURCHASING

     • Interest Dimension: PURCHASING

     • Personalization Index Type: LOW

     • Profile Data Balance: CURRENT

     • Profile Usage: INCLUDE

   • Filtering Settings
     • Filtering Type: All Items

     • Taxonomy ID: 1

     • Select Categories: For Include items, you can highlight any individual items, or, if you set Filtering Type to All Items, you do not need to highlight any items or categories.

   • Recommendation Content
     • Sorting order for Prediction: ASCEND

     • Sorting order for Type: NONE

     • Sorting order for ID: NONE

     Click Recommend Top N.

   OP then returns 10 or fewer recommendations for the user of this session. It will look something like the table below, which displays information for four movies. It displays the item type (MOVIE, for each), the item ID (a unique number for each item), and the ranking of the four movies, ranked on the likelihood of being purchased):

   Recommended Top N Items for User ID = 1

   Type	Item ID	Rating
   MOVIE	345	1.000
   MOVIE	383	2.000
   MOVIE	447	3.000
   MOVIE	223	4.000

3. You can collect data while a session is running. To add data, click addItems to bring up the Add Items page, and enter these values
   • Data source Type: RATING

   • Item Type: MOVIE

   • Item ID: 122

   • Value: 5 (Rating on a scale from 1 to 5.)

   Click Add>> to move this item to the list; click Add Items to add it to the RE. This updates the information in the RE tables for this user.

4. Next, try Hot Picks. Hot picks are used by some Web sites; for example, daily specials might be in a Hot Picks Group. Click recommendHotPicks to bring up the Recommend from Hot Picks page, and enter these values:
   • # of Recommended Items: 10

   • Hot Pick Group: COMEDY

   • Tuning Settings
     • Data Source Type: NAVIGATION

     • Interest Dimension: NAVIGATION

     • Personalization Index Type: LOW

     • Profile Data Balance: HISTORY

     • Profile Usage: INCLUDE

   • Filtering Settings
     • Filtering Type: Exclude Items

     • Taxonomy ID: 1

     • Select Categories: For Exclude items, you do not need to select here.

   • Recommendation Content
     • Sorting order for Prediction: ASCEND

     • Sorting order for Type: NONE

     • Sorting order for ID: NONE

     Click Recommend Hot Picks.

   OP then returns 10 or fewer recommendations for the user of this session. In this case, it returns something like what is shown in the table below. Again, it displays the item type (MOVIE), the item ID (a number identifying each movie), and the rating.

   Recommended Hotpick Items for User ID = 1

   Type	Item ID	Rating
   MOVIE	360	1.0000
   MOVIE	370	2.0000
   MOVIE	116	3.0000
   MOVIE	83	4.0000
   MOVIE	28	5.0000
   MOVIE	20	6.0000

5. You can also rate items with respect to the current user, that is, determine how the current user will rate items. Click rateItems to bring up the Rate Items page, and enter these values:
   • Taxonomy ID: 1

   • Tuning Settings
     • Data Source Type: RATING

     • Interest Dimension: RATING

     • Personalization Index Type: MEDIUM

     • Profile Data Balance: HISTORY

     • Profile Usage: INCLUDE

   • Recommendation Content
     • Sorting order for Prediction: ASCEND

     • Sorting order for Type: NONE

     • Sorting order for ID: NONE

   • Items
     • Item Type: MOVIE

     • Item ID: 72

     Click Add>> to add this item to the list. You can add other items to the list, if you wish.

     • Similarly, add "Movie, 122" and "Movie, 287".

     • When you are finished adding items, click Rate Items.

   REAPI Demo returns the following:

   Rate Items for User ID = 1

   Type	Item ID	Rating
   MOVIE	72	4.3071
   MOVIE	287	4.3453
   MOVIE	122	4.3569

6. When you have finished experimenting, close the session. (REAPI sessions that are not explicitly closed eventually time out; it is a good practice, however, to close them explicitly.) Close the session by clicking closeSession, which brings up the Close the Current Session page. Click the Close Session button.

Exercise 3: A Sessionless Web Application

If your Web site does not start a session for each visitor or customer, you use the calls listed under Sessionless. For each of these calls, you provide the identification data for user and session. Otherwise, the calls are identical to sessionful ones. This example illustrates several sessionless calls.

1. If a customer buys an item, you may want to offer the customer a similar or related item, that is, a cross-sell item. To create cross-sell recommendations for an item from the HORROR hot picks group, click Cross-SellFromHotpicks in the left frame under Sessionless. The Cross-Sell for Items from Hot Picks page is displayed.
   • Number of recommendations to display: 10
     • Hot Pick Group: HORROR

   • User Details
     • User Type: Customer

     • User ID: 1

   • Tuning Settings
     • Data Source Type: NAVIGATION

     • Interest Dimension: NAVIGATION

     • Personalization Index Type: MEDIUM

     • Profile Data Balance: CURRENT

     • Profile Usage: INCLUDE

   • Filtering Settings
     • Filtering Type: Exclude Items

     • Taxonomy ID: 1

     • Select Categories: Select items you want to exclude or select none.

   • Recommendation Content
     • Sorting order for Prediction: ASCEND

     • Sorting order for Type: NONE

     • Sorting order for ID: NONE

   • Items
     • Item Type: MOVIE

     • Item ID: 199

     Click Add>> to add this item to the list. Similarly, add MOVIE 354 and MOVIE 122 to the list.

When you have finished adding items, click Cross-Sell for Items from Hot Picks.

OP then returns 10 or fewer recommendations for the user of this session. In this case, it returns the following:

Cross-Sell for Items for Hot Picks for User ID = 1

Type	Item ID	Rating
MOVIE	72	1.2785

Exercise 4: Change Visitor to Customer

If a visitor registers as a user during a session, you need to change the visitor to a customer. You can only change a visitor to a customer during a session that the user entered as a visitor.

1. To create a session using the default proxy, you specify a visitor ID and a session ID. At the left, under Sessionful, click createSession to bring up the Create RE Session page, and enter these values:
   • User Type: Visitor

   • User ID: 100

   • App Session ID: 1015

     Note that App Session ID value must refer to a session that does not already exist.

2. Now you can change the visitor to a customer. At the left, under Sessionful, click setVisitorToCustomer to bring up the Set Visitor to Customer page. Click Set Visitor to Customer.

   REAPI Demo displays a message that announces SUCCESS!

You can close the session now or continue experimenting, as you like.

Summary

This chapter has presented exercises to show you how the REAPI works.

The Demo is different from the way you would use the REAPI calls in practice. In practice, you would embed the REAPI calls in a Java program that you write, and you would execute the program as you ordinarily do.