13 About Decision Studio Elements and APIs

Decision Studio elements are configured within Decision Studio, and the logic is added in the form of Java scriptlets. This chapter describes the properties of each element, and the Java scriptlets contained by the element (if any), with examples.

This chapter contains the following topics:

• Section 13.1, "Overview of the Oracle RTD Decisioning Process"

• Section 13.2, "The Oracle RTD Decisioning Process"

• Section 13.3, "About Element Display Labels and Object IDs"

• Section 13.4, "About the Application Element"

• Section 13.5, "Accessing Data" 

• Section 13.6, "Forming Entities"

• Section 13.7, "Performance Goals"

• Section 13.8, "Choice Groups and Choices"

• Section 13.9, "Filtering Rules"

• Section 13.10, "Scoring Rules"

• Section 13.11, "Using Rule Editors"

• Section 13.12, "About Decisions"

• Section 13.13, "About Selection Functions"

• Section 13.14, "About Models"

• Section 13.15, "About Integration Points"

• Section 13.16, "About External Systems"

• Section 13.17, "About the Categories Object"

• Section 13.18, "About Functions"

• Section 13.19, "About Type Restrictions"

• Section 13.20, "About Statistic Collectors"

13.1 Overview of the Oracle RTD Decisioning Process

The Oracle RTD decisioning process is based on a framework that takes into account the overall performance goals with which an organization is concerned, the performance metrics that measure those goals, the action required to score each of the available choices, and a weighting of that score based on segments of the population.

The following elements are part of this framework:

• Performance Goals

• Decisions

• Choice Groups and Choices

• Filtering Rules

• Scoring Rules

• Predictive Models

The following shows an overview of how the elements feed into the general Oracle RTD decisioning process, and form the basis for an Inline Service:

To see how extensions of these inputs can enable external applications together with Oracle RTD to provide a composite decision service for their end users, see Chapter 17, "Externalized Objects Management."

13.2 The Oracle RTD Decisioning Process

This section describes the general Oracle RTD decisioning process flow.

The Oracle RTD decisioning process is based on a framework that takes into account the following factors:

• The overall performance goals with which an organization is concerned

• How to score each of the available choices according to the performance goals

• A weighting of the performance goals based on segments of the population

Decisions are called by Advisors to score Choices, and return one or more Choices from a Choice Group. The set up of a Decision must include at least one Choice Group from which Choices are selected, and a function or rule to score the Choices. At run time, the Decision collects all the eligible Choices that exist in each of the Choice Groups. Then, the Choices are scored to finally determine the ranked order to send back through the Advisor.

Figure 13-1 shows the basic Oracle RTD processes, which include session start and finish, as well as the Oracle RTD decisioning process steps.

Figure 13-1 Oracle RTD Decisioning Process Flow

Note:

The examples in this section refer to elements in the CrossSell Inline Service, released with Oracle RTD.

The steps represent the different stages in the overall process of acquiring the necessary data and processing a decision, as follows:

1. The system initiates the session.

   When a user logs on, and the external application connects to Oracle RTD, Oracle RTD establishes a session.

   The external application generally acquires as much information about the user as possible, and passes it to Oracle RTD using one or more Informants.

   Oracle RTD may also retrieve further information from Data Sources and Entities defined in the Inline Service associated with the external application.

2. The Advisor calls a Decision.

   A request through an Advisor call initiates the decision process. The set of choices to evaluate for the decision is then determined for each of the associated Choice groups.

   The main goal of the Oracle RTD decision process is to evaluate and recommend the best choices to an application.

   What does "best choices" mean?

   The most relevant choices, the ones that serve the objectives of the application best.

   What are the "objectives" of the application?

   The Performance Goals, such as:

   • Revenue

   • Customer Retention

   The Performance Goals can be conflicting goals. So it is necessary to have a way to compromise between potentially conflicting goals.

3. The eligibility of Choices is determined.

   Some choices may not make sense in a particular real world case. Therefore there needs to be a mechanism to exclude choices at an early stage of the decision process. This is the eligibility stage.

   The eligibility rules for the Choices are invoked, to determine which Choices (from a potentially large set of Choices) pass on to the next stage of the decision process.

4. If necessary, the user segment is determined.

   The relevance of Choices may be different for the various groups of users that will ultimately get the choice recommendations. So we define different segments of users, whose characteristics are defined either explicitly by filtering rules or implicitly by custom functions that filter the data.

   For example, a Segment to Retain filtering rule can be defined as follows:

   • Segment to Retain is true when

   • All of the following:

   • 1. session / customer / callsAbandoned >= 6

   • 2. session / customer / tenure >= 2

   [Note that segments are not always required: the "best" choice could be the best for all users. In practice Oracle RTD has a Default segment, which in the absence of any other segments, means that the next stage (the scoring stage) applies to all users.]

   Typically, explicit filtering rules are used to segment the user population. Based on the segment, the designated weightings for each of the Performance Goals are used in scoring each eligible Choice.

   Segments and Weighted Performance Goals

   With a set of eligible Choices, which are the "best" ones?

   When you set up the Decision, you specify the target segment or segments that apply. At run time, during the decision process, Oracle RTD determines the (first) segment from the set-up list that applies to the user.

   When you set up the Decision, you also specify which of the Performance Goals apply for the Decision.

   Then you specify which Performance Goals are relevant to each segment, and you prioritize each Performance Goal in the segment relative to the other performance goals.

   That is, for each segment:

   • You specify which of the Performance Goals applies (there may be more than one)

   • You specify a weight factor for each Performance Goal selected for that segment

     The weight factors are used at runtime during the scoring process.

   As an example, the Decision Offers has two segments, Segment to Retain and Default, and the Inline Service has two Performance Goals, Customer Retention and Revenue.

   For the Segment to Retain segment, the weights for each Performance Goal could be set up as follows:

   • Customer Retention - Weight = 70%

   • Revenue - Weight = 30%

   For the Default segment, the weights for each Performance Goal could be set up as follows:

   • Customer Retention - Weight = 30%

   • Revenue - Weight = 70%

5. The Choices are scored.

   Summary: All eligible Choices are scored for each associated Performance Goal.

   In more detail:

   The ultimate objective of a Decision is to find the best Choices. When comparing Choices, this resolves into creating a numeric score for each Choice, ranking the Choices by score, then selecting the highest-scored Choices.

   Oracle RTD supports several types of scoring method, to allow for wide variation in real-world requirements.

   In the simplest case, each Choice has an unvarying, constant score, such as 10 for Premium Service, 8 for Standard Service, 6 for Basic Service.

   Scores for Choices can derive directly from attributes closely associated with the choices. For example, as a marketing strategy, the score for an individual Product Offer Choice can be set as the current profit margin for that product.

   More complex real-world requirements can be accommodated through the use of scoring rules, functions, and values predicted from models.

   Scoring methods apply to Choices and Choice Groups, as selected for Performance Goals. You can have different scoring methods for the same Choice with different Performance Goals. For example, Gold Choice can score 40 for the Revenue performance goal, and 10 for Customer Retention.

   Scoring rules

   A scoring rule typically consists of one or more conditions with associated scores. For example, the score for a credit card interest rate can defined as follows:

   Table 13-1 Credit Protection Retention Scoring Rule

   Condition	Value
   If All of the following: 1. session / customer / hasCreditProtection = "YES"	Then 0.0
   Otherwise...	The value is: 7.0

   
   

   The example shows a scoring rule with one qualifying condition. In general, scoring rules allow combinations of conditions with many different attributes. A simple scoring rule, on the other hand, can provide a single constant value, with no conditions.

   Functions

   Functions by their very nature can deal with the most varied real-world scenarios and special-case situations, and so provide the most flexible method to generate scores for choices. The only requirement is that any function to be used for scoring must return a number.

   Model predictions

   Scores can be related to historical and current real-time empirical data, and derived from data stored in Oracle RTD models. Where model predictions are defined as the scoring method, there must be sufficient data in the model to make the prediction for a choice.

   Example of Associating Scoring Methods with Choices

   The standard way of associating scoring methods with Choices in an Inline Service is in the Scores tab for a particular Choice or Choice Group.

   For example, in the Offers choice group, the choice Credit Protection has two different scoring methods defined, one for each of the Performance Goals:

   Table 13-2 Score Definition for Credit Protection Choice

   Performance Metric	Inherited Score (From)	Score
   Custom Retention	-	Credit Protection Retention
   Revenue	Predicted by OfferAcceptance:Purchased multiplied by Profit Margin (Offers)	-

   
   

   The scores for choice Credit Protection evaluate as follows:

   • For the Custom Retention Performance Goal, the score derives from the scoring rule Credit Protection Retention

   • For the Revenue Performance Goal, the score derives from the prediction from the OfferAcceptance model for the positive outcome Purchased multiplied by the Offers choice group attribute Profit Margin

6. The Choice scores are weighted.

   Scores are calculated for each eligible Choice that applies to an explicit or implicit Segment of users.

   For each Choice that has reached the scoring stage, scores are evaluated for each Performance Goal, with the necessary weighting applied as specified for the Segment-Performance Goal combination. For more details, see Segments and Weighted Performance Goals.

   The total score for each Choice is the sum of all the weighted Performance Goal scores.

   The best Choice is the Choice with the highest total score.

7. The Choice or Choices are returned to the external application.

   Oracle RTD returns one or more Choices to the external application, passing Choice names and any designated Choice attribute that the external application needs. The requesting application then displays the Choices or processes the information accordingly.

8. The session information is updated.

   This step can take place at any stage of the decision process. Its main effect is to update the Oracle RTD server with any new available information about the given session.

   In addition, Models can be updated from the session information either at specified integration points or at the end of the session.

9. The session is closed.

   The active Oracle RTD session is closed and any wrap up logic is executed, including learning on any Models defined to learn at session close.

13.3 About Element Display Labels and Object IDs

As you create elements, you enter a Display Label for the element. An Object ID is automatically generated as you type the Display Label.

Object IDs are automatically made to conform to Java naming conventions: variables are mixed case with a lowercase first letter; classes are mixed case with an uppercase first letter. If you have spaces in your label name, they will be removed when forming the Object ID. If you choose to manually enter an Object ID, you can overwrite the Object ID that was created for you.

You can use the Toggle icon on the Inline Service Explorer task bar to toggle between the Display Label of the object and its Object ID:

Note:

When creating a new object, if the object name is already used by an existing one, Decision Studio will automatically append a number to the Object ID (such as 1, 2, and so on) to avoid conflicts.

13.4 About the Application Element

When a new project is started in Decision Studio, an Application object is created under the Service Metadata folder. Properties of the Application object are defined with the following characteristics:

• Application Parameters

• Control Group

• Model Defaults

• Logic

All of these values are defined through the Decision Studio interface.

This section contains the following topics:

• Section 13.4.1, "Application Parameters"

• Section 13.4.2, "Application APIs"

• Section 13.4.3, "Configuring the Control Group"

• Section 13.4.4, "Setting Model Defaults"

• Section 13.4.5, "Writing Application Logic"

13.4.1 Application Parameters

This section describes Application parameters. This section contains the following topics:

• Section 13.4.1.1, "Using Debugging Options"

• Section 13.4.1.2, "Adding Application Parameters"

13.4.1.1 Using Debugging Options

If you are testing a deployed Inline Service against a production database, and you do not want to contaminate the model data, you can use the debugging options to keep data from being written. Debugging options are:

• Disable learning: This option maintains the model's current state so that testing does not introduce additional learnings.

• Disable database writes: This option keeps data from being written to the database.

• Parent first class loading: This option controls Java class loading.

  The default case, with the option checked, is to first load classes already defined at the parent (RTD server) level.

  When unchecked, this option allows the Inline Service to first load Java classes defined at the Inline Service level, which is useful for overriding existing functionalities.

  Note:

  For Oracle RTD systems running on WebSphere, you must ensure that this option (Parent first class loading) is always unchecked.

  In addition, as part of the WebSphere system configuration, you must have set up an equivalent class loading option in the WebSphere Administration Console. For details, see "Disabling Parent Class Loading" in Oracle Fusion Middleware Third-Party Application Server Guide.

13.4.1.2 Adding Application Parameters

Application parameters are global-level parameters that can be defined and stored across all sessions.

Click Add on the Application Parameters tab to add a parameter. When adding parameters, you supply the Name, Type, Array, and Default Value.

Parameters can optionally include Type Restrictions, which will help you in setting the parameters' values when used in rules. For more information about creating and using type restrictions, see Section 13.19, "About Type Restrictions."

Click Remove to remove parameters.

13.4.2 Application APIs

The following returns the Object label and Id, respectively:

public String getSDOLabel();
public String getSDOId();

When global parameters are set, getters and setters are generated in the code. To access the application parameter, for instance myApplicationParameter of type string, use the following:

String param = Application.getApp().getMyApplicationParameter();

Conversely, to set an application parameter:

Application.getApp().setMyApplicationParameter("my parameter"); 

13.4.3 Configuring the Control Group

The control group acts as a baseline so that business users can compare the Oracle RTD decisioning process against either a preexisting ranking process or a random selection. It is important to define the control group decision correctly to truly reflect the decision as it would have been made if Oracle RTD was not installed.

For example, in a cross-selling Inline Service for a call center, if cross-selling was being done randomly before Oracle RTD was introduced, the Control Group Decision should also reflect a random decision.

Table 13-3 Control Group Options

Option Name	Description
No Control Group	If selected, control group will not be used, the Selection Value will be set to 0, and Use value literally will be selected and disabled. Deselect No Control Group to turn on control group and to change the settings.
Selection Value	A reference to an attribute value. This value is used to seed the Random selection of requests for the control group.
Use value literally	If Use value literally is deselected, then the selection value for the control group should refer to a session key or an attribute uniquely identifying a customer. Control group participation is determined using a pseudo-random hash of the selection value. The result of the calculation is deterministic, and depends only on the selection value and the specified size of the control group. The actual size of the control group may differ slightly from the specified size. If Use value literally is selected, then the selection value directly determines the control group participation. The selection value in this case can be either Boolean (participation in control group is indicated by the true value) or integer (participation in control group is indicated by a non-zero value). For example, select Use value literally when assignment of customers to control group is done outside of Oracle RTD. The attribute used as the control group selection value has to indicate this assignment.
Percent of Population	This option is only active if Use value literally is set to False. In this case, the user decides what percentage of the total number of sessions should be assigned to the control group.
Use for analysis	Controls whether the control group participation should be tracked by analytic models or not.
Name for Analysis	Name that the analytic models should use for tracking the control group participation.

13.4.4 Setting Model Defaults

Model defaults control which model is used and how the model is set up. Most model defaults should not be changed unless you are advised to do so by Oracle Support Services.

Table 13-4 Model Defaults

Option Name	Description
Study name	The name of the study used by the Inline Service. Typically, each Inline Service has its own separate study. This can be achieved by keeping the name of the study the same as the name of the Inline Service. However, an existing study may be used when testing an Inline Service. In that case, learning should be disabled to preserve production data.
Persistence Interval	The interval at which model data is saved to a database. This feature should not be adjusted without assistance from Oracle Support Services.
Time Window Duration	The default value is Quarter. Each model can override this default value.
First Day of Week	The default value is locale dependent. In the United States, the default value is Sunday.
First Month of Year	The default value is January.
Build when data changes by	The percentage of new records to prompt the building of a new prediction model. The default value is 20%. For example, if set to 10% and the last time the prediction models were built was with 13400 records, then the next time they will be built will be after 1340 records.
Significance threshold	The default value is 25. This feature should not be adjusted without assistance from Oracle Support Services.
Correlation threshold	The default value is 0. This feature should not be adjusted without assistance from Oracle Support Services.
Max Input Cardinality	The maximum number of values that will be tracked in discrete attributes. The default value is 500. This feature should not be adjusted without assistance from Oracle Support Services.
Max Input Buckets	The maximum number of input buckets for numeric attributes. The default value is 200. A value of 100 may also be sufficient. This feature should not be adjusted without assistance from Oracle Support Services.

13.4.5 Writing Application Logic

Scriptlets to initialize and clean up an Inline Service are added through Decision Studio, using the Initialization Logic and Cleanup Logic panels on the Logic tab of the Application element.

These scriptlets are inserted into the init and cleanUp methods of the Application class. The init method is called when the Inline Service is being loaded. The method cleanUp is called when the Inline Service is unloaded. If the application is redeployed, init will be called again.

13.4.5.1 Adding Imported Java Classes

If the init or cleanUp method refers to user-provided Java classes, these classes may have to be imported. To add additional import statements, click Advanced next to the description. For more information, see the Description for the lib Folder Name in Table 12-1.

13.5 Accessing Data

To access data within your Inline Service, use the entity, data source, and session elements.

Entities provide a logical way to bring together data from multiple sources to form an object that is of use to the overall Inline Service. Entities are comprised of a number of attributes that describe the contents of the Entity. Entities also provide methods to access their attributes.

