| 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 |
Terminology:
The following terms are used throughout this chapter:Core ILS (or Core Inline Service) - refers to the RTD_CLM_Core Inline Service that serves as the basis for all Oracle RTD Decision Management applications
Base Marketing ILS (or Base Marketing Inline Service) - refers to the RTD_Base_Marketing Inline Service released with Oracle RTD Base Application as part of the RTD for Marketing Optimization application
This chapter focuses on the Inline Service elements required for Oracle RTD Decision Management applications, as they appear in the Core ILS and the Base Marketing ILS.
This chapter also references the metadata required as additional components for Oracle RTD Decision Management applications. For details of these metadata elements, see the following:
The chapter "Configuring Oracle Decision Management" in Oracle Real-Time Decisions Base Application Decision Management Installation and Configuration Guide
This section contains the following topics:
Table 9-1 shows a summary of the basic elements related to all Oracle RTD Decision Management Inline Services (in the Core ILS column) and those elements specific to the Inline Service for the RTD for Marketing Optimization application (in the Base Marketing ILS column).
Table 9-1 Elements in Core and Base Marketing Inline Services for Oracle RTD Decision Management Applications
| ILS Elements | Core ILS | Core Ref | Base Marketing ILS | Base Mktg Ref |
|---|---|---|---|---|
|
Application Logic |
Initialization + Cleanup logic |
As in Core ILS |
NA |
|
|
Application parameters |
CLM Database Polling Delay In Seconds CLM ILS Choice Groups CLM JDBC Source |
As in Core ILS |
NA |
|
|
Session entity |
Attribute: CLM Version Initialization + Cleanup logic |
As in Core ILS |
NA |
|
|
Entities |
CLM Dummy Entity |
As in Core ILS +
|
||
|
Data Sources |
(None) |
NA |
CustomerDataSource CustomerPreferencesDataSource |
NA |
|
Choice Groups |
CLM Base |
As in Core ILS +
(All these extra choice groups are under the CLM Base choice group) |
||
|
Decisions |
(None) |
NA |
Creative Decision Random Creative Decision |
|
|
Models |
Statistics (general model, not oriented to Decision Management) |
NA |
Creative Acceptance (based on CLM Base choice group) |
|
|
Functions |
CLM Are All Related Choices Eligible CLM Is Choice Eligible CLM Record Event Including Related Choices |
As in Core ILS
|
||
|
Informants |
CLM Request Database Hard Refresh CLM Request Database Hard Refresh CLM Reset Project Cache |
As in Core ILS +
|
"Loading the Choices of Active Projects in an Inline Service" |
|
|
Advisors |
(None) |
NA |
Get Creative |
|
|
Type Restrictions |
(None) |
NA |
Approval Status Region Type |
|
|
Java classes (in src>com>sigmadynamics>sdo) |
ApplicationSession.java CLMChoiceBag.java CLMChoiceBagStore.java CLMChoiceData.java CLMChoiceGroupMapper.java CLMChoiceGroupMapperStore.java CLMChoiceInstanceStore.java CLMCustomHandler.java CLMCustomHandlerStore.java CLMData.java CLMDataBaseHelper.java CLMDataBaseLoader.java CLMDataStore.java CLMMetadata.java CLMMetadataStore.java CLMNotRunningException.java CLMPropagateEnum.java CLMRelationshipKey.java CLMRelationshipType.java CLMScheduledExecutorService.java CLMShutdownException.java |
As in Core ILS +
|
NA |
This section describes the elements that occur in Inline Services that form part of a Oracle RTD Decision Management application. Some elements are general, that is, must exist in all such Inline Services, others are particular to the Base Marketing Inline Service associated with the reference application, RTD for Marketing Optimization, released with Oracle RTD Base Application.
As in other sections of this chapter, the terms Core ILS and Base Marketing ILS are used as required to specify where the elements are defined. Table 9-1 provides a summary of which elements are common to both Inline Services and which are specific to the Base Marketing ILS.
This section contains the following topics:
All Inline Services that form part of a Oracle RTD Decision Management application share a common architectural structure.
The Base Marketing ILS is a sample Inline Service that shows how to use choices managed by a Oracle RTD Decision Management application. This sample Inline Service uses the choice groups and relationship types of the RTD for Marketing Optimization application.
The Core ILS is a basic Inline Service which can be added to, to create an Inline Service specific to other Oracle RTD Decision Management applications.
[When you build your own Oracle RTD Decision Management application, you have to add application-specific elements and steps in addition to those provided with the Core ILS. You are strongly advised to refer to the application-specific elements and steps in the Base Marketing ILS to see the corresponding elements and steps there.]
In all Oracle RTD Decision Management Inline Services, you need to define the same choice groups in the Inline Service as you define in the Oracle RTD Decision Management metadata. In addition, you can define choice attributes that follow relationship types between choice groups using the sample functions provided in the Base Marketing ILS.
Oracle RTD Decision Management Inline Services use their own mechanism to load dynamic choices, instead of using an entity as explained in Oracle Real-Time Decisions Developer's Guide. The settings explained in Oracle Real-Time Decisions Developer's Guide are mandatory for dynamic choice groups, therefore "dummy" objects have been introduced for that purpose, but are not used. The load of dynamic choice groups happens automatically. The only difference to note is that the choice array passed as an argument to decisions pre-selection logic is empty. The Creative Decision decision in the Base Marketing ILS shows an example of how to properly handle this.
These design decisions enable the following application design goals:
Easier setup of the Inline Service
You do not have to specify a data source and an entity for each dynamic choice group and wire all these objects manually. This makes creation and maintenance of the Inline Service much easier.
Better control of dynamic choices lifecycle
The Base Marketing Inline Service automatically detects when dynamic choices have been updated in the Decision Management database main repository. This is done asynchronously and therefore has no impact on integration point response time. Dynamic choices are loaded asynchronously and their rules are compiled asynchronously. Integration point requests for new sessions will start using a new version after this whole asynchronous process has completed. To keep cohesion within a session, multiple integration point requests in the same sessions all use the same version of dynamic choices.
Ability to retrieve custom lists of dynamic choices
During the asynchronous load of the choices from the Oracle RTD Decision Management database, you can mark choices as belonging to any list you want. During an integration point, you can retrieve the dynamic choices of that list in a single call, which saves having to do the same time consuming operations over and over in each integration point.
Ability to run tests against a project before it is committed to the main repository
The Oracle RTD Decision Management database main repository gets updated to a new version when either of the following occurs:
Someone commits a project using the Decision Manager user interface on the same database
Changes from a different system are pushed to this production Oracle RTD Decision Management database using an offline process
The application has the following parameters, common to all Oracle RTD Decision Management Inline Services:
CLM Database Polling Delay In Seconds: the number of seconds the Inline Service will wait between the beginning of the previous poll and a new poll, to see if there is a new repository version in the Oracle RTD Decision Management database
CLM ILS Choice Groups: an array of all the dynamic choice groups to be loaded from the Oracle RTD Decision Management database
CLM JDBC Source: the datasource you have added in Oracle RTD's web.xml for rtis.war, typically CLMDS
The application object has some code in initialization logic and cleanup logic to start and stop the asynchronous load of Oracle RTD Decision Management dynamic choices.
Common to all Oracle RTD Decision Management Inline Services, the Session entity has an attribute called CLM Version, which is used to track which repository version of the Oracle RTD Decision Management database this session is using. If a project is committed, current sessions will continue to use the previous repository version of the Oracle RTD Decision Management database, and new sessions will start using the new repository version of the Oracle RTD Decision Management database after it is loaded in Inline Service memory.
The session has some lines of code in the Initialization logic and Cleanup logic that should not be removed.
CLM Dummy Entity appears in both the Core ILS and the Base Marketing ILS, and is required to satisfy dynamic choice group definitions. The Customer entity appears in the Base Marketing ILS only.
The CLM Dummy Entity entity has the following attributes:
Dummy Choice ID
The Customer entity has the following attributes:
Customer ID
Age
Amount Of Pending Transactions
AvailableCreditAsPercentOfCreditLine
CallReason
CallsAbandoned
CallsLast6Months
CardType
ComplaintsPerYear
CreditLineAmount
DayOfWeek
Days To Due Date
HasCreditProtection
Language
LastStatementBalance
Marital Status
MinimumAmountDue
NumberOfChildren
Occupation
Signed Up For Epay
Tenure
The dynamic choices must be created under the CLM Base choice group.
Note:
The CLM Base choice group exists in both the Core ILS and the Base Marketing ILS.In the Core ILS, there are no choice groups defined under CLM Base. The Base Marketing ILS contains the choice groups described later in this section.
For all Oracle RTD Decision Management application Inline Services, in the Dynamic Choices tab of each choice group under CLM Base, select the option Use Dynamic Choices for this Choice Group, and specify these properties:
Group attribute containing the list of Entities for choices: CLM Dummy Entity List
Choice attribute to assign the entity data: Dummy Data
Entity attribute that contains the choice id: Dummy Choice Id
You must create choice groups and choice attributes with ids, data types and type restrictions that match the ones specified in the Oracle RTD Decision Management metadata configuration files. Only Boolean, Date, Double, Integer and String data types are supported. Arrays are not supported.
The choice groups defined in the Base Marketing ILS are as follows:
You must create functions to create the relationship attributes between choices. See the following examples in the Oracle RTD Base Marketing Inline Service:
Note:
In some functions, the relationship returns one choice (such as between one offer and its campaign); in other functions, the relationship returns multiple choices (such as between one campaign and its multiple offers).Get CLM ILS Campaign Offers
Get CLM ILS Channel Creatives
Get CLM ILS Channel Placements
Get CLM ILS Creative Channel
Get CLM ILS Creative Offer
Get CLM ILS Creative Slot Type
Get CLM ILS Offer Campaign
Get CLM ILS Offer Creatives
Get CLM ILS Placement Channel
Get CLM ILS Placement Slots
Get CLM ILS Slot Placement
Get CLM ILS Slot Slot Type
Get CLM ILS Slot Type Creatives
Get CLM ILS Slot Type Slots
Note:
in the following tables for each of the choice group attributes:DM refers to the Decision Manager user interface available with Oracle RTD Decision Management
DC refers to the Decision Center user interface available with Oracle RTD
Table 9-2 show the attributes for the Campaign choice group.
Table 9-2 Campaign Choice Group Attributes
| Attribute Name | Data Type | DM Visible? | Required? | Type Restricted? | DC Viewable? |
|---|---|---|---|---|---|
|
Approval Status |
String (20) |
Yes |
Yes |
Yes |
Yes |
|
Code |
String (20) |
Yes |
Yes |
No |
Yes |
|
Name |
String (40) |
Yes |
Yes |
No |
Yes |
|
Start Date |
Date Time |
Yes |
No |
No |
Yes |
|
End Date |
Date Time |
Yes |
No |
No |
Yes |
|
Description |
String (250) |
Yes |
No |
No |
Yes |
|
Type |
String (20) |
Yes |
Yes |
Yes |
Yes |
Table 9-3 show the attributes for the Offer choice group.
Table 9-3 Offer Choice Group Attributes
| Attribute Name | Data Type | DM Visible? | Required? | Type Restricted? | DC Viewable? |
|---|---|---|---|---|---|
|
Code |
String (20) |
Yes |
Yes |
No |
Yes |
|
Type |
String (20) |
Yes |
Yes |
Yes |
Yes |
|
Start Date |
Date Time |
Yes |
No |
No |
Yes |
|
End Date |
Date Time |
Yes |
No |
No |
Yes |
|
Approval Status |
String (20) |
Yes |
Yes |
Yes |
Yes |
|
Description |
String (250) |
Yes |
No |
No |
Yes |
|
Name |
String (40) |
Yes |
Yes |
No |
Yes |
|
Region |
String (20) |
Yes |
No |
Yes |
Yes |
|
Product |
String (40) |
Yes |
No |
No |
Yes |
|
Promotion |
String (40) |
Yes |
No |
No |
Yes |
|
Cost |
Double |
Yes |
No |
No |
Yes |
|
Revenue |
Double |
Yes |
No |
No |
Yes |
Table 9-4 show the attributes for the Creative choice group.
Table 9-4 Creative Choice Group Attributes
| Attribute Name | Data Type | DM Visible? | Required? | Type Restricted? | DC Viewable? |
|---|---|---|---|---|---|
|
Approval Status |
String (20) |
Yes |
Yes |
Yes |
Yes |
|
Code |
String (20) |
Yes |
Yes |
No |
Yes |
|
Name |
String (40) |
Yes |
Yes |
No |
Yes |
|
Start Date |
Date Time |
Yes |
No |
No |
Yes |
|
End Date |
Date Time |
Yes |
No |
No |
Yes |
|
Description |
String (250) |
Yes |
No |
No |
Yes |
|
Type |
String (20) |
Yes |
Yes |
Yes |
Yes |
|
Region |
String (20) |
Yes |
No |
Yes |
Yes |
|
Product |
String (40) |
Yes |
No |
No |
Yes |
|
Promotion |
String (40) |
Yes |
No |
No |
Yes |
|
Cost |
Double |
Yes |
No |
No |
Yes |
|
Revenue |
Double |
Yes |
No |
No |
Yes |
Table 9-5 show the attributes for the Channel choice group.
Table 9-6 show the attributes for the Placement choice group.
Table 9-7 show the attributes for the Slot choice group.
Table 9-8 show the attributes for the Slot Type choice group.
The Base Marketing ILS uses a single model Creative Acceptance, defined on the CLM Base choice group, which tracks the Interested and Converted outcomes. The converted likelihood is then used in decisions.
Apart from the general Statistics model, there is no model defined in the Core ILS.
All the integration points and decisions described in this section occur in the Base Marketing ILS only.
The CLM Test Informant informant is for testing purposes only, and shows examples of how the Oracle RTD Decision Management APIs can be used.
The Session Start and Session Resolution informants are typical informants for opening and closing sessions.
The Get Creative advisor returns a creative for a given slot. A creative has a slot type and a slot has a slot type. Only creatives that have a slot type similar to the slot type of the slot passed as incoming parameter will be returned. This advisor uses the Creative Decision decision and the Random Creative Decision decision for the control group.
The Creative Feedback informant closes the loop by recording the outcome for that creative and that slot.
All the decisions described in this section occur in the Base Marketing ILS only.
The Creative Decision decision and the Random Creative Decision decision use the same code in pre-selection logic and post-selection logic to return only creatives that are eligible and have the same slot type as the slot passed as argument. The logic records that this creative was presented for both that creative and that slot.
All the type restrictions, choice groups, and choice group attributes described in this section occur in the Base Marketing ILS only.
In the Base Marketing Inline Service, type restrictions are defined for the attributes of certain choice groups. This section lists the type restrictions and the choice group attributes that use them.
This section contains the following topics:
Table 9-9 show the values for the Approval Status type restriction.
Table 9-10 show the values for the Region type restriction.
Table 9-11 show the values for the Type type restriction.
Table 9-12 shows the choice group attributes that use the type restrictions defined in the Base Marketing Inline Service.
The dynamic choice groups all inherit from CLM Base. Therefore they only inherit rules from CLM Base, there is no inheritance of rules from one choice group to the other as with standard, non-Decision Management Inline Service designs.
Instead, rules are propagated based on metadata defined in relationship types. In the reference implementation (RTD for Marketing Optimization), all relationship types are defined to propagate rules from destination to owner. Relationship types are defined as "many to one" or "many to zero", where the owner is the "many" side and the destination is the "one" or "zero" side of the relationship.
Therefore, when eligibility is evaluated on a creative, this also evaluates eligibility on that creative's offer, channel and slot type. The offer in turn evaluates eligibility on its campaign. So, in order to be eligible, the campaign, offer, channel and slot type of that creative all have to be eligible. This is more powerful than simple inheritance because multiple "directions" can be followed. This can be thought of as multiple inheritance, or more accurately composition. The rules for propagation are defined in metadata and are therefore highly customizable.
For the rules to be properly executed, two rules have been added for CLM Base choice eligibility (see the functions CLM Is Choice Eligible and CLM Are All Related Choices Eligible). One is the evaluation of the current choice rule metadata which is typical of dynamic choices. The other one is to evaluate eligibility on related choices based on this propagation metadata. The latter one is called first, so, recursively, when the eligibility of a choice is computed, the related choices that are furthest away are computed first. For instance, for a creative to be eligible, the campaign eligibility will be computed first - this is often false, and avoids having to compute intermediate eligibility rules.
Note that there is a Choice Is Eligible choice attribute in CLM Base in order to cache the eligibility for the duration of the integration point.
Propagation of events is done in a similar fashion to the propagation of rules.
In the Base Marketing ILS, Oracle RTD gets a creative for a slot. Oracle RTD records the event for:
The creative and its campaign, offer, channel and slot type
The slot and its placement, channel and slot type
Oracle RTD does not count the event twice on the channel and slot type, which appear in both lists. Therefore, Oracle RTD records the event once for the creative, campaign, offer, channel, slot type, and placement involved related to that creative and slot.
In order to follow these relationships while recording events, you must call the CLM Record Event Including CLM Related Choices function.
Note:
The javadoc for the Java APIs can be found in
clm\lib\clm-ils-api-javadoc.jar.This section contains the following topics:
Several "Store" classes are used to store objects in memory for the right lifespan.
CLMMetadataStore holds CLMMetadata in memory for the life lifespan of the Inline Service. CLMMetadata consists of information on propagation of rules and events that is stored in the Oracle RTD Decision Management database.
CLMDataStore holds CLMData in memory. CLMData consists of all the dynamic choices and all the relationships between these choices. CLMDataStore holds the latest version of that CLMData, and any older CLMData still used by existing sessions.
CLMChoiceBagStore holds a CLMChoiceBag in memory for the lifespan of each integration point. CLMChoiceBag contains dynamic choice objects that can be used in your java code to work with all the dynamic choices. See the "CLM Test Informant" for an example.
CLMCustomHandlerStore holds all the custom CLMCustomHandler instances that will be called during each new Oracle RTD Decision Management database load.
CLMChoiceGroupMapperStore and CLMChoiceInstanceStore are internal stores used to cache objects obtained using Java reflection APIs to improve performance.
Some methods ask for the "choice id" of a dynamic choice, which is different from the "SDOId" of the dynamic choice. The choice id is what users see and enter in Decision Manager. The SDOId is the concatenation of the group id, the $ symbol and the choice id. The attribute "Choice Id" has been added in choice group "CLM Base" so that it is possible to retrieve the choice id of a Oracle RTD Decision Management dynamic choice by accessing that attribute.
Some methods ask for the "group id" (also known as the "choice group id") of the dynamic choice. This is the SDOId of the choice group of the dynamic choice (getGroup().getSDOId()) and corresponds to the choice group id in both CLM and Inline Service metadata.
The choice name (as entered in the Decision Manager user interface) is retrieved by calling getSDOLabel() on the dynamic choice.
CLMDataStore holds multiple CLMData, one for each in memory version of the Oracle RTD Decision Management database.
CLMChoiceData holds data information about one choice.
CLMData holds all the choices as CLMChoiceData objects.
CLMData holds all the relationships between these objects.
CLMChoiceBagStore holds multiple CLMChoiceBag, one for each in thread currently running an integration point.
CLMChoiceBag holds choices as dynamic choices, by creating them from CLMData as needed.
The dynamic choices have relationships between each other, which are computed from CLMData as needed.
Dynamic choices are only valid for the lifespan of the integration span, so each choice bag is discarded at the end of the integration point. This is why, for performance reasons, Oracle RTD creates the dynamic choices in them. This is also one of the reasons for introducing the custom handler feature. With this feature, you can get a subset of dynamic choices without having to create other dynamic choices. In the "Get Creative" example, you can get all the creative dynamic choices of a specific slot type, without having to create a dynamic choice for every single creative, and then checking the slot type of each of these creatives, doing this every time the advisor is called.
Custom handlers let you access CLMData to build and store custom lists.
CLMData provides APIs to:
Retrieve a CLMChoiceData choice object given its choice id
Retrieve all choice ids for a given choice group
Retrieve all choice ids for a given custom list
Retrieve choice ids related to a given choice
Add a choice id to a custom list (the goal of custom handlers)
CLMChoiceBag is the main class you will use in your Inline Service to access dynamic choices.
It provides APIs to:
Retrieve a dynamic choice object given its choice id
Retrieve all dynamic choices (or their ids) for a given choice group
Retrieve all dynamic choices (or their ids) for a given custom list
Retrieve choices (or their ids) related to a given choice
You can load the main repository choices and the changes that have been made in a project. This can be used to test the changes in a project before committing them. See the method CLMChoiceBagStore.setProject(int projectRowId) and informant CLM Project Test Informant. The choices loaded for that project are cached in memory.
Oracle RTD Decision Management Inline Services must check to see if changes have been made due to a project being committed at the regular interval defined in the Application parameter CLM Database Polling Delay In Seconds.
Two informants have been added to control that behavior:
CLM Request Database Hard Refresh: requests a refresh of all dynamic choices and starts the polling interval again after the refresh is done
CLM Request Database Soft Refresh: requests a refresh of all dynamic choices only if a project has been committed since last refresh, and starts the polling interval again after the refresh is done
Anther informant, CLM Reset Project Cache, shows how to reset the cache of the choices for a given project.
|
 Copyright © 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|