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 OracleAS Personalization was installed correctly by using the REAPI to get recommendations. To run REAPI Demo, OracleAS Personalization 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 OracleAS Personalization).
You can experiment with the configuration so that you can learn how best to configure RE to suit your Web site.
You can familiarize yourself with OracleAS Personalization'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 the 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 Oracle Application Server Personalization Programmer's Guide.

For details about installing REAPI, see the Oracle 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 Oracle Application Server is installed.

3.1 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 OracleAS Personalization, choose the option to install the demo data into the MTR.

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

Create a movies MTR connection, using the sample movies MTR database supplied with OracleAS Personalization.
Create a package using the movies MTR connection created in step 1.
Create a recommendation engine farm (RE Farm) with one recommendation engine (RE).
Build a package.
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.

3.2 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 Oracle Application Server is installed. This will bring up the REAPI Demo user interface. The first page that appears is the Welcome to OP REAPI Demo page.

3.2.1 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 Section 3.3.2.

3.2.2 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 of 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.

3.3 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 stateful exercise
A stateless exercise
Changing a visitor to a customer

3.3.1 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 OracleAS Personalization.

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

3.3.2 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 OracleAS Personalization installation for host, port, and SID.
User name: The user name for the database. Enter the RE user name that was specified during OracleAS Personalization installation.
Password: The password for the RE user. Enter the password that was specified during OracleAS Personalization 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.)

3.3.3 Exercise 2: A Stateful 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 stateful Web application.)

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

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.
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.

OracleAS Personalization then returns 10 or fewer recommendations for the user of this session. It will look something like Table 3-1, 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):

Table 3-1 Recommended Top N Items for User ID = 1

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

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.
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.
OracleAS Personalization then returns 10 or fewer recommendations for the user of this session. In this case, it returns something like what is shown in Table 3-2. Again, it displays the item type (MOVIE), the item ID (a number identifying each movie), and the rating.

Table 3-2 Recommended Hotpick Items for User ID = 1

Type	Item ID	Rating
MOVIE	360	1.000
MOVIE	370	2.000
MOVIE	116	3.000
MOVIE	83	4.000
MOVIE	18	5.000
MOVIE	20	6.000

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:

Table 3-3 Rate Items for User ID = 1

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

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.

3.3.4 Exercise 3: A Stateless 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.

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.

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

Table 3-4 Cross-Sell for Items for Hot Picks for User ID = 1

Type	Item ID	Rating
MOVIE	72	1.2785

3.3.5 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.

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.
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.

3.4 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.