An Entity, such as a Customer, may combine incoming data from different sources, such as an account number entered through an IVR and customer history retrieved from a corporate database. One of the Entity's attributes may be a key, or unique identifier. The incoming data would then be mapped to a desired attribute of the Entity. Alternatively, entity attributes can be populated through the life of the session via additional logic coded in the inline service

Data sources act as suppliers of data. They provide a way to manage the connection to relational database tables and stored procedures. Data sources identify columns in a database table, or result sets from stored procedures as attributes. These attributes are mapped to Entity attributes.

The session object is a specialized Entity that identifies which attributes are available in memory to the Inline Service. Those attributes can be comprised of a Entity, such as Customer described previously, as well as attributes that are set by some other source, such as calculation. A session object is used to store information for a user session. Attributes stored in session are available throughout the Inline Service, and are destroyed when the session is closed. Attributes associated to the session will by default be used as inputs for Oracle RTD learning models unless explicitly excluded from the specific model or excluded for analysis altogether.

To access data, you typically follow these steps:

1. Create a data source, based on a SQL table or stored procedure.

2. Create an Entity with attributes mapped to zero or more data sources.

3. Add a key value to the Entity.

4. Add the Entity to the session as an attribute, and assign a session key.

5. Map the Entity attributes to data source columns or output values.

6. Map the Entity key to a session key or function.

This section contains the following topics:

• Section 13.5.1, "About Data Sources"

• Section 13.5.2, "Creating SQL Data Sources"

• Section 13.5.3, "Creating Stored Procedure Data Sources"

• Section 13.5.4, "Accessing Oracle Business Intelligence Enterprise Edition Data"

13.5.1 About Data Sources

Data is accessed within Inline Services using the elements data source and entity. A data source is an abstract provider of data. Data sources act as suppliers of data to the Inline Service.

There are two types of data sources: SQL data sources, and Stored Procedure data sources.

13.5.2 Creating SQL Data Sources

This section describes how to create a SQL data source. This section contains the following topics:

• Section 13.5.2.1, "SQL Data Source Characteristics"

• Section 13.5.2.2, "Adding Columns to the Data Source"

• Section 13.5.2.3, "Importing Database Column Names"

• Section 13.5.2.4, "Setting the Input Column"

13.5.2.1 SQL Data Source Characteristics

Table 13-5 lists the properties of a SQL data source.

Table 13-5 Properties of a SQL Data Source

Data Source Property Name	Description
Description	Description of the data source.
JDBC Data Source	The JNDI name of a JDBC data source. See "Configuring Data Access for Oracle Real-Time Decisions" in Oracle Fusion Middleware Administrator's Guide for Oracle Real-Time Decisions for information about how to create a new data source.
Table Name	The name of the table. This name is case sensitive when using a case sensitive database.
Output Column Name	The columns to select from the data source.
Output Type	Data type of the output column.
Input Column Name	The columns used in the WHERE clause of the query to the data source. This is the column or columns you will match on in order to select data from the data source.
Input Type	Data type of the input column.
Allow multiple rows	Allows multiple rows to be returned. If this option is not selected and multiple rows are returned, only the first one is used.
Advanced	The Advanced button lets you choose to show the element in Decision Center and change the label of the element. Changing the label of the element does not change the Object ID.

13.5.2.2 Adding Columns to the Data Source

Click Add or Remove to add or remove columns from the data source. If you expect more than one row, select Allow Multiple Rows. If you do not select this option and multiple rows are returned, only the first will be used.

13.5.2.3 Importing Database Column Names

