5 Configuring OracleAS Personalization

After you have installed OracleAS Personalization and verified that the installation is correct, you can specify certain configuration parameters for OracleAS Personalization.

This chapter

lists the external OracleAS Personalization configuration parameters and their default values
indicates the parameters that you can change and tells you how to change them
describes RE configuration and data synchronization and how to configure it
describes how to determine appropriate parameter values for your installation

All OracleAS Personalization configuration parameters reside on the system where Oracle is installed.

5.1 Configuring the OracleAS Personalization Scheduler

OracleAS Personalization allows users to schedule package builds, deployments, and reports. The OracleAS Personalization administrator can also specify that certain users get an email notification when a build, deploy, or report completes. The following configuration parameters in the MOR configuration table control scheduling and notification:

The values for NLS_LANGUAGE and NLS_TERRITORY determine the languages used for the email notifications.
The MAIL_PREFERENCE parameter specifies the formatting of email notifications, either plain text or HTML format. The default is MAILHTML, indicating HTML formatting.
The ADMIN_EMAIL_ADDRESS parameter specifies the email address of the OracleAS Personalization administrator. This address is used as the "return" address for email notifications. For example, if a user of the OracleAS Personalization Administrative UI enters an incorrect email address for notification, ADMIN_EMAIL_ADDRESS indicates the address used for warning about the incorrect information.

The default value of NAME - ADMIN_EMAIL_ADDRESS is the string Oracle.Personalization@oracle.com. Change this value when you install OracleAS Personalization.

5.2 Changing OracleAS Personalization Configuration Parameters

These parameters are divided into three categories:

Values that are changed using SQL Plus, indicated by Y in the Change column in the summary tables.
Values that you should not change, indicated by N in the Change column in the summary tables.
Values that are changed using the OracleAS Personalization Administration UI, indicated by UI in the Change column in the summary tables.

5.2.1 RE Configuration Parameters

Table 5-1 lists the RE configuration parameters, their data types, their default values, and a description for each. These parameters can be found in the RE_CONFIGURATION table.

Table 5-1 Recommendation Engine Configuration Parameters

Parameter Name	Data Type	Default Value	Description	Change
LOG_LEVEL	int	2	0=OFF, 1=INTERNAL ERROR plus Error and Warning, 2=All errors logged for 1 plus notifications, 3=All errors logged for 2 plus trace	Y
RE_TRACE	int	0	0=OFF, 1=LOW (detail), 2=MODERATE, 3=HIGH	Y
REAPIRT_TRACE	int	0	0=OFF, 1=LOW (detail), 2=MODERATE, 3=HIGH	Y
REAPIDEMO_TRACE	int	0	0=OFF, 1=LOW (detail), 2=MODERATE, 3=HIGH	Y
UTIL_TRACE	int	0	0=OFF, 1=LOW (detail), 2=MODERATE, 3=HIGH	Y
REAPIBATCH_TRACE	int	0	0=OFF, 1=LOW (detail), 2=MODERATE, 3=HIGH	Y
TimeoutInterval	int	1800	Session timeout interval (in seconds)	UI
TimeoutFlag	int	1	Session timeout indicator (1=TRUE, 0=FALSE)	UI
DataSyncInterval	int	1800	Interval on which to synchronize customer data (in seconds)	UI
SyncCustomerNavigationalData	int	0	Is customer navigational data synchronized (boolean)	N
SyncCustomerRatingData	int	0	Is customer rating data synchronized (boolean)	N
SyncVisitorNavigationalData	int	0	Is visitor navigational data synchronized (boolean)	N
SyncVisitorRatingData	int	0	Is visitor rating data synchronized (boolean)	N
SyncPurchasingData	int	0	Is customer purchasing data synchronized (boolean)	N
SyncDemographicData	int	0	Is customer demographic data synchronized (boolean)	N
ConnectionPoolSize	int	128	Java connection pool limit per proxy.	Y^{(Requires restart of Oracle AS Personalization})

