| Oracle® Real-Time Decisions Base Application Installation and Reference Guide Release 3.1 Part Number E19020-01 |
|
|
View PDF |
| Oracle® Real-Time Decisions Base Application Installation and Reference Guide Release 3.1 Part Number E19020-01 |
|
|
View PDF |
This chapter describes the elements in and associated with the CrossSellBatch Inline Service. It contains the following topics:
The CrossSellBatch Inline Service is a technical example of the use of the batch framework that is released with the Oracle RTD platform. It is based on the Cross Sell example Inline Service that is released with Oracle RTD. Refer to Oracle Real-Time Decisions Installation and Administration Guide and Oracle Real-Time Decisions Platform Developer's Guide for additional information on both the original Cross Sell Inline Service and the batch frame work. The CrossSellBatch Inline Serviceshould be used as a reference for developers when adding batch functionality to their own Inline Services.
In this example, batch processes have been created to support a workflow process in which Oracle RTD is used first to recommend offers to customers, and then to learn on the customer response, as follows:
One batch process reads through a list of customers and writes to an output table the best recommended offer for each customer.
The next batch process simulates the customer response to the recommended offer and then writes the result to a response table.
After this is done, a final batch process reads the response table and calls Oracle RTD to update the models with the response data.
In addition to the batch process that recommends the best offer, the CrossSellBatch Inline Service also contains an example of scoring customers against a given offer that is specified by the user.
A sample data schema and test data to be used with this example is included with the CrossSellBatch Inline Service. Setup of this data is required in order to test any of the batch processes included in this Inline Service as the batch processes rely on the created data sources.
All files for creating the database tables and loading data can be found directly in the Inline Service project folder under the /etc folder. To create the schema and populate the batch tables., you must execute the InitAppDB.cmd that is appropriate to your database type through a command line.
For example, for SQL Server, the files can be found under the path, RTD_ILS_HOME/CrossSellBatch/etc/data/SQLServer, where RTD_ILS_HOME is the directory into which the CrossSellBatch Inline Service was saved during installation.
Each InitAppDB command has the following structure:
InitAppDB sdroot host port database runtimeUser adminUser [adminPassword]
Table 8-1 describes the parameters for the InitAppDB script.
Table 8-1 Parameters for InitAppDB Script
| Parameter | Description |
|---|---|
|
|
The full path of the directory where the Oracle Real-Time Decisions files are installed. |
|
|
The name of the computer hosting the database server. If you installed your Oracle RTD Database on a SQL Server named instance, specify |
|
|
The database port number. |
|
|
The name of the database, or for Oracle Database, the SID. |
|
|
The user name of the run-time user for the system. |
|
|
The name of a user that has rights to create tables and stored procedures on the database. |
|
|
The password of the administrative user. |
Footnote 1 For Oracle Database, the runtimeUser and adminUser are the same user.
The CrossSellBatch Inline Service demonstrates a technical implementation of Oracle RTD Platform's batch framework, and provides coding for the following use case scenarios:
Batch Learning - Given a set of customer and offer data, through the batch process, call an Oracle RTD informant to process event learning of offer responses.
Batch Learning with Direct Event Recording - Given a set customer and offer data, update event models directly via java code.
Batch Offer Selection - Given a set of customer data, perform a batch advisor call to record the best offer per customer and record results to an output table.
Batch Customer Scoring - Given a specific offer, process a customer list and provide a score for that offer for each customer.
Offer Acceptance ETL - Through the batch process, demonstrate an ETL (Extract, Transform, and Load) process where simulated customer responses are recorded to an Oracle RTD table for future learning using standard JDBC java functionality.
Offer Acceptance ETL with the RTD Table Inserter - Through the batch process, demonstrate an ETL process where simulated customer responses are recorded to an Oracle RTD table for future learning using Oracle RTD Table Inserter APIs.
Each of these use cases is configured through java classes that implement the batch framework BatchJob interface, namely:
init() - Called once by the framework before starting the batch's processing loop.
getNextInput() - Returns the next input row to be processed by the batch.
executeRow() - The batch job implements this method to process the input row that was returned by getNextInput().
flushOutputs() - Called by the framework to allow the batch job to flush its output table buffers.
cleanup() - Called by the framework after the batch is finished or is being stopped. Cleans up any resources allocated by the batch job, such as the result set created by its init() method.
For full details of the methods of the BatchJob interface and execution of the batch framework, refer to the Oracle RTD Batch Framework chapter in Oracle Real-Time Decisions Platform Developer's Guide.
A separate .java file has been created for each of the batch use cases described in this section. These java files are located under the path, <RTD Studio Workspace>/CrossSellBatch/src/crosssell/batch where <RTD Studio Workspace> is the directory into which the CrossSellBatch Inline Service has been saved. The following are the .java files included:
Important:
These java files should not be relocated as their path is referenced by the Inline Service when registering each of the batch process to the batch framework.Refer to Section 8.4.1, "Application Object" for further information about registering each batch process.
The LearningBatchJob.java file contains the logic to process a list of customers and offer responses, obtained through a SQL query, and calls the Inline Service informant to update its learning models.
The init() API loads all of the batch parameters defined for this batch job, such as the SQL statement for pulling customer information from the CrossSellBatchLearnings table.
The getNextInput() API processes the given result set of customer data and sets the data into the inputRow object to be processed by the executeRow() API.
The executeRow() API calls the Call Start informant to begin the Oracle RTD session, passing it the appropriate request parameters. It then calls the recordEvent() API, which in turn calls the Record Events Integration point.
The flushOutputs() API is not used for this batch job.
The cleanup() API closes out the result set built from the init() API and closes the database connection.
For this batch job, given a set customer and offer data, the logic updates event models directly via java code.
The LearningWithDirectEventRecordingBatchJob.java file is an extension of LearningBatchJob.java. All of the expected APIs for the batch framework are consumed from LearningBatchJob.java with the exception of recordEvents(), which is overridden here.
Overrides the recordEvents() API from LearningBatchJob.java. The recordEvents() API updates the choice event model for this Inline Service directly, instead of calling the Record Events Integration point.
This batch job demonstrates an example ETL process where customer offers are read from the CrossSellBatchBestOffer table, and simulated responses are then recorded to the Oracle RTD table, CrossSellBatchLearnings, for future learning using standard JDBC java functionality.
The init() API loads all of the batch parameters defined for this batch job, and prepares all of the SQL statements to be used for this job.
The getNextInput() API processes the given result set of customer data, and sets the data into the inputRow object to be processed by the executeRow() API.
The executeRow() API simulates customer responses to the offer contained in the Input Row object. The customer information, offer id, and response are then passed to an insert() API to prepare an INSERT statement for that data to be used when flushOutputs() is called by the framework.
The flushOutputs() API is called to execute all of the INSERT statements that have been collected and prepared by the insert() API.
The cleanup() API closes out the result set built from the init() API, and closes the database connection.
This batch job is functionally the same as OfferAcceptanceETLBatchJob, but instead of using JDBC java functionality to write the output to the CrossSellBatchLearnings table, the Oracle RTD platform's TableInserter() API methods are used instead.
This .java file extends OfferAcceptanceETLBatchJob.java.
Overrides the init() API from OfferAcceptanceETLBatchJob.java and instantiates the TableInserter() API.
Overrides the insert() API from OfferAcceptanceETLBatchJob.java and sets the INSERT record using the tableInserter.put() API.
Overrides the flushOutputs() API from OfferAcceptanceETLBatchJob.java and calls the tableInserter.flush() method.
Overrides the cleanup() API from OfferAcceptanceETLBatchJob.java and closes out the job using the tableInserter APIs.
For a given offer id, this batch job requests the offer score for a list of customers pulled from the CrossSellBatchCustomers data source. The scores are then written to the output table, CrossSellBatchScores.
The init() API loads all of the batch parameters defined for this batch job and prepares the required SQL statements. It also sets a choice object for the requested offer to be scored, set by the offerId batch job parameter.
The getNextInput() API processes the given result set of customer data, and sets the data into the inputRow object to be processed by the executeRow() API.
Using the choice object set in the init() API, the executeRow() API sets the session() with customer Id from the inputRow object, and then retrieves the likelihood score for the Purchased event for the desired offer.
The likelihood score, along with the customer information is then passed to the insertOrUpdate() API, which uses JDBC functionality and prepares the INSERT or UPDATE statement to be used after the flushOutputs() API is called.
The flushOutputs() API is called to execute all of the INSERT or UPDATE statements that have been collected and prepared by the insertOrUpdate() API.
The cleanup() API closes out the result set built from the init() API and closes the database connection.
The OfferScoringBatchJobReadahead batch job has the same scoring functionality as the OfferScoringBatchJob.java file, in that it will request a likelihood score for a given offer id for each customer.
The difference is in how the customer data is fed to the RTD server. Instead of passing one customer id at a time to Oracle RTD and then retrieving its offer score, the OfferScoringBatchJobReadahead batch job passes a group of customer ids all together to Oracle RTD.
Using this strategy, Oracle RTD caches the session entities ahead of the scoring request. This enables faster processing cycles for users that are dealing with large volumes of customer data.
As with the OfferScoringBatchJob batch job, the scores retrieved are then written to the output table, CrossSellBatchScores.
The init() API loads all of the batch parameters defined for this batch job and prepares the SQL statements required. It also sets a Choice object for the requested offer that is to be scored, set by the offerId batch job parameter.
The getNextInput() API processes the given result set of customer data and sets the data into the inputRow object to be processed by the executeRow() API. Rather than process one customer id at a time, it will put together a group of customer id's, enabling Oracle RTD to cache the session entities for each id ahead of calling the executeRow method. This is passed to Oracle RTD via the fillAndCache method for the Customer entity.
Using the choice object set in the init() API, the executeRow() API sets the session() with the customer Id from the inputRow object and then retrieves the likelihood score for the event Purchased for the desired offer. The likelihood score, along with the customer information is then passed to the insertOrUpdate() API , which uses JDBC functionality and prepares the UPDATE or INSERT statement to be used once the flushOutputs() API is called.
The flushOutputs() API is called to execute all of the INSERT and UPDATE statements that have been collected and prepared by the insertOrUpdate() API.
The cleanup() API closes out the result set built from the init() API and closes the database connection.
This batch job takes a given set of customer data and requests the best offers from Oracle RTD using the Offer Request advisor integration point. The results are then written to the output table, CrossSellBatchBestOffer.
The init() API loads all of the batch parameters defined for this batch job, such as the SQL statement for pulling customer information from the CrossSellBatchCustomers table.
The getNextInput() API processes the given result set of customer data and sets the data into the inputRow object to be processed by the executeRow() API.
The executeRow() API calls the Offer Request integration point, passing it the appropriate customer id from the inputRow object. The recommended offer is then obtained from the response and passed to the insertOrUpdate() API, which uses JDBC functionality and prepares the INSERT or UPDATE statement to be used after the flushOutputs() API is called.
The flushOutputs() API is called to execute all of the INSERT and UPDATE statements that have been collected and prepared by the insertOrUpdate() API.
The cleanup() API closes out the result set built from the init() API and closes the database connection.
This section describes the elements of the CrossSellBatch Inline Service. It contains the following topics:
At the Inline Service Application object level, in the Logic section, each of the batch jobs is registered with the batch framework. Registering each of the batch .java files is all that is required to "batch enable" an Inline Service.
The general java syntax for batch job registration is as follows:
BatchAgent batchAgent = getBatchAgent();
batchAgent.registerBatch("<Batch Job Identifier Name>",
"<batch java file src path and name>",
<batch java file name>.description,
<batch java file name>.paramDescriptions,
<batch java file name>.paramDefaults);
batchAgent.registerDataSource("SDDS");
For example, to register the Learning batch job and Offer Select batch job with the Batch Framework, the syntax is as follows:
BatchAgent batchAgent = getBatchAgent();
/*
* CrossSellLearning Batch
*/
batchAgent.registerBatch("CrossSellLearning",
"crosssell.batch.LearningBatchJob",
LearningBatchJob.description,
LearningBatchJob.paramDescriptions,
LearningBatchJob.paramDefaults);
/*
* CrossSellSelectOffers Batch
*/
batchAgent.registerBatch("CrossSellSelectOffers",
"crosssell.batch.OfferSelectBatchJob",
OfferSelectBatchJob.description,
OfferSelectBatchJob.paramDescriptions,
OfferSelectBatchJob.paramDefaults);
batchAgent.registerDataSource("SDDS");
For the purposes of this example, although some of the batch jobs have redundant functional purposes (for example, LearningBatchJob.java and LearningWithDirectEventRecordingBatchJob.java), all of the .java files are registered in this Inline Service.
Two performance goals, Customer Retention and Revenue, both maximized, are included in this Inline Service. Their associated scoring methods are configured at the Offers choice group level.
Two decisions are configured for the CrossSellBatch Inline Service:
OfferDecision - Based on the OfferAcceptance model
RandomDecision - Produces a random offer for the control group
These decisions are called through the Offer Request advisor integration point. Table 8-2 and Table 8-3 describe the parameters for these decisions.
Table 8-2 Decision OfferDecision
| Parameter | Description |
|---|---|
|
Decision Name |
OfferDecision |
|
Select Choices From |
Offers |
|
Number of Choices to Select |
1 |
|
Select at Random |
No |
|
Target Segments |
Segment To Retain (Customer Retention - 70%, Revenue - 30%) Default (Customer Retention - 30%, Revenue - 70%) |
|
Pre Selection Logic |
None |
|
Post Selection Logic |
Logic included to update the choice model for the Delivered event, and to add the presented offer to the session attribute, Presented Offers |
Table 8-3 Decision RandomDecision
| Parameter | Description |
|---|---|
|
Decision Name |
RandomDecision |
|
Select Choices From |
Offers |
|
Number of Choices to Select |
1 |
|
Select at Random |
Yes |
|
Target Segments |
None |
|
Pre Selection Logic |
None |
|
Post Selection Logic |
Logic included to update the choice model for the Delivered event, and to add the presented offer to the session attribute, Presented Offers |
The batch use cases for the CrossSellBatch Inline Service are demonstrated through a cross sell example. The choice groups configured represent a sample choice group hierarchy for cross selling credit card and loan offers for a fictitious financial institution. The resulting hierarchy of choice groups is depicted in the following diagram, where each of their attributes is inherited from the parent choice group, Offers.
Table 8-4 describes the configuration parameters for the Offers choice group, including a list of the choice attributes.
Table 8-5 describes the choice attributes in more detail.
Table 8-4 Configuration Parameters for Offers Choice Group
| Parameter | Description |
|---|---|
|
Choice Group Name |
Offers |
|
Choice Attributes |
Likelihood of Purchase Message Profit Margin Should Respond Positively For choice attribute details, see Table 8-5. |
|
Scores |
For the performance goal Customer Retention, score is determined at the individual choice group level. For the performance goal Revenue, score is determined by the multiplication of the value for Profit Margin times the value predicted by OfferAcceptance model for the Purchased event. |
|
Choice Events |
Delivered Interested Purchased |
|
Choice Eligibility |
None |
|
Group Attributes |
None |
|
Group Eligibility |
None |
|
Dynamic Choices |
None |
Table 8-5 Choice Attribute Details for Offers Choice Group
| Choice Attribute | Type | Value |
|---|---|---|
|
Likelihood of Purchase |
Double |
Predicted by OfferAcceptance model for the Purchased event |
|
Message |
String |
Defined at each individual choice |
|
Profit Margin |
Double |
0.5 (value changed at the individual choice level) |
|
Should Respond Positively |
Boolean |
Determined through the ShouldRespondPositively function with the input "this" choice |
This section outlines the entity structure used for the CrossSellBatch Inline Service. As this covers a basic cross sell use case for a given set of customers, the session entity structure is kept at a minimum.
For this example the following entities have been configured:
Customer - Stores customer data used during batch learning and scoring simulations executed through the batch framework
The Session entity contains all of the additional entities and attributes to be used for learning and prediction by the Inline Service.
| Attribute | Type | Array | Mapping | Default Value | Comments |
|---|---|---|---|---|---|
|
Channel Id |
Integer |
No |
None |
None |
Session Key |
|
Channel |
String |
No |
None |
"Call" |
None |
|
Customer |
Customer |
No |
None |
None |
None |
|
Customer Preferences |
String |
Yes |
CustomerPreferencesDataSource.Response |
None |
None |
|
Presented Offers |
Choice |
Yes |
None |
None |
None |
The Customer entity is associated with the session through the Session entity.
| Attribute | Type | Array | Mapping | Default Value | Comments |
|---|---|---|---|---|---|
|
Customer Id |
Integer |
No |
None |
Session.CustomerID |
None |
|
Age |
Integer |
No |
CustomerDataSource.Age |
35 |
None |
|
Amount of Pending Transactions |
Double |
No |
CustomerDataSource.AmountOfPendingTransactions |
500 |
None |
|
Available Credit As Percent of Credit Line |
Double |
No |
CustomerDataSource.AvailableCreditAsPercentofCreditLine |
50 |
None |
|
Call Reason |
String |
No |
CustomerDataSource.CallReason |
"Credit limit related questions" |
None |
|
Calls Abandoned |
Integer |
No |
CustomerDataSource.CallsAbandoned |
1 |
None |
|
Calls Last 6 Months |
Integer |
No |
CustomerDataSource.CallsLast6Months |
2 |
None |
|
Card Type |
String |
No |
CustomerDataSource.CardType |
"Gold" |
None |
|
Complaints Per Year |
Integer |
No |
CustomerDataSource.ComplaintsPerYear |
1 |
None |
|
Credit Line Amount |
Integer |
No |
CustomerDataSource.CreditLineAmount |
1000 |
None |
|
Day Of Week |
String |
No |
CustomerDataSource.DayOfWeek |
"Wednesday" |
None |
|
Days To Due Date |
Integer |
No |
CustomerDataSource.DaysToDueDate |
15 |
None |
|
Has Credit Protection |
String |
No |
CustomerDataSource.HasCreditProtection |
"NO" |
None |
|
Language |
String |
No |
CustomerDataSource.Language |
"English" |
None |
|
Last Statement Balance |
Double |
No |
CustomerDataSource.LastStatementBalance |
400 |
None |
|
Marital Status |
String |
No |
CustomerDataSource.MaritalStatus |
"Single" |
None |
|
Minimum Amount Due |
Double |
No |
CustomerDataSource.MinimumAmountDue |
50 |
None |
|
Number Of Children |
Integer |
No |
CustomerDataSource.NumberOfChildren |
2 |
None |
|
Occupation |
String |
No |
CustomerDataSource.Occupation |
"Managerial" |
None |
|
Signed Up For EPay |
String |
No |
CustomerDataSource.SignedUpForEPay |
"No" |
None |
|
Tenure |
Double |
No |
CustomerDataSource.Tenure |
6 |
None |
The included informants for this Inline Service are the same as found in the Cross Sell example Inline Service provided with the Oracle RTD platform. As with the Cross Sell Inline Service, they are used by the batch processes to simulate learnings and provide offer predictions and scores.
The following informants are configured in the CrossSellBatch Inline Service:
The Call Info informant provides Oracle RTD with additional information about the call.
The Call Resolution informant sends the final outcome of the customer call.
The Call Start informant initiates the Oracle RTD session for the customer call.
Table 8-10 Informant Call Start
| Parameter | Description |
|---|---|
|
Informant Name |
Call Start |
|
Session Keys |
Session / Customer Id |
|
Request Data |
Channel (String) mapped to session.channel |
|
External System |
IVR |
|
Order |
1 |
|
Force session close |
No |
|
Logic |
Logic is included to fill the customer entity given the provided customer Id. |
|
Pre-condition |
None |
The Delete All Operational Data informant is created for this example to provide a method through the application to clear out the Oracle RTD learning models and choice history between each batch simulation. Typically, this informant would not be configured in a business workflow as Delete All Operational Data is also available as a method through the platform's JMX console.
Table 8-11 Informant Delete All Operational Data
| Parameter | Description |
|---|---|
|
Informant Name |
Delete All Operational Data |
|
Session Keys |
None |
|
Request Data |
None |
|
External System |
None |
|
Order |
0 |
|
Force session close |
No |
|
Logic |
Contains logic that removes the studies associated with this Inline Service, and deletes any data from the statistics and choice event history table. |
|
Pre-condition |
None |
The Force Learning informant was created for this example to run before batch learning. It wakes up the learning server or learning server will take about 15 seconds to wake up. This is important to do it before batch prediction, not regular real time predictions.
The Offer Response informant is created for this example to simulate offer responses. It will create a "response" based on the CustomerPreference data source.
Table 8-13 Informant Offer Response
| Parameter | Description |
|---|---|
|
Informant Name |
Offer Response |
|
Session Keys |
Session / Customer Id |
|
Request Data |
Channel (String) mapped to session.channel Choice Name (String) Choice Outcome (String) Simulation Mode (String) |
|
External System |
CRM |
|
Order |
4 |
|
Force session close |
Yes |
|
Logic |
Contains the simulation logic that sets whether the customer "accepts" the offer presented. |
|
Pre-condition |
None |
The Record Events informant is created for this example to simulate an offer response. It records the event that is passed through to it as a request input parameter for the given choice.
Table 8-14 Informant Record Events
| Parameter | Description |
|---|---|
|
Informant Name |
Record Events |
|
Session Keys |
Session / Customer Id |
|
Request Data |
Channel (String) mapped to session.channel Choice Name (String) Choice Outcome (String) Event Time (String) |
|
External System |
None |
|
Order |
0 |
|
Force session close |
No |
|
Logic |
Contains the logic that sets records the event for the given outcome through the request input parameters. |
|
Pre-condition |
None |
The included advisors for this Inline Service are the same as found in the Cross Sell example Inline Service provided with the Oracle RTD platform. As with the Cross Sell Inline Service, they are used by the batch processes to simulate learnings and provide offer predictions and scores.
The following advisor is configured in the CrossSellBatch Inline Service:
The advisor Offer Request returns the top ranked offers for the given customer ID.
Table 8-15 Advisor Offer Request
| Parameter | Description |
|---|---|
|
Advisor Name |
Offer Request |
|
Session Keys |
Session / Customer Id |
|
Request Data |
Channel (String) mapped to session.channel |
|
External System |
CRM |
|
Order |
3 |
|
Force session close |
No |
|
Decision |
OfferDecision |
|
Group Decision |
RandomDecision |
|
Default Choices |
None |
|
Logic |
None |
|
Pre-condition |
None |
One model is included in the CrossSellBatch Inline Service. This model is used to learn on the positive acceptance events that are simulated for the presenting of each offer for each customer session.
Table 8-16 OfferAcceptance Event Model
| Parameter | Description |
|---|---|
|
Model Name |
OfferAcceptance |
|
Model Setting |
Use for prediction, Randomize Likelihood, Default time window, Algorithm: Bayesian |
|
Choice Group |
Offers |
|
Base Event |
Presented |
|
Positive Outcome Events |
Interested Purchased |
|
Partitioning Attributes |
Session / Channel |
|
Excluded Attributes |
None |
|
Learn Location |
On session close |
|
Temporary Data Storage |
Keep for 30 Days using session key, customer ID |
This section catalogs the functions included in the CrossSellBatch Inline Service, which are used for determining profit margin and for simulating customer responses for the batch job.
Table 8-17 CrossSellBatch Inline Service Functions
| Function | Inputs | Outputs | Area Utilized In | Comments |
|---|---|---|---|---|
|
Multiply |
A (Double) B (Double) |
Double |
Various objects |
This function multiplies the given numbers. |
|
ShouldRespondPositively |
Choice (Choice) |
Boolean |
OfferResponse integration point, Offers choice attribute |
Returns either True or False based on the customer preference settings in the session attribute of the same name. |
After the CrossSellBatch Inline Service is deployed, the configured batch jobs should be run through Oracle RTD's batch framework. For further information on using the batch framework, refer to the Oracle RTD Batch Framework chapter in Oracle Real-Time Decisions Platform Developer's Guide.
From a workflow perspective, the java batch files should be run in the following sequence:
This batch process reads the CrossSellBatchCustomers table and writes the output to the CrossSellBatchBestOffer table.
Either of the following:
OfferAcceptanceETLBatchJob.java
This batch process reads from the CrossSellBatchBestOffer table and writes to the CrossSellBatchLearnings table.
OfferAcceptanceETLTableInserterBatchJob.java
This batch process reads from the CrossSellBatchBestOffer table and writes to the CrossSellBatchLearnings table.
This batch process reads the CrossSellBatchLearnings table.
LearningWithDirectEventRecordingBatchJob.java
This batch process reads the CrossSellBatchLearnings table.
Although they can be run independently, the Offer Scoring batch jobs (OfferScoringBatchJob.java and OfferScoringBatchJobReadahead.java) should ideally be run after 3a or 3b in order to produce scores which use the data learned in Oracle RTD from the learning batches.
|
 Copyright © 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|