Click Import to connect to a JDBC data source in order to display the available tables. If you have not yet created additional JDBC data sources (as described in "Configuring Data Access for Oracle Real-Time Decisions" in Oracle Fusion Middleware Administrator's Guide for Oracle Real-Time Decisions), only the SDDS JDBC data source will be selectable.

Configure Oracle RTD and create a domain using the Configuration Wizard. See "Configuring Data Access for Oracle Real-Time Decisions" in Oracle Fusion Middleware Administrator's Guide for Oracle Real-Time Decisions. For the purposes of this configuration, follow the steps for configuring Oracle RTD after a Software Only install.

Select Include objects from all schemas to display all tables accessible to the database user specified in the JDBC connection. The accessible schemas are displayed in a separate column.

Choose the table you want to import, and the column names and data types of those columns are imported. If there are columns you do not need, click Remove to remove them.

13.5.2.4 Setting the Input Column

The Input column is the column you will match on the database table to retrieve the rows needed for the session. Most likely, this will be a value of the primary key or a unique index column to return a single record. Otherwise, if you need larger result sets, it may be a non-unique indexed column. Choose the attribute on which you want to match by clicking Add.

13.5.3 Creating Stored Procedure Data Sources

This section describes how to create a stored procedure data source. This section contains the following topics:

• Section 13.5.3.1, "Stored Procedure Data Source Characteristics"

• Section 13.5.3.2, "Importing Stored Procedure Parameters"

• Section 13.5.3.3, "Adding Attributes to the Data Source"

• Section 13.5.3.4, "Adding Result Sets to the Data Source"

13.5.3.1 Stored Procedure Data Source Characteristics

Table 13-6 lists the properties of a stored procedure data source.

Table 13-6 Properties of a Stored Procedure Data Source

Data Source Property Name	Description
Description	Description of the data source.
JDBC Data Source	The JNDI name of a JDBC data source
Procedure Name	The name of the stored procedure. This name is always case insensitive, even when the database itself is case sensitive.
Inputs and Outputs	Input and output parameters for the stored procedure. Each Input and Output has a Name, a Type, and a Direction.
Result Sets	The result sets from the stored procedure.
Allow multiple rows	Allows multiple rows to be returned. If this option is not selected, and multiple rows are returned, only the first is used.
Result Set Details	The column names and type of the results expected.
Advanced	The Advanced button lets you choose to show the element in Decision Center and to change the label of the element. Changing the label of the element does not change the Object ID.

13.5.3.2 Importing Stored Procedure Parameters

Click Import to connect directly to the data source. All of the stored procedures for the specified data source will be shown. If no data source is specified, the default data source SDDS is used.

Select Include objects from all schemas to display stored procedures in all the data source schemas.

Choose the stored procedure that you want to import, and the parameter names and data types of those parameters are imported, to become attributes of the data source, then click Finish. If there are parameters that you do not need, click Remove to remove them.

13.5.3.3 Adding Attributes to the Data Source

Click Add or Remove to add or remove attributes from the data source. Choose whether the attribute is an Input, Output, or Input/Output.

Attributes must be ordered. Use Up or Down to order the attributes.

13.5.3.4 Adding Result Sets to the Data Source

If the stored procedure has one or more result sets, perform the following steps for each result set:

1. Click the Result Sets Add button to add a result set to the data source.

2. Use the Result Set Details Add button to add the column names and types of the result set.

   You must manually enter the column names and data types to match the columns in the stored procedure result set, as follows:

   • The column names in the data source must be exactly the same as the column names in the result set

   • The data types in the data source must be valid for the corresponding data types in the result set

     For example, for VARCHAR or VARCHAR2 result set columns, enter String for the corresponding data source column data types. For FLOAT columns from SQL Server or Oracle stored procedures, and REAL columns from DB2 stored procedures, enter Double for the corresponding data source column data types.

13.5.3.5 Examples of Setting Up Data Sources from Stored Procedures

Appendix C, "Examples of Data Sources from Stored Procedures" shows examples of setting up data sources from Oracle, SQL Server, and DB2 databases, and creating entities that derive their attributes from these data sources.

13.5.4 Accessing Oracle Business Intelligence Enterprise Edition Data

Oracle Business Intelligence Enterprise Edition exposes an ODBC client interface for accessing data stored in OLTP and OLAP databases. The RTD Decision Service uses the JDBC-ODBC bridge included in Java Runtime Environment (JRE) to connect to the ODBC driver provided by Oracle Business Intelligence Enterprise Edition.

From the RTD Decision Service point of view, Oracle Business Intelligence Enterprise Edition is a SQL data source similar to a regular database. Subject areas in Oracle Business Intelligence Enterprise Edition are treated as database tables by the Inline Service. Column names are compound, combining two levels of the presentation object hierarchy.

See "Configuring Data Access for Oracle Real-Time Decisions" in Oracle Fusion Middleware Administrator's Guide for Oracle Real-Time Decisions for information about how to add a JDBC data source that can be accessed by a Decision Studio data source.

13.6 Forming Entities

An Entity is a set of named attributes and methods to access those attributes. One attribute is usually designated as the Entity's key. For example, a simple customer Entity might look as follows:

Customer

customerId: string, key
name: string
age: integer
accounts: collection of Account entities

In this Entity, the customerId is the key of the Entity, name and age are simple attributes, and accounts is a collection of Account entities that has been associated under the Customer header.

This section contains the following topics:

• Section 13.6.1, "About the Session Entity"

• Section 13.6.2, "Creating Entities"

• Section 13.6.3, "Adding Attributes and Keys to the Entity"

• Section 13.6.4, "Importing Attributes From a Data Source"

• Section 13.6.5, "Using Attributes for Analysis"

• Section 13.6.6, "Decision Center Display"

• Section 13.6.7, "Adding a Session Key"

• Section 13.6.8, "Adding Attributes to the Session"

• Section 13.6.9, "Mapping Attributes to Data Sources"

• Section 13.6.10, "One-to-Many Relationships"

• Section 13.6.11, "Adding Imported Java Classes"

• Section 13.6.12, "Session Logic"

• Section 13.6.13, "Session APIs"

• Section 13.6.14, "Entity APIs"

• Section 13.6.15, "About Entity Classes"

• Section 13.6.16, "Referencing Entities in Oracle RTD Logic"

• Section 13.6.17, "Adding Entity Keys"

• Section 13.6.18, "Accessing Entity Attributes"

• Section 13.6.19, "Resetting and Filling an Entity"

• Section 13.6.20, "About Cached Entities"

• Section 13.6.21, "Enhanced Entity Attribute Logging"

13.6.1 About the Session Entity

The Session entity is a specialized Entity that is automatically created for every Inline Service.

The Session entity identifies which attributes are available in memory to the Inline Service for the life of a specific front end interaction. Those attributes can be comprised of an Entity, such as Customer, as well as attributes that are set by some other source, such as a calculation derived from a function. A Session object is used to store information for a user session. Attributes stored in a session are available throughout the Inline Service, and are destroyed when the session is closed.

Sessions are closed either explicitly by an Integration Point, or when the session times out.

13.6.1.1 About Session Keys

A session key is a field passed in the request that identifies an instance of a Real-Time Decision Server server-resident Session object that will be available to the Integration Points.

As an example of using sessions, consider a client Web application, where each request supplies the CustomerId of the Web application as the session key. When the first request arrives with a new CustomerId, Real-Time Decision Server notices that this session key is new, and consequently creates a new Session object and makes it available to the Integration Point as it executes the request. Any subsequent requests using the original CustomerId will access the original Session object.

The processing of the Integration Points may implicitly or explicitly save information in the session, so that it will be available to subsequently invoked Integration Points.

13.6.2 Creating Entities

Entities are defined using Decision Studio. Entity names must begin with an uppercase letter. Entities are defined with the following characteristics:

• Description: Description of the entity as entered in Decision Studio.

• Key: A unique ID for the entity. Click Add Key to add a key to an entity.

There are also properties for entity attributes. These attribute properties are listed in Table 13-7.

Table 13-7 Entity Attribute Properties

Entity Attribute Property Name	Description
Description	Description of the attribute as entered in Decision Studio.
Type	Attribute types are either primitive types, Java classes, Entity types, Choices, or Choice Groups.
Array	Whether single-valued, or a collection.
Type Restriction	If you want to use an entity attribute in a rule, you can select a Type Restriction for the attribute. This is not a mandatory requirement, but it will help you in formulating the rule. For more information about creating and using type restrictions, see Section 13.19, "About Type Restrictions."
Default Value	The default value, which can be a constant, a function, or a reference to an attribute.
Use for analysis	Select this option to use this attribute for analysis within the predictive model. By default, this is set to True.
Category	The category of the attribute. Categories help organize the display of attributes in Decision Center.
Analysis options	Additional analysis options are available for Date attributes. To use Dates for analysis, specify the pattern you are interested in analyzing. The effect of month, day of month, day of week, and time of day can be analyzed separately, or in any combination.

13.6.3 Adding Attributes and Keys to the Entity

Click Add Attribute or Add Key to add attributes to the Entity. If the attribute is a collection, select the Array column.

Caution:

When adding a Key attribute, the data type will automatically be String. If the data type of your data source column or output parameter is a type other than String, use a transformation function when you set the input on the data source.

13.6.4 Importing Attributes From a Data Source

To automatically add all of the output columns of a data source as Entity attributes, click Import, then choose a data source from which to import. If you would like to import from more than one data source, repeat the procedure. Click Remove to remove any unwanted attributes.

When using Import, select Build data mappings for selected data source to automatically map the attributes to the data source. If the entity is nested (for example, in a one-to-many relationship) and the attributes are mapped indirectly, deselect this option.

Note:

While the Build data mappings for selected data source functionality maps the entity attributes to the data columns, users may still assign input values under the Data Source input values section of the Entity editor.

13.6.5 Using Attributes for Analysis

Select Use for Analysis to have the attribute added to the analytical model.

By default, the Use for Analysis option for each entity attribute will be set to true, and will be used as an input to Oracle RTD's models. If this is not desired, users may explicitly uncheck this option. Right click the desired attribute and select Properties to access this setting.

A common example of when to uncheck this option is when the attribute itself is not useful for modeling, but rather is used in a function that calculates the value of another attribute.

Note:

Be careful of attributes whose values may be nulls or empty strings.

Nulls are not sent to the learning model, nor used for computing predictions, and, for standard non-partitioned attributes, do not appear in Decision Center reports.

Nulls should only be used where data values are unknown, and not serving as special-case pseudo-values. For example, a value of null for an attribute Number_of_children should mean that the number of children is unknown, whereas a value of 0 should mean that the number of children is known to be 0.

Empty strings, although sent to the learning model, produce no meaningful predictions, and appear as "NOT KNOWN" in Decision Center reports. Oracle recommends that empty strings are not used with Oracle RTD models.

13.6.6 Decision Center Display

The option Show in Decision Center is selected by default. Deselect this option if you want the attribute to be hidden from Decision Center users. If desired, choose a Category to control the display of the attribute in Decision Center. Right click the desired attribute and select Properties to access these settings.

See also the Note about nulls and empty strings in Section 13.6.5, "Using Attributes for Analysis."

13.6.7 Adding a Session Key

If the session key value that you choose to use is an attribute of an entity, first add the entity to the session. To do this, click Add attribute in the session entity, and add the entity as a new attribute of that entity type to that session.

For instance, assume you want to make the session key the customerId attribute from the Customer entity. Click Add Attribute, then add an attribute to the session called customer. The type of this attribute is an entity type, namely Customer.

To access the entity types, use the dropdown list on the Type column and choose Others. The Type window appears. Choose the Entity Type for this attribute.

To add the session key, click Select from Session Keys from Dependent Entities. All key values from entities that are attributes of the session are available to be chosen as a key value for the session. Choose the key on which you want to base the session, in this instance customerId.

Note:

The keys of cached entities cannot be used as session keys. For more information about caching an entity, see Section 13.6.20, "About Cached Entities."

13.6.8 Adding Attributes to the Session

Click Add Attribute to add an attribute that you want to make available for the entire session. Both session attributes and other Entity attributes have getters and setters generated for them. This allows configurators to use them in custom logic they create.

13.6.9 Mapping Attributes to Data Sources

After creating an entity using Decision Studio, map the attributes of the entity to values that are either constant, calculated, a reference to an attribute of a data source, or to the session key.

Mapping to configured data sources is done through the Mapping tab of the entity object. To map the attributes of an entity to a data source, use the Source column to choose the path to the data source column or output parameter that will supply the attribute with data.

To map the key value, click Input Value from Data Source Input Values. Your key value will appear here when you map the attributes to data source values. You can map the key to a session key attribute, to another entity key value, or to a function. The input type must be of type String. If it is not, use a function to transform the non-string value.

13.6.10 One-to-Many Relationships

To access data in an Entity in a one-to-many foreign key relationship, make the related Entity an attribute of the first Entity. For example, say that the Customers table has a key, CustomerID. Customers have many Orders, which are identified by OrderID and a foreign key CustomerID.

Figure 13-2 Entity Mapping Example

Description of "Figure 13-2 Entity Mapping Example"

To access data in an Entity in a one-to-many foreign key relationship, using Customers and Orders as an example, perform the following steps:

Note:

In this example, it is assumed that there is a CustomerID foreign key on the order table. This CustomerID serves as the input column to the Orders data source. The Orders data sources would also have its Allow Multiple Rows setting set to true.

1. In Decision Studio, define a data source for each of these tables.

2. Create an entity for Customers and Orders.

3. Add Customer to the session, as that is the key to retrieving the next level of data.

4. Choose CustomerID as the session key.

5. To associate the one-to-many relationship between Orders and Customers, add an attribute to Customer called Orders, of entity type Orders. Since there are many Orders for one Customer, make it an array.

6. You can map all of the attribute values for both the Customer entity and the Orders entity through the Customer entity mapping tab.

13.6.11 Adding Imported Java Classes

To add imported Java classes to your Inline Service, click Advanced next to the description.

13.6.12 Session Logic

The session element can accept scriptlets that are executed on initialization and exit of the session. The cleanup scriptlet is executed when the session is closed.

13.6.13 Session APIs

The following code returns the Object label and ID, respectively:

public String getSDOLabel();
public String getSDOId();

You can use session() to access the other entities of the Inline Service. For example:

session().getCustomer().getCustomerId();

where Customer is an entity and customerId is an attribute of that entity.

Use session() to access the instance of the application session. Session has the following APIs available:

public boolean isTemporary();

If no session keys have been passed in, the session is considered temporary.

The following code is used to access an Integration Point request outside of the Integration Point and returns the current request:

public IntegrationPointRequestInterface getRequest();

The following code returns whether the current instance of the session has been closed:

boolean isClosed();

The following code returns any known session keys. This may or may not be the complete set, depending on where it is called.

Set getKeys();

The following code closes the current session instance:

public void close();

The following code gets the application object of the current session:

public ApplicationInterface getApp();

13.6.14 Entity APIs

The following code returns the Object label and Id, respectively:

public String getSDOLabel();
public String getSDOId();

13.6.15 About Entity Classes

In addition to the normal classes generated, an array class is also generated for each Entity. The generated classes have a property, getter, and setter for each attribute. Hence, the definition of entities such as Customer, Account, and Call will result in classes with these names, as well as another class, representing a collection of that class.

For instance, for the Account entity, the following two classes are generated:

Account
SDAccountArray

The second class represents a collection of Accounts. So, when our Customer entity has an attribute named accounts of type Account (with multiplicity set to multiple), then the following gets generated for Customer:

Customer  {
SDAccountArray getAccounts() {
  }
void setAccounts(SDAccountArray accounts) {
  }
void addToAccounts(Account account) {
  }
}

13.6.16 Referencing Entities in Oracle RTD Logic

Because a class is generated for each Entity type, you create an Entity with the new operator as you would any Java object. For example:

Customer cust = new Customer();

Optionally, if the Entity is the child of another Entity, pass in the name of the parent Entity. Session can be a parent Entity of any other Entity.

Customer cust = new Customer(entityParent);

13.6.17 Adding Entity Keys

Most Entities are not very useful unless they have a value for the key attribute. The key attribute, as with any attribute, is set using a generated setter:

Customer cust = new Customer();
String newKey = '12345';
cust.setCustomerId(newKey);

13.6.18 Accessing Entity Attributes

As mentioned previously, getters are generated for each attribute. The form of the getter depends on whether the attribute has one value or more than one value. The sample Customer entity would have the following getters:

String id = cust.getCustomerId();
String name = cust.getName();
double age = cust.getAge();
Collection accounts = cust.getAccounts();

Corresponding setters are also generated. We have already seen the setter for customerId, but here are the others for our Customer example:

cust.setName("Fred Johnson");
cust.setAge(42);
cust.setAccounts(newCollection);

And, because Accounts is an attribute that has multiple values, you can also add to the collection:

cust.addToAccounts(anotherAccountObject);

An array can be added using:

cust.addAllAccounts(anotherAccountArray);

13.6.19 Resetting and Filling an Entity

Three special methods are provided to reset and to fill an Entity.

cust.reset();

Resets all keys except session keys and all attributes.

cust.resetAttributes();

Resets all attributes, but does not reset keys.

cust.fill();

Fill recursively fills the values of the attributes according to the Entity mapping, forcing it to refresh the data through the data source, calculated or constant value. Any attributes of Entity type are also filled.

Reset and fill should not be called on cached entities.

13.6.20 About Cached Entities

Entities can be cached on the server so that they are easily accessible. To cache entities, click the Cache tab of the entity.

Entities can have the following caching options:

• Enable caching for this entity type: Select this option to enable caching. Cached entities are treated exactly like non-cached entities and have the same API, except that cached entity keys may not be used as session keys.

• Max number of items to cache: The maximum number of items to cache. Items are flushed in a first in/first out manner.

In addition, entities can have the following caching strategy options:

• Use fixed lifetime: Number of seconds each object stays in cache before being refreshed.

• Use fixed period: Number of seconds before the entire cache is refreshed.

• Never refresh cache: Cached items stay in cache until the maximum number is reached.

If an entity is marked for caching, use the following code to set the attributes. Once you create the entity, set the key values and then get the attribute values from the cache. Cached entity attributes (other than the key) do not have setters. This keeps the entity in sync with the cached version.

Customer cust = new Customer();
String newKey = '12345';
cust.setCustomerId(newKey);
cust.getCustomerId();
cust.getName();
cust.getAge();
cust.getAccounts();

13.6.21 Enhanced Entity Attribute Logging

Problem

For debugging and logging requirements, developers must write a series of log statements, for example, using logDebug or logInfo, in order to examine the current values for the Oracle RTD entities they are setting. Typically, a minimum of one line of code is required for each entity attribute whose value should be output to the Oracle RTD log. This results in a large number of lines of code simply to log output.

Solution

A predefined API in the Oracle RTD platform that allows a user to output to the Oracle RTD log the value of all session entity attributes or of a specified entity and its attributes. The output is at all the log levels: Info, Debug, Error, Warning, and Trace.

General Form of the API

Notes:

1. In this section, only the logInfo command is specified. All the enhanced logging options apply also to the commands logDebug, logError, LogWarning, and logTrace.

2. For simplicity, for each logging option, only the essential "active" parameter is shown. You can concatenate extra textual information into each parameter for more informative logging messages.

To log all the attributes of a session:

• logInfo(session());

To log all the attributes of an entity, which must be a session attribute:

• logInfo (session().getEntity_id());

The output of the API displays the Entity Name, Attribute Name, and Value in the following format:

Entity > ExternalName: <label> ; InternalName: <id> ; Attribute <n> Name: <attribute_name>; Type: <attribute_type>; Value: <value> or [<list_of_array_values>];

Example

An Inline Service session entity has two attributes:

• customer (Customer)

• customer id (Integer)

The customer is an entity which has three attributes:

• assets (String array)

• productId (String array)

• unfilled (String)

The following line:

logInfo(session());

generates output similar to the following in the Test > Log tab of the Inline Service:

Entity > ExternalName: ; InternalName: ApplicationSession; Attribute 1> Name: customer; Type: Customer; Value:

Entity > ExternalName: Customer; InternalName: Customer; Attribute 1> Name: assets; Type: SDStringArray; Value: [1, 7, 8, 9, 9, null];

Entity > ExternalName: Customer; InternalName: Customer; Attribute 2> Name: productId; Type: SDStringArray; Value: [1, 7, 8, 9, 1];

Entity > ExternalName: Customer; InternalName: Customer; Attribute 3> Name: unfilled; Type: String; Value: <unfilled>;

Entity > ExternalName: ; InternalName: ApplicationSession; Attribute 2> Name: customerId; Type: int; Value: 2;

13.7 Performance Goals

In designing a decision process for an organization, first consider the specific metrics that the organization wants to improve by way of implementing Oracle RTD. Two common performance metrics are:

• Revenue per customer visit on a Web site

• Servicing costs per customer call in a contact center

The performance metrics are configured with an optimization direction (maximize or minimize) and a normalization factor.

Performance goals have the following characteristics:

• Performance metric: Metrics with which the organization has chosen to measure the success of Decisions.

• Optimization: A value, Minimize or Maximize, that indicates the direction in which to optimize the performance metric.

• Required: Check if scoring for the performance metric is required. If a metric is not marked required, and a score is not available through lack of data, Oracle RTD can provide a score by examining other scores. If it is marked required, a general score will not be provided and the metric is marked not available and dropped from the scoring process.

• Normalization factor: The relative value to the organization of this performance metric.

This section contains the following topics:

• Section 13.7.1, "Adding a Performance Metric"

• Section 13.7.2, "Calculating a Normalization Factor"

13.7.1 Adding a Performance Metric

After selecting the Performance Goals element, click Add to add performance metrics. Add a metric (for example, revenue), an optimization direction (maximize), and whether the metric is required to have scores available for a decision to be made.

After you have added all of your metrics, you must decide on the normalization factor.

13.7.2 Calculating a Normalization Factor

In order to let Inline Service developers and business users express scoring functions for their Performance Goals that have different natural measuring scales, Oracle RTD requires Inline Service developers to normalize Performance Goals by way of Normalization Factors.

In the definition of Performance Goals, one Normalization Factor is applied to each Performance Goal. Subsequently, these Performance Goals are selected to be used in one or more Decisions. As a result of score normalization, business users can change the relative weights applied to the Performance Goals for their Decisions. Note that the weights themselves are expressed as percentages between 0 and 100.

In general, a higher number is better, so choose to Maximize scores with respect to each goal. For goals where lower scores are better, such as Risk or Expense, then choose Minimize.

Considerations for Normalization

In some business areas, it may be possible to have one common single metric across Performance Goals. In general, where different Performance Goals have different units of measure and magnitude, then, without some degree of normalization across Performance Goals, one Performance Goal could unexpectedly affect the outcome of scoring and the outcome of Decisions.

The Oracle RTD approach is to let business users express scores using semantics that are specific to each Performance Goal.

Normalization Example

The following example with two Performance Goals illustrates why normalizing scores is important. Assume the following:

• The Performance Goals are Revenue and Likelihood.

• The measurement units for Revenue are monetary amounts between $0 and $1000, and for Likelihoods, numbers between 0 and 100.

• The average Revenue per sale is $500.

• The business wants to balance the relative importance of presenting offers that are Revenue generating with offers that are of high interest to the customer.

  For example, business users may be ready to linearly trade 100% of likelihood for every incremental $500 in revenue. In other words, they would consider presenting an offer which is 10% less likely to be accepted than one that would bring $50 more in Revenue.

To achieve this balance without using normalization factors, the following weights would need to be applied in the Decision:

• Weight for Revenue = 1/500 = 0.002

• Weight for Likelihood = 1 – (1/500) = 0.998

Applying such weights would be quite difficult to manage as small increments in weight would drastically change the outcome of Decisions. The key factors in this design are the following:

• Revenue and Likelihood use different natural measuring scale units

• Business users want to express how those two units need to be compared at the point of Decision

Therefore, in this case, a Normalization Factor should be applied.

To achieve equal importance for Likelihood and Revenue scores, define a linear normalization factor of 500 for Revenue, and 1 for Likelihood. For Decisions, set the weights for both Revenue and Likelihood to 0.5.

General Design Factors

It is important for Inline Service developers to understand that they should perform the normalization of their Performance Goals. This normalization can be implemented in two ways:

• A linear normalization is applied when setting Normalization Factors for each Performance Goal

• For some scoring functions a linear scale factor may not be sufficient. For example, if Revenue fell between $1500 and $1650, then it might be appropriate to define a custom scoring function to use in place of the normalization factor.

The Required flag for a Performance Goal indicates whether an actual value is required for Decisions to proceed:

• If this flag is set to True, a score for this Performance Goal is required for each eligible choice.

  When no such value can be found for a Choice, that is, the score is NaN, a random score will be generated.

• If this flag is set to False, a score for this Performance Goal is not required for each eligible choice.

  When no such value can be found for a Choice Score, that is, the score is NaN, this Performance Goal for the Choice is ignored and the weights of the other Performance Goals participating in the Decisions are adjusted by equally distributing the weight of the Performance Goal marked as not required.

Note:

In the context of Externalized Performance Goals and their weighting, it is the responsibility of Inline Service developers to normalize the weights themselves.

13.8 Choice Groups and Choices

Choices are the objects evaluated during the decision process> They can also be the targets of study for modeling a business process. When used in the decision process, the best "choices" from a list of candidate Choices are returned through an Advisor call. Examples of Choices in a decision process include:

• List of marketing offers from which to select

• List of products to recommend

• List of resources for a task

Choices can be organized into Choices Groups. Choice Groups and Choices are organized into a hierarchical tree like representation, where one parent Choice Group can have multiple child Choice Groups. The selection of Choices from a list of candidate Choices, that is, the decision process, is a step by step operation following this logic:

1. Eligibility: A set of rules that determines whether or not a Choice should be considered for a given Decision. Eligibility rules can be defined at each level of the Choice Group and Choice hierarchy.

2. Scoring: The computation of scores along each Performance Goal defined for the Decision.

3. Normalization: Brings the scores along the different performance metrics to a common scale that enables the comparison of scores.

4. Totaling: Produces a single number for each Choice. This number is a weighted sum of the normalized scores for each Performance Goal for the Segment to which the Decision applies.

5. Selection: Selects a set number of "best" Choices based on Choice total score.

Choices can either be Static or Dynamic.

With Static Choices, the Choices to present to the requesting application or self-learning model are completely defined within Oracle RTD. Static Choices are useful in cases where the Choices are known in advance, and are constant over a period of time.

Dynamic Choices are Choices that are built dynamically at run time. These Choices typically reside in external data sources. This allows for the management of Choices to be done at the source system, such as Choices based on offers defined in an offer management system.

Note:

Choice Groups are always Static, that is, defined in an Oracle RTD Inline Service.

This section describes the general features and processes applicable to Choice Groups and to both Static and Dynamic Choices. For information specific to Dynamic Choices, see Chapter 17, "Externalized Objects Management."

This section contains the following topics:

• Section 13.8.1, "About Choice Groups and Choices"

• Section 13.8.2, "About Choice Group and Choice Attributes"

• Section 13.8.3, "Choice Attribute Characteristics"

• Section 13.8.4, "About Choice Scoring"

• Section 13.8.5, "About Eligibility Rules"

• Section 13.8.6, "Evaluating Choice Group Rules and Choice Eligibility Rules"

• Section 13.8.7, "Determining Eligibility"

• Section 13.8.8, "Choice Group APIs"

• Section 13.8.9, "Choice APIs"

13.8.1 About Choice Groups and Choices

Choice Groups and Choices have the following characteristics:

• Attributes: The attributes that make up the choice. These can be inherited from the parent Choice Group, or assigned at the Choice level.

• Scores: Each choice will be scored according to the definition in the Scores tab. Choices are scored against all of the performance metrics that are defined for a given Decision.

• Choice Events: Choice events are only described at the Group level. These events identify important events in a Choice lifecycle. For instance, a Cross Selling Offer made may have events such as Offered, Accepted, and Product First Used.

• Rules: Two types of Rule can be applied to Choices, both of which can be created and modified by Decision Center users:

  • Eligibility rules govern the conditions under which Choices are considered for a Decision. Eligibility rules can be defined at any level of the Choice Group hierarchy. Choices inherit all the Eligibility conditions defined at a higher level of the hierarchy.

  • Scoring rules can be used to associate numeric scores to Choices. Those scores can be used as part of the Performance Goal scoring logic or as attributes of Choices.

  Scoring rules are defined as separate elements and are applied to the relevant choice, whereas eligibility rules are defined directly at the Choice Group or Choice level.

• Advanced: The Advanced button lets you choose to show the element in Decision Center, and to change the label of the element. Changing the label of the element does not change the Object ID.

13.8.2 About Choice Group and Choice Attributes

Choice Group attributes are used to define attributes at the group level. Group attributes apply only at the Choice Group level, and so are not assignable for individual Choices.

Choice attributes are defined at the Choice Group level to ensure that each Choice in a Group has the same set of attributes. Choice attribute values are individually defined at the Choice level. Choice attributes may have default values that can be set and overridden at lower levels.

Choice Groups and Choices are defined hierarchically. The hierarchy should follow the logical taxonomy of the Choices. At the top level, it is necessary to consider the definition of Choice attributes that make sense for a whole subtree. At lower levels, the shape of the hierarchy is typically determined by organizational considerations.

Choice attributes are typically defined at the higher levels of the hierarchy. Some attributes have a default value that may be marked as non-overrideable, which means that the value provided by default is the value that will be used. This is typically done when computations are involved. This is useful when you do not want a business user to update the attribute after deployment.

Choice attribute values can be one of the following:

• A constant

• An attribute or variable

• A function or rule call

• A model prediction

Figure 13-3 shows an example of a choice group as configured in the CrossSell Inline Service.

Figure 13-3 Example Choice Group

The Choice attributes set at the Offers level for this example are shown in Table 13-8.

Table 13-8 Choice Attributes Set at the Offers Level for Offers Choice Group Example

Attribute	Type	Value
Message	String	No default value. Values assigned at Choice level for each Choice.
shouldRespondPositively	Boolean	The function ShouldRespondPositively() that returns a Boolean value about whether a customer will respond positively to a given Choice. This specific function is used in the context of the loadgen simulator.
Likelihood of Purchase	Double	A placeholder attribute that is assigned by the choice model or choice event model where this choice group is registered. Used for likelihood that the choice will be purchased. There is no default value as this is calculated at run time.
Profit Margin	Double	An indicator of the profitability of the offer represented as a percentage. Default value of 0.5. Values assigned at Choice level for each Choice.

Each Choice overrides the Profit Margin and Message values with a value that is indicative of that Choice. However, the default value will be available at run time in case the server cannot respond in an effective time period.

No Choices override the shouldRespondPositively attribute, as they all use the same function to determine that value. The Likelihood of Purchase is calculated by the model for each Choice at run time.

13.8.3 Choice Attribute Characteristics

Choice attributes have the following characteristics:

• Name: The name of the attribute.

• Category: The category to which the attribute belongs. Categories are defined by the Category element.

• Type: Data type of the attribute.

• Array: Whether the attribute is a collection.

• Type Restriction: If you want to use a choice attribute or a choice group attribute in a rule, you can select a Type Restriction for the attribute. This is not a mandatory requirement, but it will help you in formulating the rule. For more information about creating and using type restrictions, see Section 13.19, "About Type Restrictions."

• Inherited Value: The value, if any, that the Choice Group or Choice attribute has inherited from its parent.

• Value: The value of the attribute. This value always overrides an inherited value.

• Show in Decision Center: Select this option to make the attribute visible to business users in Decision Center. Deselect for internally used attributes.

  See also the Note about nulls and empty strings in Section 13.6.5, "Using Attributes for Analysis."

• Use for indexing: Select this option if you want to be able to look up the Choice by the attribute specified. For example, assume you have a choice attribute called name. A static method is generated on the Choice Group called getChoiceWithName(String name). This method returns a choice.

  When selecting this option, the value for this attribute must be unique across all the choices.

• Send to client: Select this option if the attribute will be sent to the outside client calling the Inline Service that returns this choice.

To add or remove Choice attributes, click Add or Remove.

To edit a Choice attribute, right-click the attribute and choose Properties. You can only edit Choice attributes at the highest level that they are defined.

13.8.4 About Choice Scoring

Choices inherit scoring functions from their parents. In scoring a Choice, you identify the performance metrics that apply to that Choice and then apply a scoring method to it. Scoring methods can be a scoring rule, function, constant, or the likelihood of an event occurring on a Choice Event Model.

For instance, assuming the Choice Group structure shown in Figure 13-3, some of the Choices may have scoring similar to the following:

• Mileage Plus Card

  • Performance Metric: Increase Revenue

  • Score: A function that uses the likelihood of the customer to accept the offer and the expected profit margin of the card to calculate the revenue potential of the offer. The likelihood is computed by a model.

• Gold Card

  • Performance Metric: Increase Revenue

  • Score: An inherited constant from the choice group level.

• Credit Analysis

  • Performance Metric: Increase Customer Retention

  • Score: A scoring rule that uses customer data to assign a score.

Note:

The value of a score, as defined in the Score column of the Scores tab for a Choice or Choice group, can be any real value, that is, positive, negative, or zero.

13.8.5 About Eligibility Rules

Eligibility rules are available at the Choice Group level and at the Choice level as follows:

• Choice Groups may have Choice Eligibility rules and Group Eligibility rules, located respectively on the Choice Eligibility and Group Eligibility tabs of the Choice Group editor.

  The Group Eligibility rules for Choice Groups are eligibility rules that apply to attributes defined at the Choice Group level.

  The Choice Eligibility rules for Choice Groups generically apply to attributes of choices defined in this Choice Group.

• Choices may have Choice Eligibility rules, located on the Eligibility Rule tab of the Choice editor.

These rules for Choices and Choice Groups determine their eligibility to participate in the decision. Eligibility rules determine whether the Choice is eligible to participate in the selection function or rule of the Decision or logic that makes the Choice selection.

Eligibility rules determine whether the subtree headed by a Choice Group or a Choice is eligible for a decision. Note that even if Choices themselves are eligible, they will not be eligible unless all their ancestors are eligible.

See Section 13.11, "Using Rule Editors" for information about how to use the editors for these rules.

13.8.6 Evaluating Choice Group Rules and Choice Eligibility Rules

Choice Group rules and Choice rules are inherited and additive. That is, if there are rules at the Choice Group (Group and Choice rule) and rules at the Choice level, it is as if there is a logical AND extending the rules. The inherited rules are shown in an expandable section at the top of the rule labeled Inherited eligibility conditions. Use the Move Rule icons to expand and collapse the sections:

The following example illustrates the interaction between Choice Group rules and Choice rules:

Group1 has rules GroupRule1 and ChoiceRule1
Group2 is a child of Group1 and has rules GroupRule2 and ChoiceRule2
Group2 has a Choice, Choice1, and it has a rule, Rule1

In evaluating the rules for Choice1, the rules will be invoked in the following order:

GroupRule1 AND GroupRule2 AND ChoiceRule1 AND ChoiceRule2 AND Rule1

13.8.7 Determining Eligibility

When determining eligibility for a Choice, parent eligibility is tested first, to avoid the unnecessary evaluation of eligibility rules on Choices.

13.8.8 Choice Group APIs

The following code returns the Object label and Id, respectively:

public String getSDOLabel();
public String getSDOId();

The following code returns a Choice object from the Choice Group:

public Choice getChoice(String internalNameOfChoice);

When a Choice attribute is marked for indexing, the following method is used to return the Choice as referenced by the indexed attribute:

public Choice getChoiceWithAttributeID(AttributeType val);

13.8.9 Choice APIs

The following code returns the Object label and Id, respectively:

public String getSDOLabel();
public String getSDOId();

To get the Choice Group in which the Choice is contained, use the following code:

public ChoiceGroup getGroup();

Choice event tracking API consists of two methods defined on choices, as follows:

void recordEvent(String eventName);
void recordEvent(String eventName, String channel);

Typical code for an Integration Point recording a choice event is as follows:

String choiceName = request.getChoiceName();
String choiceOutcome = request.getChoiceOutcome();
ChoiceGroup.getChoice(choiceName).recordEvent(choiceOutcome);

Tracking of extended and accepted offers is required by many Inline Services for eligibility rules that depend on previous offers extended to, or accepted by, the same customer in the past.

Two kinds of questions, both related to a particular customer, can be answered by the Choice event history:

• How long ago was an offer extended or accepted?

• How many times was an offer extended or accepted during a given recent time period?

The answers to these questions are provided by API methods defined on Choices and Choice Groups:

int daysSinceLastEvent(String eventName);
int daysSinceLastEvent(String eventName, String channel);
int numberOfEventsDuringLastNDays(String eventName, int numberOfDays);
int numberOfEventsDuringLastNDays(String eventName, int numberOfDays, String channel);

13.9 Filtering Rules

As standalone rules, filtering rules can be used to segment population or be used as components of other rules. Standalone rules are reusable by many different elements.

A typical rule used to identify a segment of the population is shown in Figure 13-4.

Figure 13-4 Filtering Rule

Description of "Figure 13-4 Filtering Rule"

The rule shown in Figure 13-4 targets customers over the age of 18 with a credit line amount over $8000.

See Section 13.11, "Using Rule Editors" for information on editing rules.

13.10 Scoring Rules

As opposed to eligibility rules that return Boolean values, scoring rules return numeric values. These values can be used throughout the Oracle RTD Decision logic. Typical use cases are:

• Setting the score of a choice for a given performance goal

• Setting the value for a choice attribute

Scoring rules have a default value if none of the rule segments evaluate to true.

To add a value, click under Then or The value is in the Value column. Then, click the ellipsis and edit the value as you would any other rule value.

For instance, the scoring rule shown in Figure 13-5 assigns scores based on the credit line amount of a customer. If they do not fit into any of the credit line range categories, the score defaults to 3.25.

Figure 13-5 Example of Scoring Rules

Description of "Figure 13-5 Example of Scoring Rules"

Scoring rules also have the following options:

• Description: Scoring Rules can be adjusted by Decision Center users, so it is very important to describe your scoring rule adequately. It is suggested that you include the range that the score is to work over.

• Advanced: The Advanced button lets you choose to show the element in Decision Center, and to change the label of the element. Changing the label of the element does not change the Object ID.

See Section 13.11, "Using Rule Editors" for information on editing rules.

13.11 Using Rule Editors

Rules are used for several purposes within Decision Studio and Decision Center, namely:

• For determining the eligibility of Choice Groups and Choices to take part in a Decision

• As standalone, for creating filtering rules to be used to create population segments for decisioning

• As standalone, for creating scoring rules to be used for the scoring of choices

The Rule Editor toolbar provides access to features used to edit rules. Inside each rule editor, the editor toolbar provides users with the functionality required to create their rules. These functions become active based on the context of the rule creation and editing done by the user.

Figure 13-6 Rule Editor Toolbar

Description of "Figure 13-6 Rule Editor Toolbar"

From left to right, the toolbar functions are as follows:

• Edit rule properties

• Add conditional value

• Add Rule

• Add Rule Set

• Delete

• Invert

• Move up

• Move down

• Copy

• Cut

• Paste

The editors that are used to create rules are very similar. The following sections describe how to create rules using these editors.

This section contains the following topics:

• Section 13.11.1, "Oracle RTD Rule Terms and Statements"

• Section 13.11.2, "Adding Statements to Rules"

• Section 13.11.3, "Selecting an Operator"

• Section 13.11.4, "Editing Boolean Statements"

• Section 13.11.5, "Editing Rule Properties"

• Section 13.11.6, "Inverting Rule Elements"

13.11.1 Oracle RTD Rule Terms and Statements

Oracle RTD has three types of rules:

• Filtering rules

• Scoring rules

• Eligibility rules

An Oracle RTD rule consists of one of more rule conditions, with logical operators governing how the conditions are combined. These conditions are expressed in the form of rule statements, as described in the section.

Note:

This section describes rules that have conditions, that is, they are not always true.

The following is an example of a simple filtering rule, used to illustrate rule statements in this section:

• Select List Rule is true when
  All of the following
  1. session / customer / Age > 21
  2. session / customer / MaritalStatus = "MARRIED"
  

Table 13-9 shows a more formal representation of the Oracle RTD rule grammar, using BNF (Backus-Naur Form)-type conventions, which describes the terms used in Oracle RTD rule statements.

Table 13-9 Oracle RTD Rule Grammar

Term	Term Component	Notes
<rtd rule>	<header line> <logical operator> <rule entry>+ | <header line> <array operator> <logical operator> <rule entry>+	None.
<header line>	<rule name> is true when	Provides the name for the rule. After the rule is created, the header line is not editable.
<logical operator>	All of the following | Any of the following | None of the following | Not all of the following	The logical operator controls the <rule entry> immediately following. The logical operator All of the following is the default logical operator when you initially create a rule.
<rule entry>	<boolean statement> | <rule set>	Rule entries are always numbered. They may contain boolean statements or other rule entries.
<rule set>	<logical operator> <rule entry>+ | <array operator> <logical operator> <rule entry>+	The second <rule set> component option is known as an array-processing rule set.
<boolean statement>	<boolean> | <boolean function> | <left operand> <relational operator> <right operand>	The <boolean statement> is the lowest level of a rule set - it cannot be decomposed further.
<array operator>	<quantifier> <array variable> in <array name> ,	Used only for array-processing rule sets. For details, see Quantifiers and Array-Processing Rules.
<quantifier>	For all | There exists	None.

The Select List Rule example can be categorized as follows:

• Select List Rule is true when = <header line>

• All of the following = <logical operator>

The remainder of the rule consists of a <rule entry> made up of the following two statements:

• session / customer / Age > 21 = <boolean statement>

• session / customer / MaritalStatus = "MARRIED" = <boolean statement>

Rule Sets and Boolean Statements

A rule set (as denoted by <rule set> in Table 13-9) is a composite statement, that consists of one or more numbered rule entries, each of which is either a boolean statement or another rule set.

A boolean statement (as denoted by <boolean statement> in Table 13-9) contains a condition that evaluates to true or false when the rule is processed. The boolean statement is the lowest-level element of a rule set - it cannot be decomposed further.

You can optionally name the rule sets defined within higher-level rule sets.

Note:

Each Oracle RTD rule has an implicit, unnamed, top-level rule set.

Each rule set is qualified by a logical operator, which controls the processing of the rule set statements. For more information, see Logical Operators.

The following Exclusion Rule example shows a rule set within a rule set.

In the example:

• The top-level unnamed rule set contains the logical operator All of the following and two rule entries. The first rule entry is a boolean statement, the second rule entry is a rule set.

• The rule set inside the top-level rule set contains the logical operator None of the following and three rule entries, each of which is a boolean statement.

Note:

Oracle RTD also supports rule sets that depend on values in an array. For more details, see Quantifiers and Array-Processing Rules.

Logical Operators

The Oracle RTD logical operators are as follows:

• All of the following (logical and). The rule set evaluates to true when all of its boolean statements and lower-level rule sets are satisfied.

• Any of the following (logical or). The rule set evaluates to true when any one of its boolean statements or lower-level rule sets is true.

• None of the following (logical not and). The rule set evaluates to true when all of its boolean statements and lower-level rule sets are false.

• Not all of the following (logical not or). The rule set evaluates to true when any one of its boolean statements or lower-level rule sets is false.

Quantifiers and Array-Processing Rules

Rule sets may depend on values that occur in arrays, as follows:

• Rule sets can evaluate elements of an array

• An expression within a rule set can reference elements of an array

These types of rules are referred to as array-processing rules.

For these cases, there are rule sets where a "quantifier" expression - also referred to as a quantifier - qualifies the logical operator of the rule set. Either the statements of the rule set must be fulfilled for all array elements, or they must be fulfilled for at least one array element.

In the following example, a rule has been created which examines all of the agents contained in an array attribute, session/agents. In this example, the rule evaluates to true when all the agents are at least 30 years old and have a status of "Qualified."

• Agent Rule is true when
  For all people in session/agents, All of the following
  1. people / Age >= 30
  2. people / Status = "Qualified"
  

Full details of the syntax of array-processing rules appear in the section following. In the preceding example, the term people is an arbitrary term that is defined by the user and is used to identify individual array elements in the rule set.

Array-Processing Rule Qualification

The general formula for an array-processing rule qualification is:

<quantifier> <array_variable> in <array_name>, <logical_operator>

where:

quantifier is one of the following: For all, There exists

• For all. This quantifier, together with the rule set logical operator, specifies that each array element must be examined, and for each array element, all the boolean statements and lower-level rule sets in the qualified rule set must be fulfilled.

  Rule evaluation will stop processing the array as soon as one array element is found where all the boolean statements and lower-level rule sets in the qualified rule set are not fulfilled. The rest of the elements in the array will be skipped.

• There exists. This quantifier, together with the rule set logical operator, specifies that all the boolean statements and lower-level rule sets in the qualified rule set must be fulfilled for at least one array element.

  Rule evaluation will stop processing the array as soon as one array element is found where all the boolean statements and lower-level rule sets in the qualified rule set are fulfilled. The rest of the elements in the array will be skipped.

array_variable is an arbitrary name to identify individual array elements of the array array_name in the boolean statements and lower-level rule sets in the qualified rule set

Notes:

1. The array_variable can still be referenced in the boolean statements of lower-level rule sets that have their own specific array variables.

2. The array_variable must be unique within the scope of the rule, that is, you cannot use the same array_variable name as the array variable for a lower-level array-processing rule.

array_name is the array to be examined

logical_operator is one of the following: All of the following, Any of the following, None of the following, Not all of the following

As an example of an array-processing rule set, consider the two entities session and customer.

The session entity contains the following attributes:

• The Integer attribute AgentDept

• The array attribute CustInfo of type customer

The customer entity contains the following attributes:

• The Integer attribute CompSize

• The String attribute Region

You require a filtering rule to satisfy both of the following conditions:

• The value of AgentDept must be 42.

• For at least one customer in the CustInfo array, the CompSize must be > 100, and the Region must be "West."

The filtering rule could then be defined as follows (the array qualification expression is highlighted):

• Cust Rule is true when
  All of the following
  1. session / AgentDept = 42
  2. There exists some_customer in session / CustInfo, All of the following
     1. some_customer / CompSize > 100
     2. some_customer / Region = "West"
  

13.11.2 Adding Statements to Rules

Add Rule Set

To add a rule set, click the Add Rule Set icon:

If this is the first element to be created in the rule, the following statements appear in the rule:

• The default logical operator All of the following

• A rule set entry as the numbered first line in the rule, which itself contains the default logical operator All of the following

• An empty two-operand boolean statement within the newly-defined rule set

Otherwise, a new rule set entry is added as the next entry in the current rule set, containing an empty two-operand boolean statement. For example, when you add a rule set to an existing rule set that already contains one boolean statement, the added rule set entry appears beside the line number 2, as in the following:

You can name the rule set, by clicking the top right corner. When a rule set is named, you can collapse or expand the rule set, by clicking the appropriate chevron icon in the top right corner of the rule set box.

Add (Boolean Statement to) Rule

To add a boolean statement, click the Add Rule icon:

If this is the first element to be created in the rule, the default logical operator All of the following appears, followed by an empty two-operand boolean statement, as in the following:

Otherwise, an empty two-operand boolean statement is added to the current rule set, as in the following example, where one boolean statement already exists:

By default, boolean statements have two operands, with an intervening operator.

To switch between single and double operands in boolean statements, click the line number of the boolean statement, then click the arrowhead icon in the lower-right corner of the boolean statement box, as in the following example:

Single operands always evaluate to a Boolean.

13.11.3 Selecting an Operator

Click the operator, then click the lower-right corner to select an operator:

Table 13-10 lists the available operators.

Table 13-10 Rule Operators

Operator	Description
none	A simple expression that has only one operand
=	Left is equal to Right
<>	Left is not equal to Right
<	Left is less than Right
<=	Left is less than or equal to Right
>	Left is greater than Right
>=	Left is greater than or equal to Right
in	Left value is contained in a List on the Right side
not in	Left value is not contained in a List on the Right side
includes all of	Left list includes all the values of the Right list
excludes all of	Left list contains none of the values of the Right list
includes any of	Left list includes any one of the values of the Right list
does not include all of	Left list does not include all of the values of the list on the Right

13.11.4 Editing Boolean Statements

To edit the boolean statements of a rule, click the left side, then click the ellipsis. You can choose from a constant, attribute, or function call. Select Array at the top of the page to specify an array value.

Note:

Use of the Esc key at any time in an operand dialog will close the dialog.

• If you choose Constant, provide the Data type and a Value for the item. If you selected Array, add as many items to the array as needed. Then, for each item, choose a Data Type and provide a Value.

• If you choose Attribute, provide one of the following:

  • Group attribute: Attributes that are part of the Choice Group or its Choices that is selected in the Properties of the rule.

  • Session attribute: Attributes that are part of the Session entity.

  • Application attribute: Attributes that are a member of the Application element.

  • Array variable: Names used to identify individual array elements for rule sets within a quantified logical operator expression. For more information, see Quantifiers and Array-Processing Rules.

  Optionally, select Apply filter type and choose a Data type to filter the attributes by type. If you have selected Array, add as many items to the array as needed, then assign an attribute value for each.

• If you choose Function call, provide one of the following:

  • Filtering rules: Standalone filtering rules defined for the Inline Service.

  • Scoring rules: Standalone scoring rules defined for the Inline Service.

  • Function calls: Standalone functions defined for the Inline Service.

  Optionally, select Apply filter type and choose a Data type to filter the attributes by type. If you have selected Array, add as many items to the array as needed, then assign a function or rule for each.

13.11.4.1 Using Type-Restricted Objects in Rules

When you select a type-restricted object for an operand or part of an operand, you may view values from a dropdown list of values for the other operand. You may select a value from this dropdown list, but you do not have to.

For more information about type restrictions and type-restricted objects, see Section 13.19, "About Type Restrictions."

13.11.5 Editing Rule Properties

Both Filtering and Scoring rules have rule properties that can be set. To edit rule properties, click the Rule properties icon:

Edit rule properties appears.

Rule properties include call templates and negative call templates. Call templates provide a user-friendly way to describe how to call a rule from another rule.

To define a call template, add the number of parameters for the rule by clicking the Add button under Parameters. Using {0}, {1}, and so on as arguments, and phrasing to describe the rule, define the template for call. It is important to use good phrasing, as this is what will be shown when using the rule.

For instance, a rule that checks if there were at least x calls from the user in the last y days could be phrased as follows:

There were at least {0} calls in the last {1} days

The negative call template is used when a rule is inverted, and should express the opposite. For example:

There were less than {0} calls in the last {1} days

Rule properties also let you assign which Choice Group to use with the rule. By selecting Use with choice group, you can specify which Choice Group or its Choices will provide the Choice attributes for use by parameters. These attributes will be available when you edit the value of an operand.

13.11.6 Inverting Rule Elements

Use the Invert icon to invert different elements of a rule. By selecting the number of a boolean statement, you can invert the operator of the boolean statement. For instance, if the operand was =, it will be inverted to <>.

Logical operators for a rule set can also be inverted. To do this, select the logical operator and click Invert. For instance, All of the following becomes Not all of the following.

The final use for Invert is to invert a Boolean, or single operand, rule. When this type of rule is inverted, it is transformed to the negative call template of the function that defines the rule.

13.12 About Decisions

A Decision is used to select one or more Choices out of a group of eligible Choices. The most common use of a decision is within an Advisor. In an Advisor, two separate decisions can be called, one for regular processing, and another if control group functionality is being used in the Inline Service.

The setup of a Decision must include at least one Choice Group from which Choices are selected, and generally some numeric selection criteria so that Choices can be ordered.

Choices can be selected either at random, or with a custom selection function, or based on some user defined scoring logic configured at the choice group level for each associated Performance Goal.

Multiple scores can be defined for each choice using a variety of scoring techniques such as static scores or function driven values, rule based or predictive scores.

At run time, the Decision first identifies all the eligible choices in the subtree of its associated Choice Groups. Then all the eligible choices are scored (with one or multiple scores) and ordered.

Examples of scoring techniques for Choices include:

• Likelihood of interest in the Choice (as computed by an Oracle RTD self-learning predictive model)

• Business value of the Choice (as computed by a user defined rule or function)

Alternatively, a custom selection function can be written to select the choice.

Selection criteria include:

• Select Choice from: Used to assign the Choice Group or Groups that will be considered by the Decision.

• Number of Choices to Select: Indicates the maximum number of Choices that will be selected by the decision. The actual number of Choices returned at run time may be smaller or equal to this number, based on eligibility rules.

  This number can be overridden at the Advisor level, in the event where one decision is called by multiple touchpoints and each requires a different number of choices to be returned.

  The default and most commonly used number is 1.

• Radio buttons for Type of Selection: The radio button that you select controls whether you want to select a random Choice or if you want to use weighted Performance Goals as part of the Choice selection procedure:

  1. The Select with Fixed Goal Weights option enables you to specify population segments and set Performance Goal weights for each of the segments. The screen areas that appear when you select this option are:

     • Target Segments: Segment of the population that have been segmented using filtering rules. The default segment is everyone.

     • Priorities: Used to set Performance Goal weights for a given segment. The Performance Goals to use for scoring are selected in the Decision. Consequently, each specified goal must have a matching scoring method for each choice group selected for the Decision.

  2. The Select with Custom Goal Weights option allows you to have custom Performance Goal weights, typically by executing a function that returns Performance Goal weights at run time.

     If you select the Select with Custom Goal Weights option, and click the ellipsis button beside the Select with Custom Goal Weights box, you must select one of the following in the Value window:

     • Function or rule call, then a function that returns a data type of com.sigmadynamics.sdo.GoalValues

     • Attribute or variable, then an application parameter or session attribute of type com.sigmadynamics.sdo.GoalValues

  3. The Select at Random option assigns random selection of a Choice from the Choice Groups. This is often used for a Control Group Decision.

  For more information on the Select with Fixed Goal Weights and Select with Custom Goal Weights options, see Section 13.12.1, "Segmenting Population and Weighting Goals."

To add a Choice Group, click Select, then select the Choice Group or Groups to use.

To select Performance Goals for the Decision, click Goals, then select the desired goals.

This section contains the following topics:

• Section 13.12.1, "Segmenting Population and Weighting Goals"

• Section 13.12.2, "Using a Custom Selection Function"

• Section 13.12.3, "Pre/Post-Selection Logic"

• Section 13.12.4, "Selection Function APIs for Custom Goal Weights"

• Section 13.12.5, "Adding Imported Java Classes and Changing the Decision Center Display"

13.12.1 Segmenting Population and Weighting Goals

Decisions can target segments of the population and weight the performance metrics attached to that Decision for each segment.

Note:

Business users can modify Decision priorities (the weights applied to a Decision for a given segment) in Decision Center at any point throughout the lifecycle of the Decision. They can change the priorities in a Decision Center window similar to the following, which derives from the Cross Sell application released with Oracle RTD:

There are two ways that you can set up your Decision, depending on what kind of weights you want for your Performance Goals:

• Pre-defined weights, whose values are specified in the Inline Service

• Custom weights, whose values can be calculated or changed at run time

For pre-defined weights, start the decision setup process by selecting Select with Fixed Goal Weights in the Selection Criteria for your Decision.

Then, add one or more target segments, which are defined by a rule or a function, as follows:

• To add or remove a Segment, click Add and Remove.

Finally, specify a fixed percentage weight for each Performance Goal that you select for each segment, by performing the following steps for each segment:

• Click the segment.

• Click Goals to select Performance Goals to use for this Decision.

  The selected Performance Goals are shown in the Priorities area.

• Specify a Weight for each Performance Goal in the Priorities area.

For instance, consider a Decision, Select Best Offer, for an Inline Service where two Performance Goals have been defined, Customer Retention and Revenue. We have also defined a segment of the population People to retain through filtering rules. The default remainder is the segment to which we will cross sell.

The weighting is for each Performance Goal and for each segment:

• People to retain

  • Customer Retention: 90%

  • Revenue: 10%

• Default

  • Customer Retention: 20%

  • Revenue: 80%

For custom weights, start the decision setup process by selecting Select with Custom Goal Weights in the Selection Criteria for your Decision. The key feature is a function that you must write to retrieve or calculate Performance Goal weights at run time. This function must return a data type of com.sigmadynamics.sdo.GoalValues.

Terminology:

In this section, this function is referred to as the custom goal weights function.

Typically, the function would have parameters that can influence the values of the goal weights, but that is not mandatory.

Within the custom goal weights function, you do not explicitly create segments. Instead, you can include one or more conditions, each of which returns Performance Goal weights for a separate subdivision of your population.

When you set up the Decision, you can either select the custom goal weights function explicitly as the driving parameter of the process, or you can select an application parameter or entity attribute that receives the goals from the custom goal weights function or other sources.

For example, assume you have defined a condition, IsMarried, which effectively segments your target population. You have two Performance Goals Max Rev and Min Costs.

You create a function Get GoalValues, that returns a data type of com.sigmadynamics.sdo.GoalValues, and which calculates and returns the Performance Goals weights.

Note:

To illustrate the principle, the following example uses specific numbers for Performance Goals. These can be replaced by variables whose values are evaluated elsewhere in the function.

The key statements of the custom goal weights function Get GoalValues could be:

if (IsMarried)
{return new GoalValues().buildValueForMaxRev(100).buildValueForMinCosts(50);}
else
{return new GoalValues().buildValueForMaxRev(80).buildValueForMinCosts(120);}

With both pre-defined and custom weights, when the Decision is invoked, the performance metric scoring (whether function, scoring rule, function, and so on) is applied to all of the eligible Choices. Scores are leveled using the normalization factor of the performance metrics. Scores are then weighted according to performance metric weighting contained in the decision. A total score is achieved, and the Choice with the highest score is selected.

13.12.2 Using a Custom Selection Function

If, instead of using the standard scoring decision process, you would like to use a custom selection function, select the Custom selection option on the Custom Selection tab. Choose the selection function from the list, and add any parameters that the function requires.

13.12.3 Pre/Post-Selection Logic

Scriptlets in the Pre and Post Selection tab are executed before or after the scoring is done and the decision is made.

Pre-selection logic is executed after collecting all the eligible Choices, but before the selection happens. Post-selection logic is executed after the selection, but before the selected Choices are returned. Post-selection logic is more common. For example, this section can be used to record which choice Oracle RTD has recommended.

The logic here can use the variables defined for the computation of the choices. For example, the name of the Choice array, which contains eligible Choices before and selected Choices after the selection, is set in the Pre/Post Selection tab (by default, choices).

Decision returns a choiceArray. To access the individual elements, use an index into the array. The following example reads the choiceArray, and records the base event Delivered to the Choice Event Model. The method choice.recordEvent calls the model recordEvent, passing in the Choice to be recorded.

for (int i = 0; i < outputChoiceArray.size(); i++) {
  Choice choice = outputChoiceArray.get(i);
  choice.recordEvent("Delivered");
 }
 session().addAllToPresentedOffers(outputChoiceArray); /* Store presented offers for future reference */

13.12.4 Selection Function APIs for Custom Goal Weights

The type of weights parameter is GoalValues. The GoalValues class has a getValue method for each of the goals defined in the Decision. For example, given the goals CustomerRetention and Revenue, it has the following methods:

public double getValueForCustomerRetention();
public double getValueForRevenue();

13.12.5 Adding Imported Java Classes and Changing the Decision Center Display

To add imported Java classes to your Inline Service, click Advanced, next to the description. You can also change the display label for Decision Center, and choose whether the element is displayed in the Decision Center Navigator. Changing the display label does not affect the Object ID.

13.13 About Selection Functions

As an alternative to the standard scoring decision process, a selection function can be used by a Decision. Selection functions are completely user defined. However, selection functions have a well-defined signature. They take a Choice array as input, and return a Choice array as output.

Selection functions have a description, as well as the following parameters:

• Input Choice Array: The input parameter to the selection function. The data type of this variable is SDChoiceArray.

• Output Choice Array: The return variable, which specifies the name of the variable that contains the selected choices and should be returned to the caller of this selection function. The return variable can be the Input Choices Array that is passed in to this selection function, or it can be another variable defined locally within the Logic panel. The data type of this variable is SDChoiceArray.

• Number of Choices Parameter: The name of the function argument that represents the number of choices that the selection function should return. The default name of the parameter is numChoices. The data type of this argument is int.

• Weights: If goals are defined for the Decision that uses this selection function, those goals are passed to the Selection function under the parameter named in Weights. The type is a GoalValue. For more about GoalValue, see the section on Decisions.

• Extra Parameters: Any extra parameters the selection function needs.

This section contains the following topics:

• Section 13.13.1, "Selection Function Scriptlets"

• Section 13.13.2, "Adding Imported Java Classes and Changing the Decision Center Display"

13.13.1 Selection Function Scriptlets

Selection functions are used as a custom function for selection criteria. Many standard priority functions are available through templates. Priorities or selection functions are defined in Java. A set of these are predefined in the template, and usually either fill in the need, or provide an advanced prototype to modify.

Java code that does the actual selection of Choices from the list passed in as an Input Choices Array is entered in the Logic pane. Often, the Java code in the Logic section will want to refer to other classes. For the Java code and the function to compile correctly, the classes need to be imported into the function.

The execute method invokes the selection function.

A simple example of a selection function is shown in the following code sample:

double maxL = -1.0;
Choice ch = null;
for (int i = 0; i < eligibleChoices.size(); i++) {
  Cross_Selling_OfferChoice cso = (Cross_SellingOfferChoice)eligibleChoices.
get(i);
  double likelihood = cso.getLikelihood();
  if (ch == null || (!Double.isNaN(likelihood) && likelihood > maxL)) {
    maxL = likelihood;
    ch = cso;
  }
}
SDChoiceArray selectedChoices = new SDChoiceArray(1);
if (ch != null)
  selectedChoices.add(ch);

13.13.2 Adding Imported Java Classes and Changing the Decision Center Display

To add imported Java classes to your Inline Service, click Advanced next to the description. You can also change the display label for Decision Center, and choose whether the element is displayed in the Decision Center Navigator. Changing the display label does not affect the Object ID.

13.14 About Models

Models serve two primary purposes: prediction and reporting. Models should be defined to:

• Predict the likelihood that certain events associated with Choices will occur

• Analyze data correlated with those events

Oracle RTD models automate many of the tasks that need to be addressed when designing and integrating predictive models for the purpose of improving decisions in a business process. These automated tasks include:

• Applying data transformation to input data prior to applying predictive models

• Validating the quality of the models

• Rebuilding / recalibrating models when new target attributes occur

• Validating the accuracy of models with new data and / or new outcomes

• Introducing some degree of randomization in the decision making process to enable "exploration"

The rest of this section highlights how the Oracle RTD model features address these different situations.

Note:

Data accumulated in Oracle RTD predictive models can also be exported to external database tables, and subsequently analyzed using standard reporting and business intelligence products and techniques. For more information, see the chapter "Setting Up and Using Model Snapshots" in Oracle Fusion Middleware Administrator's Guide for Oracle Real-Time Decisions.

Models are updated with, and "learn" from the following data:

• All the data in the Session entity - specifically, all the Session attributes, unless specifically excluded from analysis through the Inline Service configuration

In addition, Choice Event Models also require event-related details. For more information, see Section 13.14.1, "Model Types."

Models are associated at design time with a Choice Group. This defines the list of Choices to which prediction and reports apply. The nature of the Choices to which Oracle RTD models apply is very flexible as demonstrated by the following example:

• A model can be associated with a Marketing Offers choice group that contains a list of offers that have been presented and purchased by customers over time. This model can then be used to:

  • Predict: Compute the likelihood that a given customer will purchase a given offer in the list

  • Analyze: Explore reports highlighting customer characteristics correlated with purchase events

• A model can be associated with a Call Transfer choice group that contains two choices: Call was transferred and Call was not transferred. This model can be used to:

  • Predict: Compute the likelihood that a given customer call will be transferred or not transferred

  • Analyze: Explore reports highlighting call, agent and customer characteristics correlated with transfer events

Using Oracle RTD terminology (and by contrast with other approaches), one single Oracle RTD model applies to a list of target attributes rather than to a single target attribute. An Oracle RTD model therefore defines a series of shared parameters that apply to all the Choices to which this model applies. Because Oracle RTD models are in essence defining shared metadata, Oracle RTD models can then apply to a set of Choices that evolves over time. For example:

• New Offers can be added to the Marketing Offer choice group and Oracle RTD will automatically apply the shared model parameters to those new occurrences

Note:

Changes to Oracle RTD models parameters can be made incrementally at any point in the lifecycle of a Model and will apply in a forward manner to all model operations.

For more technical information about Oracle RTD models, see Appendix A, "Oracle RTD Model Features and Strategies."

This rest of this section contains the following topics:

• Section 13.14.1, "Model Types"

• Section 13.14.2, "Common Model Parameters"

• Section 13.14.3, "Model Attributes"

• Section 13.14.4, "Model APIs"

13.14.1 Model Types

When defining models with Oracle RTD, you can select from three types of model: Choice Event Model, Choice Model, and Model.

Each type of model corresponds to predefined usage patterns. While they share most of their characteristics, they differ by the degree of automation they provide for using prediction for the purpose of improving business decisions. All types of model can be used for prediction and reporting purposes.

• Choice Models and Choice Event Models: These models are associated with a target attribute of type Choice Group.

  A Choice Event Model is used to predict and analyze the conditional probability of events occurring, given a base event. Choice Event Models are defined with one base event and a list of positive events. The model can be used to predict the conditional probability that a positive event will happen given the base event happening. The model interprets the list of positive events as a sequence.

  It is possible (and quite common) to define more than one Choice Event Model to track the same group of events in a given Choice Group. The differences between the models are typically related to time windows, base events or partitioning attributes.

  A Choice Model is used to predict and analyze the probability of occurrences of Choices in general. Choice models do not define any events associated with their Choices. The model predicts whether the Choice is present or not.

  This is useful for situations where the Choices represent items that can be present in a business process. Example include: the reason for a call, a product that is being purchased, a Web page that is visited.

• Models: These models are associated with a target attribute of type session attribute. Plain Models or Models are typically not used but represent general purpose predictive models that would not have inherent knowledge of abstractions such as Choices, Choice Groups and Events.

For both choice models and choice event models, a prediction based on a numeric attribute value which does not exist in the model is generated from the closest numeric attribute value in the model, as follows:

• For attribute values greater than the highest value, the highest value is taken

• For attribute values less than the lowest value, the lowest value is taken

• For attribute values that lie between existing attribute values, the closest values is taken, where sufficient data exists to make the prediction

13.14.2 Common Model Parameters

Several of the model parameters are common to the three types of model:

• Algorithm

  The Algorithm dropdown list defines the type of predictive algorithm the model will use.

  There are two types of algorithm supported by Oracle RTD:

  • Bayesian algorithm

  • Regression algorithm

  Selecting an option will determine how correlations between input attributes and target attributes are handled to produce likelihood scores. Oracle recommends that you consult the mathematical literature to better understand the differences between these algorithms. In general terms, Bayesian algorithms are well suited when the proportion of positive outcomes is low, and Regression algorithms are well suited when the proportion of positive outcomes is high (typically above 15%).

• Time Window

  The Default time window check box and the Time Window dropdown list define the time lifecycle of models. The default time window is defined at the application level and is used for the model by default, except when you uncheck Default time window and select from the Time Window dropdown list.

  Model time windows can be set to:

  • Week, Half-Month, Month, Two Months, Quarter, Half-Year, or Year

  Based on the defined model time window, Oracle RTD will create new model instances as time passes to ensure that old data does not have the same influence over predictions as new data.

  Time Window is a key parameter for Oracle RTD model learning, reporting, and predictions:

  • Model learning occurs in every time window, and learning knowledge accumulates within each time window.

  • At the end of each time window, an archive is taken of all the knowledge learned in that time window. These archives, together with the current time window knowledge, provide the information for Decision Center users when they generate time-window-based reports.

  • Decision Center users can report on the information learned in:

    • Any specific time window (selecting it from the Time Window list of values)

    • Only the current time window (selecting it from the Time Window list of values and selecting Show Incomplete Time Window)

    • The special case of the current time window combined with the previous time window (selecting the current time window from the Time Window list of values and leaving Show Incomplete Time Window unchecked)

  • Predictions, when the Use for prediction option is chosen for the model, derive from what has been learned so far in the current time window together with all the learning from the previous time window. This ensures that new data is used for predictions rather than old data.

• Use for prediction and Randomize Likelihood

  All types of model can be used for prediction and reporting purposes. Models that are to be used for prediction purposes must have the Use for prediction option selected. When selecting this option, you can also decide whether or not to use the Randomize Likelihood option.

  Models used for prediction are available to compute a mathematical likelihood for each eligible choice at runtime in the Decision Server.

  The Randomize Likelihood option will apply some randomization formula on those scores to avoid a local minimum or maximum situation. This frequent situation occurs when new Choices are introduced during the life cycle of a model and when Models associated with those new Choices are "competing" with models on established Choices.

  In the context of new Choices, it is sometimes useful to introduce some degree of randomization so that those new Choices get a chance to be presented, and as a result to accumulate learning. By selecting the Randomize Likelihood option, you let Oracle RTD decide the degree to which model scores will be randomized. Oracle RTD adds to the likelihood of a positive outcome a normal random variable with mean zero and standard deviation which is proportional to the average likelihood of the positive outcome during the second and third phases of a model's maturity. For more details of this process, see Appendix A, "Model Randomized Likelihoods Computation."

• Premise Noise Reduction

  One known data pattern that needs to be addressed when using predictive models for decision purposes is the case of self-fulfilling predictions. This situation typically occurs when an input data attribute is always associated with the model target attribute. If you expect this situation to occur, select the Premise Noise Reduction option.

  This option automatically identifies input attribute values that are highly correlated with the model output and ignores those values for prediction purposes.

  For example:

  • Assume that a Model is built to predict products that will be added to a shopping cart

  • Assume that the array of products already in the shopping cart is used as input to the Model

  Using the Premise Noise Reduction option ignores the self-fulfilling correlation observed between a product and itself. Oracle RTD will also ignore products that are always associated with the input product, for example, as part of a bundle.

  Noise reduction filters out very high correlations, that is, about 99 to 100%. It is also subject to the model parameter Max Input Cardinality, whose default value is 500. This means that the counts of the first 500 distinct values are examined to determine high correlation - the more popular values are likely to occur within this.

  Though ignored for prediction purposes, input attribute values that are identified as "noise" are still visible in Decision Center and displayed in graphs with gray bars.

• Advanced: The Advanced button lets you choose to show the element in Decision Center, and to change the label of the element. Changing the label of the element does not change the Object ID.

13.14.3 Model Attributes

Choice Tab for Choice Events and Choice Models

For Choice Event and Choice Models, the Choice Tab has the following common options:

• Choice Group

• Label for Choice - the label for the Choice Group shown in Decision Center

For Choice Event Models, the Choice Tab has the following specific options:

• Base Event: The event is the event associated with Choices that represent the baseline of the conditional probabilities computed by the Choice Event Model. Events can be selected from a list of Events defined at the Choice Group level.

• Base Event Label

• Positive Outcome Events: This is the list of events for which the Model will compute conditional probabilities.

  For example, assume a Model linked to a Product Choice Group has a baseline event Delivered and two positive events, Interested and Purchased. When computing the likelihood of purchase of a given product:

  • The Model will first compute the likelihood of the Purchased event based upon knowing the Delivered event, and use this number if available.

  • If not enough data is available to make such prediction (in other words, the Model returns NaN), the Model likelihood function will then compute the likelihood of the Interested event based upon knowing the Delivered event, and return this number if available.

  • If not enough data is available to make such a prediction, the Model likelihood function will return NaN.

  In that regard, the list of positive outcomes represents an ordered sequence of positive events that you attempt to predict. The Model likelihood function allows you to select the "most positive" event from an ordered list of events.

For Choice Models, the Choice Tab has the following specific option

• Mutually exclusive choices: This option is available for Choice Models and indicates that the Choices representing the target of the Model are mutually exclusive.

Attributes Tab for Choice Events and Choice Models

For Choice Event and Choice Models, the Attributes tab has the following common options:

• Partitioning Attributes

  Partitioning a Model by adding a Partitioning Attribute is equivalent to creating a separate Model for each value of the Partitioning Attributes.

  For example, when building a Model to predict likelihood of acceptance for offers, you might want to create a Partitioning Attribute indicating the interaction channel in which this offer was delivered and accepted. Having a Model for Web offer acceptance and Contact Center offer acceptance will result in better predictive Models as it is known that customers with the same characteristics have very different likelihoods of accepting an offer depending on the channel through which the offer is made.

  If you choose a partitioning attribute, the default behavior is that at run-time, when each new partitioning attribute value is presented to the learning process, Oracle RTD automatically creates a new partition in the model. You can restrict the number of partitions to a specified set of values, which you enter in the Value Domain field for the chosen partitioning attribute. At run-time, the first time each specified value is presented to the learning server, a separate partition is created. To hold learning data for all non-specified values, Oracle RTD creates an "Other" partition the first time a non-specified value is presented to the learning server.

  In many Decision Center reports, you can filter the results by choosing a partition attribute value in the report header. For those reports, a value of "(missing)" in the filtering list of values for the partitioning attribute indicates that a null value for that attribute was presented at least once.

  Notes:

  1. In general, partitioning attributes should always have meaningful real-world values. They should not be nulls nor empty strings.

  2. A partitioning attribute in a model must be an attribute in the Session entity with the "Use for analysis" property selected.

  The decision to partition a model needs to be made very carefully for the following reasons:

  • Creating attributes will reduce the number of observations for each choice and attribute value combination, and therefore slow down the Model conversation process.

  • Model size is very sensitive to the cardinality of partitioning attributes.

  • Excluded attributes. By default, all session and entity attributes are used as inputs to Models. To remove a specific attribute from the list of Model inputs, add them to the list of Excluded Attributes.

Note:

Adding or removing Partition Attributes to an existing Model breaks compatibility with reports, snapshots, predictions, and deployment. To prevent any errors, erase old learning data using Enterprise Manager. To preserve existing data, create a new model, cloned from the existing model, and update decision logic to record learnings to the new model.

For Choice Models, the Attributes tab has the following specific option:

• Aggregate by: By choosing one of the partitioning attributes, you can create additional sub-models for learning on the attribute. As with partitioning, a decision to aggregate on an attribute has to be based on a radical difference in predicted likelihood depending on the value of the attribute in question.

Learn Location Tab for Choice Events and Choice Models

For Choice Event and Choice Models, the Learn Location tab has the following common options:

• (Learn) On session close or On Integration Point

  By default, all model learning operations occur when the session closes. Alternatively you can select a specific integration point (Informant or Advisor) at which point model learning operations need to be triggered.

Temporary Data Storage Tab for Choice Event Models

For Choice Event Models, the Temporary Data Storage tab contains fields that enable deferred or delayed learning to occur in the situations where a base event occurs in one session and one or more corresponding positive events occur in a later session.

The Temporary Data Storage tab has the following common options:

• Use temporary data storage

  A common data pattern is that events related to Choices might not all occur during the lifetime of an Oracle RTD session. To make sure the original input values used for predictions are also used to update the Model when such delayed positive outcomes occur, select the Use temporary data storage option.

• Days to Keep: Specifies the number of days to keep temporary data stored on the server.

• Keys: The data stored in temporary data storage is available for retrieval by having any one of the Session keys defined in the Temporary Data Storage tab.

When Use temporary data storage is selected, then the choice and choice attributes for a base event in a session are stored (for Days to Keep days), identified by each of the Session key identifiers specified in Keys.

In a later session, which has the same Session key value as one of the Keys stored in an earlier session, a positive event may occur without a corresponding base event in that later session. Oracle RTD searches data stored in previous sessions to try to find a corresponding base event in an earlier session, by matching the later-session Session key value against an earlier-session Key value.

The earlier-session base event choice and choice attributes together with the later-session positive event data are sent to the learning model at the next learning point (session close or specified integration point).

13.14.4 Model APIs

The following code returns the Object label and Id, respectively:

public String getSDOLabel();
public String getSDOId();

This section contains the following topics:

• Section 13.14.4.1, "Querying the Model"

• Section 13.14.4.2, "Recording the Choice with the Model"

• Section 13.14.4.3, "Obtaining Model Object by String Name"

• Section 13.14.4.4, "Recording Choice Events for Choice Event Models"

• Section 13.14.4.5, "Recording Choices for Choice Models"

• Section 13.14.4.6, "Obtaining Model Choice Likelihood"

13.14.4.1 Querying the Model

The model can be queried using any of the getChoiceEventLikelihood methods shown in the following code sample. This will return the likelihood of a Choice being chosen by the model and the likelihood that any Choice will have the given event.

public static double getChoiceEventLikelihoods(GENOffersChoice choice, String eventName); 
public static double getChoiceEventLikelihoods(GENOffers choiceGroup, String eventName);

13.14.4.2 Recording the Choice with the Model

For the Choice Event model, the model method recordEvent is executed when a call to the Choice method recordEvent is made. Therefore, it is not necessary to directly invoke this method on the model. This method is usually called from within the Integration Point where the Choice was extended to the calling application.

For instance, in an Advisor Integration Point:

if (choices.size() > 0) {
  Choice ch = choices.get(0);
  ch.recordEvent("Presented");
  session().setOfferExtended(ch.getSDOId());
}

For the Choice model, the following APIs are available:

public static SDStringArray getChoice()
public static void setChoice(SDStringArray _v)
public static void addToChoice(String _a)
public static void addAllToChoice(SDStringArray _c)

The Informant usually records a Choice with the model. For instance, in a case where we are recording the Choice of a call reason code with the Model Reason Analysis:

if (code == 17)
  ReasonAnalysis.addToChoice("BalanceInquiry");
else if (code == 18)
  ReasonAnalysis.addToChoice("MakePayment");
else if (code == 19)
  ReasonAnalysis.addToChoice("RateInquiry");
else
  ReasonAnalysis.addToChoice("Other");

13.14.4.3 Obtaining Model Object by String Name

These APIs allow users to obtain a model object by its string name. There is one API for choice models, and another for choice event models.

General Form of the APIs

ChoiceModel <cm_model_instance_name> = Application.getApp().getChoiceModel(<model_name>);

ChoiceEventModel <cem_model_instance_name> = Application.getApp().getChoiceEventModel(<model_name>);

where:

<model_name> must be a type String model name

Example

For an example of the getChoiceEventModel API, see Example of Choice Event Model APIs.

For an example of the getChoiceModel API, see Example of Choice Model APIs.

13.14.4.4 Recording Choice Events for Choice Event Models

This API allows users to send in a choice id and event and automatically update the associated choice event model. Developers can write "record event" logic once. The code can then be reused, without additional editing, for additional choices and choice groups added subsequently to the Inline Service.

General Form of the API

<cem_model_instance_name>.recordEvent(<choiceId>,<eventId>);

where:

<cem_model_instance_name> must be of type ChoiceEventModel, previously retrieved by the getChoiceEventModel API

<choiceId> must be a type String choice identifier

<eventId> must be a type String event identifier

Example of Choice Event Model APIs

The following shows an example of the getChoiceEventModel and recordEvent APIs:

// Select the choice for the given classification
int classification = session().getDnaRecord().getClassification();
 
String modelName = "DnaClassesAPITest";
ChoiceEventModel model = Application.getApp().getChoiceEventModel(modelName);
// Definitions
SDChoiceArray choices = new SDChoiceArray();
ChoiceGroupInterface group = ClassificationsTestApi.getPrototype().cloneGroup();
// Get the group of choices to simulate
//group = ClassificationsTestApi.getPrototype().cloneGroup();
// Get all eligible choices
group.getEligibleChoices(choices);
int sz = choices.size();
// Iterate through all eligible choices in the group
for (int i = 0; i < sz; i++) {
ClassificationsTestApiChoice ch = (ClassificationsTestApiChoice) choices.get(i);
    String choiceId = ch.getSDOId();
    String eventId = "record";
    model.recordEvent(choiceId, eventId);
 
if (ch.getClassification() == classification) {
String cnm = ch.getSDOId();
eventId = "identified";
model.recordEvent(choiceId, eventId);
logInfo("ID " + session().getDnaRecord().getId()
+ " Classification: " + classification + " choice: "
+ ch.getSDOId() + " size was: " + sz);
}
}

13.14.4.5 Recording Choices for Choice Models

This API allows users to send in a choice id to automatically update the associated choice model.

General Form of the API

<cm_model_instance_name>.recordChoice(<choiceId>);

where:

<cm_model_instance_name> must be of type ChoiceModel, previously retrieved by the getChoiceModel API

<choiceId> must be a type String choice identifier

General Form of the API

<cm_model_instance_name>.recordChoice(<choiceId>);

where:

<cm_model_instance_name> must be of type ChoiceModel, previously retrieved by the getChoiceModel API

<choiceId> must be a type String choice identifier

Example of Choice Model APIs

The following shows an example of the getChoiceModel and recordChoice APIs:

double amount = targetNumber;
double spacing = Application.getApp().getSpacing();
double max = Application.getApp().getMaxOutput();
double min = Application.getApp().getMinOutput();
//Application.logInfo("amount is: "+amount);
int nDigits = (int)Math.log10(max);
nDigits = nDigits + 3;
//Application.logInfo("nDigits in Dynamic Choices: "+nDigits);
String targetChoiceGroupName = Application.getApp().getTargetChoiceGroupName();
String targetChoiceBaseName = Application.getApp().getTargetChoiceBaseName();
double t_max = max-spacing;
double t_min = min-spacing;
ChoiceModel model = Application.getApp().getChoiceModel(modelName);
for (double t= t_max; t>t_min; t = t-spacing) {
    String id;
   if (amount > t) {
   id = String.format(targetChoiceGroupName+"$"+targetChoiceBaseName+"%0 "+nDigits+".1fAbove", t);
        model.recordChoice(id);
       for (double it = t-spacing; it>t_min; it= it-spacing) {
        id = String.format(targetChoiceGroupName+"$"+targetChoiceBaseName+"%0 "+nDigits+".1fAbove", it);
               model.recordChoice(id);
             }
              break;
   }
}

13.14.4.6 Obtaining Model Choice Likelihood

These APIs allow users to obtain a likelihood score for either a choice or choice event model for the "All" version of the model or a specific partition of the model should a partition exist.

General Form of the APIs

<cm_model_instance_name>.getChoiceLikelihood(<choiceId>);

<cem_model_instance_name>.getChoiceEventLikelihood(<choiceId>,<eventId>);

where:

<cm_model_instance_name> must be of type ChoiceModel, previously retrieved by the getChoiceModel API

<cem_model_instance_name> must be of type ChoiceEventModel, previously retrieved by the getChoiceEventModel API

<choiceId> must be a type String choice identifier

<eventId> must be a type String event identifier

Example

The following shows an example of the getChoiceEventLikelihood API:

ChoiceEventModel model = Application.getApp().getChoiceEventModel(modelName);
return model.getChoiceEventLikelihood(choiceId, eventId);

13.15 About Integration Points

There are two types of Integration Point in Oracle RTD, Informants and Advisors. These represent the integration points between external systems and Oracle RTD.

An external system and an order number are also defined for each Integration Point. These are used to generate the process map presented in Decision Center. The system determines the swim-lane and the order the position, from left to right. The order can be any number, not just integers, allowing for the introduction of new Integration Points without modifying existing ones.

This section contains the following topics:

• Section 13.15.1, "About Informants"

• Section 13.15.2, "Adding Imported Java Classes and Changing the Decision Center Display"

• Section 13.15.3, "Informant APIs"

• Section 13.15.4, "Informant Logic"

• Section 13.15.5, "About Advisors"

• Section 13.15.6, "About the Advisor Decisioning Process"

• Section 13.15.7, "Adding Imported Java Classes and Changing the Decision Center Display"

• Section 13.15.8, "Adding a Session Key"

• Section 13.15.9, "Identifying the External System and Order"

• Section 13.15.10, "Adding Request Data"

• Section 13.15.11, "Adding Response Data"

• Section 13.15.12, "Logic in Advisors"

• Section 13.15.13, "Accessing Request Data from the Advisor"

13.15.1 About Informants

Informants represent asynchronous integration points between external systems and Oracle RTD.

Informants are typically triggered to pass contextual information to Oracle RTD to support the decision process, as follows:

• Informants pass closed loop information to Oracle RTD to update its predictive models

• Informants pass session identifiers for Oracle RTD to fetch relevant information from external data sources

To add an Informant to the Inline Service, perform the following:

1. Create an external system to identify which system accesses the Integration Point.

2. Create a Choice Group to represent the targets for your analysis. For instance, a Choice Group may represent the reasons for calls to the service center.

3. Create an Informant that receives the session key information and gathers and processes data based on the session.

4. Create an analytical model that is the repository for the data and analyzes it.

Informants have a Description, as well as the following Request characteristics:

• Session Keys: One or more session keys used to uniquely identify a session. Any of the session keys within the message are sufficient for identifying a session, and therefore cause the message to be dispatched to an existing session, if any, already containing information related to this message.

• External System: Identifies the external system that will be sending the Informant a request. Associating the Informant with an external system allows the Informant to be displayed among other Informants and Advisors in Decision Center's process map.

• Order: This number identifies the position of the Informant in the sequence of Integration Points displayed in Decision Center's process map. An Integration Point with an order less than another Integration Point's order will be displayed before the other Integration Point. The order can be a decimal number; for example, 2.1 will be displayed before 2.2.

• Force Session Close: When selected, causes the Inline Service to automatically terminate the session of the Informant after all of the Informant's asynchronous logic has executed. The same effect can be achieved by placing the following Java statement anywhere in a subtab of the Informant's Logic tab: session().close();

This section contains the following topics:

• Section 13.15.1.1, "Adding a Session Key"

• Section 13.15.1.2, "Identifying the External System and Order"

• Section 13.15.1.3, "Adding Request Data"

13.15.1.1 Adding a Session Key

On the Request tab, click Select to select a session key for the Integration Point. This is one of the values that the operational system will supply to the Integration Point.

13.15.1.2 Identifying the External System and Order

On the Request tab, use the dropdown list to choose the external system that accesses the Integration Point. This menu is populated by creating external system identifiers using the external system element.

The order in which the Integration Points are accessed is represented by Order. This number and the External System determine how the end-to-end process is displayed in Decision Center.

13.15.1.3 Adding Request Data

On the Request tab, click Add to add request data. Assignments are the values that the operational system will supply to the Integration Point. Assignments have the following characteristics:

• Incoming Parameter: The name of the field in the request sent to the Informant whose value will be copied from the request to the session attribute. This name does not have to be the same as the session attribute; however, it generally is named the same.

  After the session key is created, incoming parameters are assigned to the session key attributes.

• Type: This is the data type of the session attribute into which the incoming argument will be copied. The valid types are: integer, string, date, or double.

  Note:

  If the type of the request field and the session key attribute do not match, you should use a transform method.

• Array: Marked if the type is a collection.

• Session Attribute: The attribute of the session to which the incoming parameter of a request will be mapped.

13.15.2 Adding Imported Java Classes and Changing the Decision Center Display

To add imported Java classes to your Inline Service, click Advanced next to the description. You can also change the display label for Decision Center, and choose whether the element is displayed in the Decision Center Navigator. Changing the display label does not affect the Object ID.

13.15.3 Informant APIs

The following code returns the Object label and Id, respectively:

public String getSDOLabel();
public String getSDOId();

13.15.4 Informant Logic

There are two tabs for Informant logic: the Logic tab and the Asynchronous Logic tab. You can access request data for an Informant in either of the tabs.

This section contains the following topics:

• Section 13.15.4.1, "Logic"

• Section 13.15.4.2, "Asynchronous Logic"

• Section 13.15.4.3, "Accessing Request Data From the Informant"

13.15.4.1 Logic

This script runs after any Request Data declared in Request Data are executed. If the primary purpose of the Informant is to transfer data from the operational system request fields to the session key and Request Data, logic may be unnecessary, as this happens automatically according to declarations in the Request Data tab.

Logic in Informants is typically used for tracing message reception in the log file, or for pre-populating entities whose keys are supplied by the Informant's message, in order to avoid having to do this later in an Advisor, where response time might be more important. Logic is executed directly following the Request Data.

Logic in the Informant can also be used to record Choices with a Choice Model. See the Choice Model APIs for methods to call.

13.15.4.2 Asynchronous Logic

This script runs after the script defined in the Logic tab, described in the previous section. Any additional processing that needs to be done can be placed in this area. The order of execution of Asynchronous Logic is not guaranteed.

13.15.4.3 Accessing Request Data From the Informant

Request data from an Informant is accessed one of several ways. If the incoming parameter is mapped to a session attribute, there is a get method for the parameter.

request.get$()

where $ is the parameter name with the first letter capitalized.

If the attribute is not mapped, there are methods to achieve the same results using the field name of the parameter.

String request.getStringValue(fieldName)
SDStringArray request.getStringArrayValue(fieldName)
boolean request.isArgPresent(fieldName)

13.15.5 About Advisors

Advisors represent synchronous integration points between external systems and Oracle RTD. Advisors are typically triggered to initiate an Oracle RTD Decision.

Each Advisor can make use of two Decisions, the Optimized Decision and the Control Group Decision. This enables users to compare the respective performance of the two options.

Generally, the two Decisions are set up as follows:

• The Optimized Decision implements some decision logic that takes advantage of the advanced features of the Oracle RTD Decision Framework.

• The Control Group Decision is as close to the existing business process as possible, so that the Optimized Decision has a basis for comparison.

Default Choices can be defined for the Advisor. These Choices are used when the computation in the server can not be completed in time, or if the client loses communication with the server.

13.15.6 About the Advisor Decisioning Process

Advisors have a Description, as well as the following Request characteristics:

• Session Keys: One or more session keys used to uniquely identify a session. Any of the session keys within the message are sufficient for identifying a session, and hence cause the message to be dispatched to an existing session, if any, already containing information related to this message.

  When the Advisor is called, the session key creation is the first thing executed.

• External System: Identifies the external system that will be triggering the Advisor request. Associating the Advisor with an external system allows the Advisor to be displayed among other Informants and Advisors in Decision Center's process map.

• Order: This number identifies the position of the Advisor in the sequence of Integration Points displayed in Decision Center's process map. An Integration Point with an order less than another Integration Point's order will be displayed before the other Integration Point. The order can be a decimal number; for example, 2.1 will be displayed before 2.2.

• Force Session Close: When selected, this option causes the Inline Service to automatically terminate the Advisor's session after all of the Advisor's asynchronous logic has executed. The same effect can be achieved by placing the following Java statement anywhere in any subtab of the Advisor's Logic tab: session().close();

13.15.7 Adding Imported Java Classes and Changing the Decision Center Display

To add imported Java classes to your Inline Service, click Advanced next to the description. You can also change the display label for Decision Center, and choose whether the element is displayed in the Decision Center Navigator. Changing the display label does not affect the Object ID.

13.15.8 Adding a Session Key

On the Request tab, click Select to select a session key for the Integration Point. This is one of the values that the operational system will supply to the Integration Point.

13.15.9 Identifying the External System and Order

On the Request tab, use the dropdown list to choose the external system that accesses the Integration Point. This list is populated by creating external system identifiers using the external system element.

The order in which the Integration Points are accessed is represented by Order. This number and the External System determine how the end-to-end process is displayed in Decision Center.

13.15.10 Adding Request Data

On the Request tab, click Add to add request data. Request data is the values that the operational system will supply to the Integration Point. Request data has the following characteristics:

• Incoming Parameter: The name of the field in the request sent to the Advisor whose value will be copied from the request to the session attribute. This name does not have to be the same as the Session attribute; however it generally is named the same.

  After the session key is created, the assignment of incoming parameters to session attributes is made.

• Type: This is the data type of the session attribute into which the incoming argument will be copied. The valid types are: integer, string, date or double.

  Note:

  If the type of the request field and the session attribute do not match, you should use a transform method.

• Array: Select this option if the type is a collection.

• Session Attribute: The attribute of the session to which the incoming parameter of a request is mapped.

13.15.11 Adding Response Data

On the Response tab, click Add to add response data. Response data is the values that the operational system will send back to the Integration Point after a request is invoked. Response data has the following characteristics:

• Response: The response contains an array of selected Choice objects, with each Choice containing a collection of named attribute values. The Choice selection process is governed by one of two Decision objects referenced by the Advisor. One Decision is given to the calling application.

• Decision to Use: The name of the Decision object to use for normal sessions, as opposed to control-group sessions. This Decision becomes the Advisor's response to the calling system.

• Control Group Decision to Use: Control Group Decision is used for only a small percentage of sessions as a way to assess the effectiveness of the other Decisions by providing a baseline. The percentage of sessions that use the control-group decision is specified in the Application element of the Inline Service. The Control Group Decision should be designed to select choices using "business-as-usual" logic, meaning whatever rules the enterprise previously used before introducing the Inline Service. Reports are available through the Decision Center console that compare the business effectiveness of the Advisor's normal Decision object with its Control Group Decision.

• Parameters: Input parameter defined by the decision. The Name and Type columns are descriptive only, surfaced here from the Decision object.

• Default number of choices returned: Default number of choices returned by the decision. This is the number of choices defined by the Decision.

• Override default with: The Advisor can override or accept the number specified by the referenced Decision. This area specifies the maximum number of qualified choices to be included in the Advisor's response.

• Default Choices: A list of Choices that are returned to the calling client application whenever it tries to invoke this Advisor, and the Advisor is not able to deliver its response within the server's guaranteed response time.

  Note that default Choices do not have to be specified for each Advisor. The Inline Service may also declare default Choices, which are used for Advisors that don't declare their own. Also note that the default Choice configuration is propagated to the client application and stored in the local file system by the Smart Client component. Hence, it is subsequently available to client applications that cannot connect to the server.

13.15.12 Logic in Advisors

There are two tabs for Advisor logic: the Logic tab and the Asynchronous Logic tab.

This section contains the following topics:

• Section 13.15.12.1, "Logic"

• Section 13.15.12.2, "Asynchronous Logic"

13.15.12.1 Logic

This script runs after any request data declared in the request data tab is executed, and before the response is sent back to the client.

Advisor logic is generally not needed. You may want to use it for preprocessing data coming in with the request, or for debugging purposes.

13.15.12.2 Asynchronous Logic

This script runs after the response has been handed off to the server-side mechanism that sends it back to the client. Depending on the type of endpoint used by the client, the client may be able to start processing the result before this script finishes, thus improving the effective response time by increasing parallelism.

13.15.13 Accessing Request Data from the Advisor

Request data from an Advisor is accessed in one of several ways. If the incoming parameter is mapped to a session attribute, there is a get method for the parameter.

request.get$()

where $ is the parameter name with the first letter capitalized.

If the attribute is not mapped, there are several methods to achieve the same results.

String request.getStringValue(fieldName)
SDStringArray request.getStringArrayValue(fieldName)
boolean request.isArgPresent(fieldName)

13.15.14 Temporary Sessions for Integration Points Without Session Keys

Integration Points may be designed as Remote Procedure Calls to execute some logic in the server, without having to contribute to model learning. If the design intention is not to access a specific session, Integration Points can be defined without a session key.

The APIs available to an Integration Point includes the Session() method, which returns a session object. When an Integration Point with no session key defined calls the Session() method, Oracle RTD creates a temporary session. This session can be used as a container of data generated and consumed by the Integration Point, but, because the session is temporary, it will not be available to other Integration Point calls.

13.16 About External Systems

External systems are only identified within Decision Studio. The external system represents the operational systems within the enterprise that integrate to the Inline Service. The external system is not accessible through the API. The external system is used by an Integration Point to identify which external system will access that Integration Point. External systems are used for display on the Integration Map in Decision Center.

External systems have a Description, and a Display Label. Changing the Display Label does not affect the Object ID.

13.17 About the Categories Object

Categories are used to organize Choices. All Choices of the same category appear together in Decision Center. No classes are generated for categories. They are only used by Decision Center for grouping and organizing Choices.

Categories have the following characteristics:

• Name: Name of the category, as entered in Decision Studio.

• Description: Description of the category, as entered in Decision Studio.

• Display Label: Lets you change the Display Label. This does not affect the Object ID.

13.18 About Functions

Functions can be used for calculation or for other processing that you want to make reusable. Functions are defined using Decision Studio. Functions are defined with the following characteristics:

• Description: Description of the function.

• Return value: Specifies whether the function returns a value.

• Data Type: Type of the returned value.

• Array: Select this option if the return type is an array.

• Call Template: The definition of how the function will be called. Using {0}, {1}, and so on as arguments, and phrasing to describe the function, define the template for call. It is important to use good phrasing, as this is what will be shown when using the function. For instance, a call template for multiply is {0} multiplied by {1}.

• Parameters: Named parameters that will be used in the logic of the function. This number must match the number of arguments in the call template. For instance, Multiply has the following parameters: a, type Double; b, type Double

  If you want to use a function parameter in a rule, you can select a Type Restriction for the parameter. This is not a mandatory requirement, but it will help you in formulating the rule. For more information about creating and using type restrictions, see Section 13.19, "About Type Restrictions."

• Logic: Java code for the function. The code for multiply is:

  return a * b;
  

This section includes the following topics:

• Section 13.18.1, "Functions to Use with Choice Event History Table"

• Section 13.18.2, "About Maintenance Operations"

• Section 13.18.3, "Adding Imported Java Classes and Changing the Decision Center Display"

13.18.1 Functions to Use with Choice Event History Table

As part of configuring an Inline Service, predefined functions are available to access any data that is stored in Oracle RTD's Choice Event History table. These functions are accessible when creating or editing choice eligibility rules, and can also be called through custom Java logic as well.

To access these functions in a choice eligibility rule statement, select Function Call, and expand the Functions folder. The following functions appear in the list of available functions:

Function Name	Parameters	Description
Days Since Last Event	Event Name	For a given choice and a specified event name, returns the number of days since that last recorded event.
Days Since Last Event on Channel	Event Name Channel	For a given choice, specified event name, and specified channel name, returns the number of days since that last recorded event.
Number of Recent Events	Event Name Number Of Days	For a given choice, specified event name, and specified number of days, returns the total count of times that event has been recorded.
Number of Recent Events on Channel	Event Name Channel Number Of Days	For a given choice, specified event name, specified channel, and specified number of days, returns the total count of times that event has been recorded.

13.18.2 About Maintenance Operations

Maintenance Operations are user-defined, Inline Service specific functions that enable administrators to perform particular Inline Service related tasks in Enterprise Manager, such as the following:

• Clearing the external rule cache

• Broadcasting messages within a cluster

• Performing blocking operations

The Maintenance Operations written for an Inline Service are exposed by Oracle RTD as MBean Operations.

A Maintenance Operation may be invoked on an individual cluster member, or across a cluster as a whole. Maintenance Operations are non-blocking.

Note:

You may invoke a Maintenance Operation on an individual cluster member directly, in a blocking fashion. If you broadcast the request to invoke the Maintenance Operation across a cluster, you will block only as long as it takes to deliver the message.

Each Maintenance Operation will appear twice in the MBeans tree for each Loadable Inline Service:

1. To allow for the Maintenance Operation invocation on a local server only.

2. To allow for the Maintenance Operation invocation across every node of a cluster.

Different versions of a particular Inline Service may have different Maintenance Operations. For example, it is possible to have more than one version of an Inline Service deployed - they may be in different deployment states. Only Inline Services in the "Loadable" state expose any Maintenance Operations.

There are certain design-time considerations for Maintenance Operations:

• Maintenance Operations may have 0 or more primitive type arguments (String, int, double, date, or boolean), and may return String, int, double, date, boolean, or void.

  Returned values (and Exception) are logged.

• Maintenance Operation operate within the global Inline Service context. Session attributes are null. If the session is accessed, an IllegalStateException is thrown.

Maintenance Operations for External Rule Caching

Oracle RTD provides specific maintenance operations for external rules caching. For details, see Section 17.2.6.2, "External Rule Caching."

13.18.3 Adding Imported Java Classes and Changing the Decision Center Display

To add imported Java classes to your Inline Service, click Advanced next to the description. You can also change the display label for Decision Center, and choose whether the element is displayed in the Decision Center Navigator. Changing the display label does not affect the Object ID.

Functions are called from other elements using the call template. For instance, if you wanted to use the multiply function described in the previous section, you would choose the function from the Edit Value dialog. The call template {0} multiplied by {1} provides the editor with the position and number of arguments.

13.19 About Type Restrictions

Type restrictions define constraints that can be attached to session and entity attributes, choice and choice group attributes, and function and application parameters, so long as their type is Integer, Double, Date, or String.

Type restrictions are typically used in the Rule Editor to simplify user inputs, When you define a rule in the Rule Editor that uses one or more type-restricted elements, you can view and select from lists of values that obey the constraints defined in the associated type restrictions. A type restriction acts as an aid to the Inline Service designer. It does not get evaluated at run time.

There are three kinds of type restriction:

• List of Values

• List of Entities

• Other Restrictions

List of Values type restrictions appear in a list with one or more values.

List of Entities type restrictions consist of entity attribute values that are returned from a function. List of Entities type restrictions can be used to generate dynamic lists of values from database tables and views.

Other Restrictions consist of either a range of values (for Date, Double, or Integer data types), or a JavaScript Regular Expression pattern.

JavaScript Regular Expression patterns are generally used for data such as post codes and telephone numbers, where each character of the data may be subject to a different real-world constraint, depending on its position in the code. For example, US telephone numbers, such as [phone], and British postal codes, such as KT2 6JX.

13.19.1 Managing Type Restrictions

You create and edit type restrictions as individual Service Metadata objects. You can then associate type restrictions with the following Inline Service objects in the corresponding object editor:

• Session and entity attributes

• Choice group attributes

• Choice attributes

• Function parameters

• Application parameters

If you include a type-restricted object as an operand in a rule in the Rule Editor, you can get the following assistance as you create or edit the rule:

• For objects with List of Values or List of Entities type restrictions, you can view and select values for the object from dropdown lists that obey the type restriction constraints

• For objects whose type restrictions are Other Restrictions, you can move the mouse (cursor) over the object to see the range constraint or the JavaScript Regular Expression of the type restriction

This rest of this section consists of the following topics:

• Section 13.19.1.1, "Creating and Editing "List of Values" Type Restrictions"

• Section 13.19.1.2, "Creating and Editing "List of Entities" Type Restrictions"

• Section 13.19.1.3, "Creating and Editing Other Restrictions"

• Section 13.19.1.4, "Associating Type Restrictions with Inline Service Objects"

• Section 13.19.1.5, "Using Type Restrictions in Rules"

• Section 13.19.1.6, "Examples of Type Restrictions"

13.19.1.1 Creating and Editing "List of Values" Type Restrictions

For a List of Values type restriction, you must select a data type, then provide one or more values for individual elements. Oracle recommends the number of values selected to be less than 500.

You can define List of Values type restrictions for String, Integer, Double, or Date data.

13.19.1.2 Creating and Editing "List of Entities" Type Restrictions

In order to define a List of Entities type restriction, you must first fulfill certain prerequisites:

• You must have defined a function that returns data of a certain entity type (Oracle recommends that the function returns less than 500 values)

• The referenced entity type must contain at least two columns, that will serve as the "label" and "value" of the type restriction.

  The "label" and "value" columns are used in the Rule Editor when you edit a rule statement, and you select an attribute or parameter to which you have attached a type restriction.

  The "label" column holds the dropdown list data. When you select from the dropdown list, the corresponding data in the "value" column is placed in the rule.

  For example, a type restriction on US state codes may enable a rule creator to select a state name from a dropdown list of US state names - such as Alabama, or California, and so on. The "state name" column is the "label" column.

  After the rule creator selects a state name from the dropdown list, Oracle RTD places the corresponding state code - such as AL, or CA - into the rule. The "state code" column is the "value" column.

  List of Entities type restrictions are defined with the following characteristics:

  • Entity: The entity for which you want to define a type restriction.

  • Function: The function that returns restricted data. The Return value for this function must specify the type restriction entity as its Data Type.

  • Label: The attribute of the type restriction entity that holds the dropdown list values when rules are created that reference objects with this type restriction.

  • Value: The attribute of the type restriction entity that holds the values returned into rules when users select dropdown Label list values in the Rule Editor.

You can define List of Entities type restrictions for String, Integer, Double, or Date data.

Note:

After you have created or edited a List of Entities type restriction, you must deploy the Inline Service. This is to enable correct values to appear in dropdown lists when you create rules involving the type-restricted attribute or parameter.

13.19.1.3 Creating and Editing Other Restrictions

With Other Restrictions, you can define range constraints or JavaScript Regular Expression patterns or a combination of both.

You can define range constraints on data whose type is Integer, Double, or Date. You can specify lower and upper limits, and whether the limit value is included or not. For example, a "greater than" condition does not include the minimum value, whereas a "greater than or equal" condition does.

A JavaScript Regular Expression pattern uses standard Regular Expression pattern characters, such as {,}, [,], $,?,\, and so on, to define a data format or pattern. You can specify JavaScript Regular Expression patterns for String, Integer, Double, or Date data.

As an example, consider Canadian post codes, such as L5J 2V4 or V6Z 1M5. The JavaScript Regular Expression pattern that constrains these data values to the desired format is [A-Z]\d[A-Z] \d[A-Z]\d.

For Integer, Double, or Date data, you can define both a range constraint and a JavaScript Regular Expression pattern. When the type restriction is used, the two conditions are combined using the logical AND operation.

13.19.1.4 Associating Type Restrictions with Inline Service Objects

After you have created a Type Restriction, you can associate it with one or more of the following Inline Service objects in the corresponding object editor:

• Session and entity attributes

• Choice group attributes

• Choice attributes

• Function parameters

• Application parameters

For more information about using the appropriate object editors, see the corresponding object-related sections in this documentation.

13.19.1.5 Using Type Restrictions in Rules

Associating a Type Restriction with an object helps business users formulate rules for that object in the Rule Editor.

When you create or edit a rule, you have the following options:

• If you select a List of Values or List of Entities type-restricted object as an operand, a dropdown list of values becomes available for the other rule operand. You may select a value from this dropdown list, but you do not have to.

• If you select an Other Restrictions type-restricted object as an operand, and mouse hover over the operand, the range constraint or the JavaScript Regular Expression for the type restriction appears in the hover help.

Note:

Type Restrictions are an aid, not a strict requirement, for creating or editing rules. For example, you may enter values in rules for type-restricted elements other than those that appear in the dropdown lists. At run time, rules are evaluated and acted upon, not Type Restrictions.

In general:

• List of Values type restrictions present constant lists

• List of Entities type restrictions present dynamic run time lists

• Other Restrictions enable design type validation other than checking against list entries

Any violation of a type restriction constraint is treated as a warning rather than an error, as follows:

• The violating operand is underlined with a red wiggly line

• When you mouse hover over the offending operand, you get detailed information about the violation

The rule can still be compiled and deployed with warnings.

13.19.1.6 Examples of Type Restrictions

This section shows examples of how to create and use various type restrictions.

1. "List of Values" Type Restriction

   Create a type restriction called Product_Size, with values "Large", "Medium", and "Small."

   Attach the Product_Size type restriction to the attribute session/Product.

   In the Rule Editor, create the filtering rule Large_Product as follows:

   • session/Product = "Large"

2. "List of Entities" Type Restriction

   Create an entity New_Province, with String attributes Code and Fullname.

   Create a function Fn_New_Provinces, which returns a value of data type New_Province, with the following Logic:

   SDProvinceArray provinces = new SDProvinceArray();
   Province nb = new Province();
   nb.setCode("NB");
   nb.setFullname("New Brunswick");
   provinces.add(nb);
                   
   Province nf = new Province();
   nf.setCode("NF");
   nf.setFullname("Newfoundland");
   provinces.add(nf);
   
   return provinces;
   

   Create a String type restriction, Province_Restriction, with the following characteristics:

   • Entity= New_Province

   • Function=Fn_New_Provinces

   • Label=Fullname

   • Value=Code

   Deploy the Inline Service. This is to enable correct values to appear in a subsequent dropdown list of values of the Rule Editor.

   Attach Province_Restriction as a type restriction for the entity attribute session/Address/Province.

   In the Rule Editor, create the filtering rule NF as follows:

   • session/Address/Province = "NF"

   The dropdown list for Province values shows Fullname values. The selected value, which is placed in the rule, is a Code.

3. "List of Entities" Type Restriction Showing Dynamic Values

   This example enables you to view and select values from a database table when you use a type-restricted object in a rule.

   Create an entity Look Up, with String attributes Statecode and Statename.

   Create a data source States DS based on a table States, with columns Abbr and Fullname.

   Create an entity US States Look Up, with the following characteristics:

   • An array attribute lookUp, of type Look Up

   • The attribute lookUp/Statecode mapped to States DS/Abbr

   • The attribute lookUp/Statename mapped to States DS/AbbrFullname

   Create a function Look Up States, which returns a value of data type Look Up, with the following Logic:

   return new UsStatesLookUp().getLookUp();
   

   Create a String type restriction, States Input, with the following characteristics:

   • Entity= Look Up

   • Function=Look Up States

   • Label=Statename

   • Value=Statecode

   Deploy the Inline Service. This is to enable correct values to appear in a subsequent dropdown list of values of the Rule Editor.

   Attach States Input as a type restriction for the entity attribute session/Address/State.

   In the Rule Editor, create the filtering rule ND as follows:

   • session/Address/State = "ND"

   The dropdown list for State values shows Statename values. When you select "North Dakota", the corresponding Statecode value "ND" is placed in the rule.

4. Other Type Restriction Using a Range

   Create a Date type restriction called From_Now_On, with a minimum inclusive lower value of the current date.

   Attach the From_Now_On type restriction to the attribute session/Acct/Pay_By.

   In the Rule Editor, create the filtering rule PayUp as follows:

   • session/Acct/Pay_By = <current_date> + 45 days

5. Other Type Restriction Using a JavaScript Regular Expression Pattern

   Create a Date type restriction called Morning Rush Hour, which restricts values to times from 8:00 AM to 9:59 AM, with the following JavaScript RegEx pattern:

   ^(?=\d)(?:(?:(?:(?:(?:0?[13578]|1[02])(\/|-|\.)31)\1|(?:(?:0?[1,3-9]|1[0-2])(\/|-|\.)(?:29|30)\2))(?:(?:1[6-9]|[2-9]\d)?\d{2})|(?:0?2(\/|-|\.)29\3(?:(?:(?:1[6-9]|[2-9]\d)?(?:0[48]|[2468][048]|[13579][26])|(?:(?:16|[2468][048]|[3579][26])00))))|(?:(?:0?[1-9])|(?:1[0-2]))(\/|-|\.)(?:0?[1-9]|1\d|2[0-8])\4(?:(?:1[6-9]|[2-9]\d)?\d{2}))($|\ (?=\d)))?(((0?[8-9])(:[0-5]\d){0,2}(\ AM))|(0?[8-9])(:[0-5]\d){1,2})?$
   

   Attach the Morning Rush Hour type restriction to the attribute session/Traffic/Morning Rush Hour.

   In the Rule Editor, create the filtering rule Mid_MRH as follows:

   • session/Traffic/Morning Rush Hour = <current_date> 9:00 AM

13.20 About Statistic Collectors

Statistic collectors manage the collection and lifecycle of ad hoc Inline Service statistics. A Choice Event Statistics Collector is created by default for each Inline Service. Choice Event Statistics Collectors automatically collect statistics for the events defined by your Inline Service. Statistics collectors have the following properties:

• Description: The description of the statistics collector.

• Collect Statistics On: Statistics can be collected either for each object, such as Choice or Choice Group, individually, or aggregated for all objects of the same type.

• Aggregation: Either record individual events, or record aggregated data. Care should be used in recording individual events, as high transactional systems may suffer from performance issues.

• Aggregation Interval: Amount of time in seconds to aggregate data before recording it through the Statistic Collector.

• Expiration: Choose either Keep forever or Purge old statistics. Care should be used in choosing Keep forever, as data size can be an issue.

• Keep in database for: Amount of time in days that data is kept before purging.

All parameters are configurable through the Decision Studio editor. Choice Event Statistics are displayed as a report in Decision Center.

13.20.1 Creating a Custom Statistics Collector

Using Decision Studio, you can create a custom Statistics Collector to record additional statistics about objects or classes. For instance, you can create a statistics collector to record statistics about Choices. Configure the parameters as described in the previous section.

In code in your Inline Service (for instance, in an Informant or through a Function Call), create a Statistics Collector Factory, passing in the Statistics Collector Name (String) or the statistic type (String):

StatisticCollectorFactory factory = Application.getCollectorFactory(<stat collector name | statistic type>);

Using the factory, create a collector, passing in the event name on which you want to collect statistics (String) or the statistic name (String):

StatCollectorInterface collector = factory.getCollector(<event name | statistic name> );

The event name or statistic name is an arbitrary string that represents what you want to collect.

Then, finally, using the collector, record the event passing in the object_type (String), object_id (String), event value (double), and extra data (string) to record:

Collector.recordEvent(<object_type>, <object_id>, event value, extra data);

The object_type must be a valid Object type, such as Choice, Choice Group, Entity, and so on. The object_id is the internal name of the object.