5.2.2 MOR Configuration Parameters

Table 5-2 describes the configuration parameters for the OracleAS Personalization Mining Object Repository (MOR). The table shows their data types, their default values, and provides a description for each. These parameters can be found in the MOR_CONFIGURATION table.

If the value in the Change column is "N," do not change the parameter. If the value in this column is "Y," the value of the parameter must be changed to a value suitable for your environment. The description of these parameters includes the instruction "change value on install."

Table 5-2 MOR Configuration Parameters

Parameter	Data Type	Value	Description	Change
MOR_USERNAME	string	<username>	User name for Admin UI; change value on install	N
MOR_PASSWORD	string	<password>	Password for Admin UI; change value on install	N
MOR_DBALIAS	string	<alias>	Alias for the MOR database; change value on install	N
MOR_SCHEMA	string	< schema>	MOR schema name	N
MOR_HOST_URL	string	<hostname>	MOR hostname; change value on install	N
MOR_PORT	string	<port>	MOR port; change value on install	N
MOR_SID	string	<sid>	MOR system ID; change value on install	N
MOR_VERSION	string	9.0.4	MOR version number	N
scheduleItemGracePeriod	int	60	Number of minutes a scheduled item must have been past due for it to cause an error	Y
buildEvents	int	20	Maximum number of events of this type to keep in log	UI
MAXNUMPUCHASEINGSESS	int	20	The maximum number of purchasing sessions reports to keep per recommendation engine farm
MAXNUMRECEFFREP	int	20	The maximum number of recommendation effectiveness reports to keep per recommendation engine farm
MAXNUMITEMIZEDRECEFFREP	int	20	The maximum number of itemized recommendation effectiveness reports to keep per recommendation engine farm
NUMOFITEMSINITEMIZEDRECEFFREPORT	int	20	The number of top-ranked items in itemized recommendation effectiveness reports
IAS_HOSTNAME	string		Parameter used by report workflow to construct a URL for email notification
IAS_SERVLET	string		Parameter used by report workflow to construct a URL for email notification
IAS_SERVLET_ZONE	string		Parameter used by report workflow to construct a URL for email notification
IAS_PORT	string		Parameter used by report workflow to construct a URL for email notification
IAS_SERVLET_MOR_CONN	string		Parameter used by report workflow to construct a URL for email notification
LOG_FILE	string	morlog.txt	Log file name
deployEvents	int	20	Maximum number of events of this type to keep in log	UI
reportEvents	int	20	Maximum number of events of this type to keep in log	UI
LOG_LEVEL	int	2		Y
ALGS_TRACE	int	0	0=OFF, 1=LOW (detail), 2=MODERATE, 3=HIGH	Y
DMAPI_TRACE	int	0	0=OFF, 1=LOW (detail), 2=MODERATE, 3=HIGH	Y
PAR_TRACE	int	0	0=OFF, 1=LOW (detail), 2=MODERATE, 3=HIGH	Y
TNB_TRACE	int	0	0=OFF, 1=LOW (detail), 2=MODERATE, 3=HIGH	Y
UI_TRACE	int	0	0=OFF, 1=LOW (detail), 2=MODERATE, 3=HIGH	Y
UTIL_TRACE	int	0	0=OFF, 1=LOW (detail), 2=MODERATE, 3=HIGH	Y
WFJAVA_TRACE	int	0	0=OFF, 1=LOW (detail), 2=MODERATE, 3=HIGH	Y
MAIL_PREFERENCE^Foot 1	string	MAILHTML	Format for email notifications; other possible value is MAILTEXT	Y
NLS_LANGUAGE^Foot 2	string		Supported values: AMERICAN, FRENCH, GERMAN, ITALIAN, SPANISH, BRAZILIAN PORTUGUESE, JAPANESE, KOREAN, SIMPLIFIED CHINESE	Y
NLS_TERRITORY^Foot 3	string		Supported values: AMERICA, FRANCE, GERMANY, ITALY, SPAIN, BRAZIL, JAPAN, KOREA, CHINA	Y
ADMIN_EMAIL_ADDRESS	string	Oracle. Personal- ization@oracle.com	Email address of the Oracle Personalization administrator for email notifications	Y

