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.
Note:
The Base Marketing Slices ILS used by the Base Marketing with Slices application is the same as the Base Marketing ILS. For more information on the Base Marketing with Slices application, see Section 2.3 "Configuring and Deploying Base Marketing with Slices" in the Oracle Real-Time Decisions Base Application Decision Management Installation and Configuration Guide.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 |
Campaign Acceptance Channel Acceptance Creative Acceptance Offer Acceptance Placement Acceptance Slot Acceptance Slot Type Acceptance Tag Acceptance |
|
|
Functions |
CLM Is Choice Graph Eligible CLM Is Choice Eligible CLM Record Event Including Related Choices |
As in Core ILS+
|
||
|
Informants |
CLM Request Database Hard Refresh CLM Request Database Soft 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 Eligibility Rule Filtering Rule Project Type Region Scroring Rule Type |
|
|
Java classes (in |
|
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.
For the Base Marketing ILS, the following two parameters are added:
Record Decision Event Log: specifies if logging of decisions is done
Record Choice Event Log: specifies if logging of choice events is done
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:
The Project choice group is required in the Inline Service if the Decision Management application has project attributes with type restrictions. Type restrictions provide lists of values for the attributes during project creation and editing.
Note:
The Project choice group must be defined in the metadata for a Decision Management application, even if no project attributes have type restrictions.Functions for Choice Group Relationship Attributes
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 Creative Tags
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
Get CLM ILS Tag Creatives
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 shows the non-relationship 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 |
|
Region |
String (20) |
Yes |
No |
Yes |
Yes |
|
Start Date |
Date Time |
Yes |
No |
No |
Yes |
|
End Date |
Date Time |
Yes |
No |
No |
Yes |
|
Type |
String (20) |
Yes |
Yes |
Yes |
Yes |
Table 9-3 shows the non-relationship 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 |
|
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 |
|
Marketing Priority |
String (CLOB) |
Yes |
No |
No |
No |
|
Marketing Priority Value |
Double |
No |
No |
No |
No |
The Marketing Priority Value is used to cache the value returned by the Marketing Priority scoring rule for the duration of the integration point. It is computed by calling the Get CLM Marketing Priority function.
Table 9-4 shows the non-relationship 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 |
|
Start Date |
Date Time |
Yes |
No |
No |
Yes |
|
End Date |
Date Time |
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 |
|
Image |
String (250) |
Yes |
No |
No |
Yes |
|
Script |
String (CLOB) |
Yes |
No |
No |
Yes |
The Tag choice group contains only relationship attributes, defined in the Tag-related Functions for Choice Group Relationship Attributes.
Note:
in the Inline Service, Tag choice groups are defined with default eligibility rules. However, unlike the other choice groups, there are no equivalent eligibility rules for Tag choices in Decision Management metadata.The Channel choice group contains only relationship attributes, defined in the Channel-related Functions for Choice Group Relationship Attributes.
Table 9-5 shows the non-relationship attributes for the Placement choice group.
The Slot choice group contains only relationship attributes, defined in the Slot-related Functions for Choice Group Relationship Attributes (that is, functions related specifically to Slot, rather than Slot Type).
The Slot Type choice group contains only relationship attributes, defined in the Slot Type-related Functions for Choice Group Relationship Attributes (that is, functions related specifically to Slot Type, rather than Slot).
The Project choice group is only required in the Inline Service if you want to see lists of values for project attributes in Decision Management applications when creating and editing projects. If no Project choice group exists in the Inline Service, Decision Management Project screens will show Name and Description only.
Table 9-6 shows the non-relationship attributes for the Project choice group.
Table 9-7 shows the non-relationship attributes for the Segment choice group.
Table 9-8 shows the non-relationship attributes for the Decision choice group.
There are eight choice event models in the Base Marketing ILS, one for each choice group. All the choice event models are used for tracking and reports, and the Creative Acceptance model is also used to predict the most suitable creatives.
The Inline Service can be modified to implement more advanced decision logic involving multiple predictive models, for example, to select the best offer according to certain predictive criteria, then to pick the most suitable creative associated with this offer.
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 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
See also Section 9.2.14.6, "Loading the Choices of Active Projects in an Inline Service" and Section 9.2.14.7, "Dynamic Choice Cache Administration Methods" for information about project administration informants.
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.
The weights for the decision are defined in Decision Manager and retrieved using the Decision choice with the id specified as argument in the custom goal weights function, which is the following by default: CLM Get Weights("CreativeDecision").
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 Project Type type restriction.
Table 9-11 show the values for the Region type restriction.
Table 9-12 show the values for the Type type restriction.
These type restrictions are used to specify which attributes should be automatically compiled as either an eligibility, filtering or scoring rule. Specify these type restrictions for attributes that use the rule editor in Decision Manager.
Table 9-13 shows the choice group attributes that use the type restrictions defined in the Base Marketing Inline Service.
Table 9-13 Choice Group Attribute Usage of Type Restrictions
| Type Restriction | Used By |
|---|---|
|
Approval Status |
Campaign - Approval Status Offer - Approval Status Creative - Approval Status |
|
Project Type |
Project - Type |
|
Region |
Campaign - Region Offer - Region Creative - Region |
|
Type |
Campaign - Type Offer - Type Creative - Type |
|
Eligibility Rule |
CLM Base - Eligibility Rule |
|
Filtering Rule |
Segment - Filtering Rule |
|
Scoring Rule |
Offer - Marketing Priority |
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 - this applies to all the choice groups except Tag, as tags do not have rules defined in the metadata. Relationship types are defined as either "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) or "many to many".
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, the Choice Eligibility for the CLM Base choice group calls the CLM Is Choice Graph Eligible function which executes the eligibility rule on this choice and all the choices it needs to propagate to.
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, tag, 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, tag, 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 Related Choices function.
Decision Manager lets business users specify performance goal weights for a choice of type Decision.
The decision that wants to use the External Performance Goal Editor needs to call the CLM Get Weights function with the decision choice id as argument (the same ID as the ID of the decision choice business users are editing in Decision Manager).
The function CLM Record Log records information about the decision or choice event in the Decision Analytics tables. This function is executed in the post selection logic of the Get Creative advisor and in the logic of the Creative Feedback informant. When logging occurs depends on the values of the Record Decision Log and Record Choice Event Log application parameters. The function GetDecison is used by CLM Record Log to find out the name of the decision logged in the choice event log.
For more information on Decision Analytics logging, see Section 18.2.4, "Inline Service APIs" in the Oracle Real-Time Decisions Platform Developer's Guide.
Note:
The javadoc for the Java APIs can be found inclm\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 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). 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
Another informant, CLM Reset Project Cache, shows how to reset the cache of the choices for a given project.