^Footnote 1The email notifications sent by OracleAS Personalization support either plain text or HTML format. The default setting in the MOR configuration table is MAILHTML, indicating HTML format. If the incoming mail server that you are using supports only plain text, set this parameter to MAILTEXT.
^Footnote 2The default value for NLS_LANGUAGE after OracleAS Personalization installation is that this is empty (blank). However, if it is edited, OracleAS Personalization verifies that the value is supported and uses it instead of the database default language for the server code (it does not affect PL/SQL messages however). If it is not specified, the database default language is used. If neither these values nor the database default indicates one of the supported languages, OracleAS Personalization defaults to AMERICAN. This value also specifies the language used for email notifications.
^Footnote 3The default value for NLS_TERRITORY after OracleAS Personalization installation is that this is empty (blank). However, if it is edited, OracleAS Personalization verifies that the value is supported and uses it instead of the database default language for the server code (it does not affect PL/SQL messages however). If it is not specified, the database default language is used. If neither these values nor the database default indicates one of the supported languages, OracleAS Personalization defaults to AMERICA. This value specifies also specifies the language used for email notifications.THIS WAS FOOTNOTE # 1 (to browserToBuyerConvetsion, now conditionalized): The parameter name "browserToBuyer" was changed temporarily to "visitorToCustomer"; the two terms mean the same thing, and both terms appear in different parts of the code. The report title for this data is "Purchasing Session Report."THIS WAS FOOTNOTE #2 (to mostActiveCrossSellProducts, now conditionalized): The report title for this data is "Itemized Recommendation Effectiveness Report."

5.2.3 MTR Configuration Parameters

Table 5-3 describes the configuration parameters for the OracleAS Personalization Mining Table Repository (MTR). The table shows their data types, their default values, and a description for each. These parameters can be found in the MTR_CONFIGURATION table in MTR schema.

These parameters allow selecting different types of data to be synchronized to the MTR. At the end of an OracleAS Personalization session, MTR synchronization adds data collected in the RE (during the session) to the data already stored in the MTR. In order for data synchronization to take place, the MTR must be configured to allow the various types of data to be synchronized.

Table 5-3 MTR Configuration Parameters^Foot 1

Parameter	Data Type	Value	Description	Change
ALLOW_SYNC_DEMOGRAPHIC	boolean	T	Allows demographic data to be synchronized to MTR	Y
ALLOW_SYNC_NAVIGATION	boolean	T	Allows navigational data to be synchronized to MTR	Y
ALLOW_SYNC_PURCHASING	boolean	T	Allows purchasing data to be synchronized to MTR	Y
ALLOW_SYNC_RATING	boolean	T	Allows rating data to be synchronized to MTR	Y
ALLOW_MTR_SYNC_VISITOR_NAVIGATION	boolean	T	Allows visitor navigation data to be synchronized to MTR	Y
ALLOW_SYNC_VISITOR_RATING	boolean	T	Allows visitor rating data to be synchronized to MTR	Y

^Footnote 1Change these values only when the MTR is not being used.

5.3 RE Installation and Configuration

Installation and configuration of a recommendation engine (RE) must be tailored to the expected number of active users that it will support. The RE in this context refers to a single engine in a single Recommendation Engine Farm on a single database instance. If multiple engines in one or more RE farms are installed on the same database instance, the configuration parameters require adjustment.

5.3.1 RE Optimization

Many factors go into the optimization of an RE. Some of these are set by the installation procedure, while others are techniques that may be used by the DBA. Configuration options fall into two broad categories:

System availability settings
Performance settings

System availability settings are those settings required by the RE to handle user load without failure. Performance settings are those settings that help maximize throughput.

System Availability

The system availability settings for RE configuration depend on the number of anticipated users. If you know the number of users, it is possible to estimate the approximate system resource requirements and make database configuration recommendations. Since the REAPI maintains a connection pool of user connections, which can be reused, the number of required connections depends on how well user requests are being satisfied by the RE. That is, if for some reason there is a slowdown in the RE causing connection links to be held longer in the REAPI connection pool, the number of connections will tend to increase. As the number of connections increases, the number of actual database sessions increases. Each connection in the REAPI connection pool represents a database session.

The maximum number of connections in the REAPI connection pool is a configurable parameter in each RE. If this limit is exceeded, it may indicate that there are performance issues that need to be addressed other than simply increasing the size of the connection pool.

Each application user's client session results in database activity in the RE schema. First, configure the database to handle the number of anticipated simultaneous users. Depending on the amount of available memory and CPUs in the system the RE database is installed on, it may be possible to support 50-100 users in a dedicated server environment. In this environment, each user connection to the database would require its own dedicated Oracle server for database access. As the number of users extends beyond 100, it may be more appropriate to use Oracle's Multi-Threaded Server environment where database connections are pooled and serviced by shared database servers. The DBA responsible for the RE must decide whether the dedicated or shared server environment is used.

Performance

REAPI performance may be affected by several factors. On the client side, the REAPI runs in the JServer environment. Sufficient memory and CPU must be available to the client to handle the throughput for the active users. Communication with the RE from the REAPI clients is implemented through JDBC connections over Oracle's SQL*Net network. As the number of users grows, so does the demand on the network.

5.3.2 Required RE Parameters

The recommendation engine requires certain database parameters to be set to a minimum value, as follows:

JOB_QUEUE_PROCESSES=2

5.3.3 Suggested RE Database Parameters (All Load Levels)

The parameters and values listed below, while not necessary, are strongly recommended:

BUFFER_POOL_KEEP (50 buffers) SORT_AREA_SIZE (819200 bytes) SORT_AREA_RETAINED_SIZE (819200 bytes)

5.3.4 Suggested RE Database Parameters (Variable Load Level)

Table 5-4 suggests guidelines for database configuration parameters based on number of projected users. The table shows, for a specified number of users, whether multi-threaded servers (MTS) are recommended, and recommended values for the number of MTS dispatchers, shared MTS servers, sessions, the size of large pool, and the size of shared pool:

Table 5-4 Suggested RE Database Parameters (Variable Load Level)

Users	MTS	MTS Dispatchers	MTS Shared Servers	Sessions	Large Pool	Shared Pool
100	No	N/A	N/A	100	Default	Default
1000	Yes	4	20	300	250M	100M
2000	Yes	8	30	600	500M	120M
3000	Yes	10	40	900	1000M	140M
4000	Yes	12	50	1200	1500M	160M

5.3.5 Suggested RE Configuration Parameters

The table settings in Table 5-5 are based on the number of estimated simultaneous sessions. These parameters are set in the RE schema table RE_CONFIGURATION. The table shows, for a specified number of simultaneous sessions, the recommended connection pool size and data synchronization interval:

Table 5-5 Suggested RE Configuration Parameters

Sessions	Connection Pool Size (number of connections)	Data Synchronization Interval (in seconds)
100	128	300
1000	256	300
2000	512	300
3000	1024	180
4000	2048	180

5.4 MTR Installation and Configuration

The Mining Table Repository (MTR) database holds customer (demographic, purchasing, ratings, navigational data) and product data. Predictive models are built based on this data. Any data collected in the RE will be copied to the MTR at scheduled intervals. Customer profile data is also copied from the MTR into the RE when a customer begins a user session. All data transfer between the MTR and the RE is done using database links.

Table 5-6 offers guidelines for database configuration parameters based on the number of projected users. The table shows, for a specified number of users, whether multi-threaded servers (MTS) are recommended, and recommended values for the number of MTS dispatchers, the number of MTS servers, the number of sessions, and the size of the large pool:

Table 5-6 Suggested Database Configuration Parameters

Users	MTS	MTS Dispatchers	MTS Servers	Database Sessions	Large Pool
100	No	N/A	N/A	100	Default
1000	Yes	2	10	100	25M
2000	Yes	3	20	200	50M
3000	Yes	4	20	300	100M
4000	Yes	50	30	400	150M

5.5 Data Synchronization

Data synchronization moves user-specific data that is collected in the RE during a session to permanent storage, that is, to the appropriate table in the mining table repository (MTR). Session and recommendation data are always synchronized; other kinds of data are synchronized according to the way the RE Farm and MTR are configured. See "Data to Synchronize", later in this chapter, for configuration instructions. Customer data and visitor data are copied to the appropriate MTR tables. (There is one set of MTR tables for customer data and a different set for visitor data.)

Data is synchronized every DataSyncInterval, which is a configuration parameter that is specified for an RE Farm. Data synchronization is performed only for users whose sessions are inactive. A session is inactive if there has been no activity for a specified period of time or if the session has been explicitly closed. Note that a user can have more than one session at any time. A customer ID is deleted from RE_PROFILE_DATA only when all the customer's sessions are inactive.

After the data is copied to the MTR, the data is purged (deleted) from the RE tables. Data that cannot be synchronized for some reason (for example, data that has an invalid item ID) is also purged.

Data is collected in the RE_CURRENT_SESSION_DATA table and the RE_RECOMMENDATION_DETAIL table. The data source type of the data determines the MTR table to which data is copied.

Table 5-7 shows the four data source types and the MTR table for each.

Table 5-7 Data Synchronization for RE_CURRENT_SESSION_DATA

DATA_SOURCE_TYPE	MTR Table
1 (demographic) for customers only	`MTR_CUSTOMER`
2 (purchasing) for customers only	`MTR_PURCHASING_DETAIL`
3 (rating) for visitors and customers	`MTR_RATING_DETAIL`
4 (navigational) for visitors and customers	`MTR_NAVIGATIONAL_DATA`

RE_RECOMMENDATION_DETAIL data is copied to the MTR_RECOMMENDATION_DETAIL table and appropriate RE_ACTIVE_USER data is copied to MTR_SESSION table. RE_PROFILE_DATA is updated in the MTR_CUSTOMER table.

5.5.1 Configuring Data Synchronization

You specify two things: the synchronization interval for a Farm, and exactly what data to synchronized for a specific MTR connection:

Synchronization Interval

In the Farms tab of the Administrative UI, select a farm, select Edit, and then click the Advanced Settings button. Specify an appropriate data synchronization interval for the selected farm. (You can also specify the timeout interval here.)

The default synchronization interval is 300 seconds (5 minutes). The synchronization interval should be adjusted for the number of users of the application. If there are many users and the synchronization interval is long, the REs will fill with data.

Data to Synchronize

In order for data synchronization to take place, the MTR must allow that type of data to be synchronized. These rules are specified when you install OracleAS Personalization.

You configure the MTR connection using the OracleAS Personalization Administrative UI. At the top of the Farms tab, click Options, click MTR database connections, click Edit, and finally click the Sync settings button. The synchronization settings for this MTR are displayed. To change a setting click the appropriate checkbox.

The types of data that are allowed to be synchronized are indicated by a checkmark in the corresponding checkbox. If a selection is greyed out, the configuration of the MTR does not allow synchronization of that type of data.

By default, all four types of data are left unchecked, that is, no data is synchronized. You can choose to allow synchronization of any type of data for which the MTR allows synchronization. Any changes apply only to the current MTR connection.