2 Configuring Oracle RTD Decision Management

Terminology:

The term reference implementation is used in this chapter to refer to the specific Oracle RTD Decision Management application RTD for Marketing Optimization, released with Oracle RTD Base Application.

This chapter contains the following topics:

• Section 2.1, "Oracle RTD Decision Management Architecture Overview"

• Section 2.2, "Configuring Oracle RTD Decision Management"

• Section 2.3, "Configuring and Deploying Base Marketing with Slices"

• Section 2.4, "Configuring Logs"

2.1 Oracle RTD Decision Management Architecture Overview

The following diagram shows the communications at runtime between the various components of Oracle RTD Decision Management after installation:

Description of the illustration clmarch01.gif

The Oracle RTD Decision Manager application is an ADF based web application. The Oracle RTD Decision Manager application makes web service (SOAP) calls to the Oracle RTD workbench service and discovery explorer service running on one of the Oracle RTD Query Servers. These calls are used to retrieve type restrictions, display the rule editor and the model reports. These requests use the username and password that you configured in Section Section 1.2.3.4, "Storing Credentials to Enable Web Service Calls" for WebLogic.

The following diagram shows the communications at runtime between the various components of Oracle RTD Decision Management and the databases they use:

Description of the illustration clmarch03.gif

The Oracle RTD Decision Management application accesses the Decision Management database using the credentials defined in the JNDI datasource specified in Section 1.2.3.3, "Oracle RTD Decision Management Data Source Setup".

The Oracle RTD Decision Management Inline Service loaded in the Oracle RTD application accesses the Decision Management database to retrieve dynamic choices.

The Oracle RTD application accesses the Oracle RTD (SDDS) database using the credentials defined in the SDDS JNDI datasource.

An ETL process transform data from the Decision Analytics tables in the Oracle RTD (SDDS) database into a star schema in the RTD Reports database.

The BI application access its own database schema and reports on the information in the RTD Reports database.

2.2 Configuring Oracle RTD Decision Management

This section contains the following topics:

• Section 2.2.1, "Overview"

• Section 2.2.2, "Oracle RTD Decision Management Metadata Configuration Files"

• Section 2.2.3, "Install and Configure Oracle JDeveloper"

• Section 2.2.4, "Ant Tasks"

• Section 2.2.5, "Java API"

• Section 2.2.6, "Application Extensions"

2.2.1 Overview

Oracle RTD Decision Management applications are built and deployed using Decision Designer.

Decision Designer is the combination of design tools that include JDeveloper, ant, and the metadata files that you set up and used to create the Oracle RTD Decision Management application, as described in Chapter 1, "Installing Oracle RTD Decision Management."

You can use Decision Designer to make changes to the reference implementation, or to build your own application from scratch.

You can also use Decision Designer to further customize the behavior of Oracle RTD Decision Management applications by adding your own logic. You can do so in the model layer and the view controller layer. The two ways to achieve customization are through extensibility of the ADF Framework and through the Decision Manager templates. As an example, the rule to validate that a start date is less than an end date has been implemented through templates in the released application RTD for Marketing Optimization

The following diagram shows the components that are generated by Decision Designer.

Description of the illustration clmarch02.gif

2.2.2 Oracle RTD Decision Management Metadata Configuration Files

The following diagram shows the main Decision Management metadata and database setup files, as released with Oracle RTD Base Application.

Figure 2-1 Main Oracle RTD Decision Manager Metadata and Database Files

Description of "Figure 2-1 Main Oracle RTD Decision Manager Metadata and Database Files"

The folder clm\Build\metadata, also referred to generically as <metadata_modules_home>, contains metadata modules for different applications.

The folder clm\Build\metadata\ref contains the metadata for the reference implementation.

The folder clm\Build\metadata\ref-slices contains the metadata for the reference implementation with the addition of the slices feature; for details, see Section 2.3, "Configuring and Deploying Base Marketing with Slices".

The folder clm\Build\metadata\core contains the metadata module for the core application. Use the core application when you want to create your own application from scratch, it contains the strict minimum for an empty application and Inline Service.

Within a metadata module, two files, config.xml and perspectives.xml, must be in the config/ subdirectory. To configure choice groups, relationship types, and security, you can add as many files as you want in the main directory.

Note:

In all the XML files, the characters "<" and ">" are effectively control characters, and must not be used to specify any metadata element values. For operators, for example, they must be replaced by "&lt;" (instead of "<") and "&gt;" (instead of ">").

This section contains the following topics:

• Section 2.2.2.1, "Config XML File"

• Section 2.2.2.2, "Perspectives XML File"

• Section 2.2.2.3, "Choice Group, Project, and Relationship-Types XML Files"

• Section 2.2.2.4, "User Interface Pages"

• Section 2.2.2.5, "Security XML Files"

• Section 2.2.2.6, "Folder for Choice Group Images"

• Section 2.2.2.7, "Inline Service Folder"

2.2.2.1 Config XML File

config.xml contains general configuration settings:

Under a config node, the following settings are available and must be specified in this order:

• enterpriseAppName (optional) specifies the application name used when multiple applications are deployed into the same domain. The default value is clm.

• webAppContextRoot (optional) specifies the context root used when multiple applications are deployed into the same domain. This element must start with "/", for example /dm2. The default value is /dm.

• datasourceJNDIName (optional) specifies the data source name used when multiple applications are deployed into the same domain. The default value is CLMDS.

• inlineService (required) specifies the Inline Services used. Multiple inline services can be inserted. Each inline service has the following attributes:

  • url: the URL to the RTD server (using HTTP or HTTPS)

  • inlineServiceName: the name of the Inline Service

  • version: must be RTD3

  • deploymentState: must be 5

  • default: one of them must be true. This is the one used for type restrictions, performance goals, segments and the rule editor. The other ones can be used for reports and are optional.

• ownership-mode (optional) specifies the ownership mode for when a choice is edited in a project. The value can be:

  • off (the default)

    The user does not become the owner of the choice when the user edits a choice, and the choice owner is not shown in the Decision Manager user interface.

  • on

    The user becomes the owner of the choice when the user edits a choice, and the choice owner is shown in the Decision Manager user interface. Users can also see the owner in the Audit Trail without adding the Owner attribute on the page.

• display-name (optional): specifies the name of the application as it appears on the login page and at the top of the main page.

• database-encoding (optional): The value of database-encoding depends on the database character set. Oracle RTD Decision Manager uses database encoding to properly enforce byte length throughout the application.

  You must specify the java character set, as defined in java.nio.charset.Charset. For example, for an Oracle database with charset AL32UTF8, the value of database-encoding must be UTF-8. UTF-8 is the default value, used when database-encoding is not specified in config.xml.

• bi-server (optional): specifies the OBIEE server to populate Decision Analytics Dashboard in a tab that contains a bi-dashboard parameter. If you do not have a bi-server in config.xml, Any tab that contains a bi-dashboard will be hidden. bi-server has two attributes:

  • url specifies the URL (http or https) to the OBIEE server; for example, url="http://<server>:<port>/analytics".

  • wsdl-context specifies the WSDL used; for example, wsdl-context="analytics-ws".

2.2.2.2 Perspectives XML File

Perspectives allow business users to view a subset of the choice group graph in the folder tree in the Decision Manager user interface.

For instance, the reference implementation contains the choice groups shown in the following choice group graph:

Description of the illustration cgrels.gif

Four "general" - that is, unqualified - perspectives are defined on top of this graph:

Figure 2-2 Campaigns Perspective

Description of "Figure 2-2 Campaigns Perspective"

Figure 2-3 Tags Perspective

Description of "Figure 2-3 Tags Perspective"

Figure 2-4 Slot Types Perspective

Description of "Figure 2-4 Slot Types Perspective"

Figure 2-5 Channels Perspective

Description of "Figure 2-5 Channels Perspective"

Perspectives are defined in the file clm\Build\metadata\ref\config\perspectives.xml (you can modify this if you use a metatada.module different from ref).

perspectives.xml is made of a <perspectives> root node which contains multiple perspectives.

Properties of perspective:

• name (required): the name of the perspective

• description (optional)

  If present in perspectives.xml, the description appears as the heading for the perspective in the left-hand Perspective panel of the Decision Manager user interface. It also provides the tool tip help information for Decision Manager users as they mouse hover over the perspective name either in the Perspective panel or the dropdown list of perspectives that is displayed by clicking the Perspectives list icon at the top of the Perspectives panel.

• one root node (required)

• multiple level nodes (ordered; optional)

  A single root node can have multiple level nodes in sequence - which enables multiple folders to be visible in sequence under the root choice group in the Decision Manager user interface. Alternatively, to enable a hierarchical folder structure in the Decision Manager user interface, the level nodes under a root node can be nested.

  For example, the associations Slot Type then Creative, Slot-Type then Slot can be represented through the following schematic:

  <root ... "Slot Type"... >
     <level ... "Creative" ... />
     <level ... "Slot" ... />
  </root>
  

  In the Decision Manager user interface, this provides a perspective panel display similar to the following (with showFolder=true):

  
  Description of the illustration slt01.gif
  
  

  On the other hand, a hierarchical association Channel then Placement then Slot can be defined with nested level nodes, as in the following schematic:

  • <root ... "Channel" ... >
       <level ... "Placement" ... >
          <level ... "Slot" ... />
       </level>
    </root>
    

  In the Decision Manager user interface, this provides a perspective panel display similar to the following:

  
  Description of the illustration ch01.gif
  
  

Properties of root:

• choiceGroupId (required) the choice group that will be the root node of the tree

• simpleViewCriteria (optional; see later in this section)

• viewCriteria (optional; see later in this section)

Properties of level:

• choiceGroupId (required) the choice group that will be the node of the tree at that level

• relationshipTypeId (required): the relationship to follow between the previous level and this level

• reversed (optional): whether to follow the relationship from fromChoiceGroupId to toChoiceGroupId (reversed = false) or from toChoiceGroupId to fromChoiceGroupId (reversed = true, the default).

  For the cardinalities *:1, *:0, *:*, and *:1..*, use reversed=true to display many child nodes under each node

• showFolder (optional)

  If showFolder=true, this shows a folder with the name of the relationship (when reversed=true, relationship types folder name is toName, when reversed=false, relationship types folder name is fromName)

  If showFolder=false (the default value), this shows the children directly under the parent node without a folder.

• simpleViewCriteria (optional; see later in this section)

• viewCriteria (optional; see later in this section)

• simpleViewCriteria and viewCriteria (both optional) allow the application of a filter on which choices are displayed. You can specify multiple choices and the resulting filter will be the OR combination of all of them (that is, a choice will appear if it matches any of the criteria).

  Properties of simpleViewCriteria:

  • attribute: the choice attribute to filter on (of the choice group defined by choiceGroupId for this root or level)

  • operator: the operator to use for filtering (see searchCriteriaOperator later in this section for a list of operators)

  • value: the value of the choice attribute to filter on

Example:

<perspective name="Draft Campaigns"> ......
<root choiceGroupId="Campaign">
<simpleViewCriteria attribute="approvalStatus" value="Draft"/>

Note:

To specify criteria for date attributes, the value must be in the format yyyy-mm-dd, such as in:

<simpleViewCriteria attribute="startDate" operator="AFTER" value="2012-11-25" />

Properties of viewCriteria:

• name (optional): the id of a criteria defined on the choice group of the same choiceGroupId as this root or level

2.2.2.3 Choice Group, Project, and Relationship-Types XML Files

You can put as many xml configuration files in the top-level application configuration folder (for the reference implementation, this is clm\Build\metadata\ref) as you wish.

These configuration files let you specify choice groups and relationship types between choice groups.

Relationship types are owned by one side. In other words, to add, edit or delete a relationship between two choices, the user must be able to lock the choice owning that relationship.

When defining choice groups, you also define all the attributes in each choice group and all the user interface views associated with displaying this choice group in the Decision Manager user interface.

When defining choice attributes, you can define which widget is used to display this attribute. Oracle RTD Decision Manager automatically selects a default widget most appropriate for the attribute, but you can override that and specify a different widget.

For the purpose of defining objects and their attributes, projects are considered as choice groups in metadata. The only difference is that you cannot have relationship types between projects and other choice groups. You can define project attributes and project views similar to the way you describe choice group attributes and views. You can even have project attributes with type restrictions by having a choice group in your Inline Service with id Project.

Note: In the following lists, properties shown in bold mean that they are required.

Properties of choice groups:

• id (required): the id of the choice group. It must match the id in the Inline Service

• name (required): the name of the choice group. It will appear as such in the Decision Manager user interface

• description (optional): the description of the choice group.

• searchSortOrder (optional): the order in which this choice group will appear in the search dropdowns (sorted ascending based on this number)

  If you do not put this property, then this choice group will not appear in the dropdowns

• createSortOrder (optional): the order in which this choice group will appear in the create dropdown (sorted ascending based on this number)

  If you do not put this property, then this choice group will not appear in the dropdown

• attributes (optional): an array of attribute (see later in this section)

• criteria (optional): zero to many criteria used for perspective filtering (see later in this section)

Properties of attributes:

• id (required): the id of the choice attribute. It must match the id in the Inline Service.

• name (required): the name of the choice attribute. It will appear as such in the Decision Manager user interface.

• description (optional): the description of the choice attribute.This description will appear in tool tips in the user interface, and is a useful way to give advice to business users on how to enter values for this attribute.

• searchCriteriaOperator: (optional): the operator used for the advanced search.

  If you do not put this property, then this attribute will not show up in the advanced search (unless you use the Add Field dropdown).

  Valid values for strings:

  • "&lt;&gt;" (Not equal to)

  • "NOTBETWEEN" (Not between)

  • "CONTAINS" (Contains)

  • "ISNOTBLANK" (Is not blank)

  • "=" (Equal to)

  • "&lt;" (Less than)

  • "&gt;" (Greater than),

  • "ISBLANK" (Is blank)

  • "&lt;=" (Less than or equal to)

  • "&gt;=" (Greater than or equal to)

  • "DOESNOTCONTAIN" (Does not contain)

  • "STARTSWITH" (Starts with),

  • "ENDSWITH" (End with)

  • "BETWEEN" (Between)

  Valid values for dates:

  • "&lt;&gt;" (Not equal to)

  • "ISBLANK" (Is blank)

  • "ONORAFTER" (On or after)

  • "BEFORE" (Before)

  • "NOTBETWEEN" (Not between)

  • "ISNOTBLANK" (Is not blank)

  • "ONORBEFORE" (On or before)

  • "AFTER" (After)

  • "BETWEEN" (Between)

  • "=" (Equal to)

  Valid values for numbers:

  • "&lt;&gt;" (Not equal to)

  • "ISBLANK" (Is blank)

  • "&gt;" (Greater than)

  • "&lt;=" (Less than or equal to)

  • "&gt;=" (Greater than or equal to)

  • "NOTBETWEEN" (Not between)

  • "ISNOTBLANK" (Is not blank)

  • "BETWEEN" (Between)

  • "&lt;" (Less than)

  • "=" (Equal to)

  The text within each set of parentheses shows what appears in the user interface.

  Note:

  When using operators in metadata elements, make sure that the "less than" operator is written as "&lt;" and the "greater than" operator is written as "&gt;".

  For example:

  <perspective name="Offer Contents Expiring within 7 Days ">
  <root choiceGroupId="OfferContent">
  <simpleViewCriteria attribute="expiringDays" operator="&lt;=" value="7" />
  

• genSysNote (optional): controls whether changing the value of such an attribute should trigger a "Set Attribute" audit trail entry, true or false, true by default

• type (optional; see later in this section)

• restriction (optional; see later in this section)

• default-value (optional; see later in this section)

• control (optional; see later in this section)

Properties of type:

• name (required): the type of the attribute, either "string", "date", "number", or "clob".

• length (optional): for string types, the maximum number of characters that can be entered into the text control. This includes the characters representing the new line. If set to 0 or less, the maximumLength is ignored. Note that in some browsers like Internet Explorer, new line is treated as two characters.

• precision (optional): for number types, the precision is the total number of digits. It must be between 1 to 15. The default value for precision is 5.

• scale (optional): for number types, the scale is the number of digits to the right of the decimal point. It can range from 0 to the value of precision. The default value for scale is 2.

• displayWidth (optional): the size of the text control specified by the number of characters shown. The number of columns is estimated based on the default font size of the browser.

• required (optional): whether a non-null, non-empty value must be entered.

Properties of restriction:

• kind (required): the kind of type restriction, either "lov" (only for string attributes), "regexp" (only for string attributes), or "range" (only for number and date attributes).

• minDefined (optional): for range type restrictions, whether the range has a min bound ("true" or "false")

• maxDefined (optional): for range type restrictions, whether the range has a max bound ("true" or "false")

• minInclusive (optional): for range type restrictions, whether the range min bound is included ("true" or "false")

• maxInclusive (optional): for range type restrictions, whether the range max bound is included ("true" or "false")

(all other type restriction information is retrieved at runtime from the Inline Service)

Properties of default-value:

The default-value tag has one required attribute "value" and two optional attributes: "expression" and "masterValue".

• value (required): a value of the following types: "string", "date", "number" or a Groovy expression.

  For date attributes, the value must be in the format yyyy-mm-dd, for example, 2012-10-08.

  If a string, date or number value is defined for the "value" attribute, then the optional "expression" attribute must be set to "false" or omitted.

• expression: (optional) a Boolean value that indicates whether the "value" attribute specifies a Groovy expression (default is "false"). If the "value" attribute contains a Groovy expression, then expression must be set to "true".

  For example (optional): <default-value value="adf.currentDate" expression="true"...... />

• masterValue (optional): for a project attribute, this specifies the default value for the project attribute in the Main Repository. It may contain a value of the following supported types: string, date, number.

  The following considerations apply for default values for project attributes:

  1. If the "required" attribute (a property of type) is set to "true", then the default-value "value" attribute must be non-empty.

  2. If "expression" is set to "true", then "masterValue" must be non-empty.

  3. During application generation, Oracle RTD Decision Manager sets the required attributes of the Main Repository project based on the default values for these attributes in the project choice group. Expressions cannot be used at that time. So if you use an expression as a default value on a project attribute, you must also add a static value in ”masterValue” that will be used for the Main Repository project.

     In other words, for project attributes where the "value" attribute contains a Groovy expression and where "masterValue" is non-empty, then "masterValue" is used for the column value (for example: <default-value value="adf.currentDate" expression="true" masterValue="2012-08-29" />), otherwise the contents of the "value" attribute are used (for example: <default-value value="2012-08-30" expression="false"/>).

Properties of control:

• name (required): the widget name, which must be one of the following:

  • InputDate - this widget creates a text field for entering dates and a glyph which opens a popup for picking dates from a calendar.

  • InputTextRange - this widget is used for attributes with Range Type Restriction.

  • InputTextRegexp - this widget is used for attributes with Regexp Type Restriction

  • ManyToManyRelationship - this widget is used to show the shuttle for selecting a choice participating in a many-to-many relationship.

  • OneToManyRelationship - this widget is used to show a dropdown list for selecting a choice participating in a one-to-many relationship.

  • OutputRelationship - this widget displays a choice participating in many-to-many or one-to-many relationships.

  • OutputText - this widget displays text (read only).

  • PerformanceGoalsEditor - This creates a widget which helps in assigning weights to the Performance Goals. This widget uses these attributes:

    • inlineService (optional): specifies to which inline service is being used.

    • ruleChoiceGroupId (optional): The name of the choice group whose segments should be displayed in the PerformanceGoalsEditor widget. This is used when the name of the control is set to PerformanceGoalsEditor.

    • includeIlsSegments (optional): It can be set to true or false. This indicates whether static segments should be shown in the PerformanceGoalsEditor widget. This is used when the name of the control is set to PerformanceGoalsEditor.

  • SelectOneChoiceLOV - this widget displays list of values derived from a Type Restriction.

  • Image - this widget displays an image when a choice is opened in view mode. The URL location of the image is determined at run time, during choice creation or editing.

    An Image widget can have two optional attributes:

    • urlPrefix

    • urlPostfix

    The values of urlPrefix and urlPostfix can be used to form the complete URL where the image is to be found. During choice creation or editing, the location of the image is provided either as a complete URL, or as a value to which the urlPrefix and urlPostfix values, if specified in the metadata, can be attached.

    Typically, urlPrefix specifies a general directory that contains multiple images (for example, http://www.oracleimg.com/us/assets/), and choice creators and editors provide the name of a particular image file in that directory (for example, oralogo-small.gif).

  • InputText - This widget is used to enter values for attributes. An InputText widget can have one optional attribute, rows. rows determines if a text field will have one or more rows. If rows is not specified, the default value is 1

  • RTDRuleEditor - the widget displays the ADF RTD Rule Editor for the creation of rules in Decision Manager.

    A RTDRuleEditor widget has the following optional attributes:

    • title

      Specifies the message shown in the Rule Editor as the top Rule Editor entry. By default, the message is {0} is eligible. Use {0} to refer to the choice group name.

    • inlineService

      Specifies the Inline Service used by this rule. If not specified, the default inline service is used.

    • object, type and editingAspect

      This type shows what to enter for these attributes based on the type of rule you want:

      Rule Type	object	type	editingAspect
      Choice Eligibility Rule	Choice Group Id (Optional; this defaults to the choice group ID of the choice group this rule is in)	choice (Optional; this is the default value)	rule (Optional; this is the default value)
      Filtering Rule	(Omit this parameter)	eligibilityRule	whole
      Scoring Rule	(Omit this parameter)	valueRule	rule

      
      

Properties of relationship types:

• id (required): the id of the relationship type. You use this id in your Inline Service for methods such as CLMChoiceBag.getRelatedChoiceIds().

• fromChoiceGroupId (required): the choice group source.

• toChoiceGroupId (required): the choice group destination.

• fromName (required): the owner to destination relationship type name. You use this name in your Inline Service for methods such as CLMChoiceBag.getRelatedChoiceIds().

• toName (required): the destination to owner relationship type name. You use this name in your Inline Service for methods such as CLMChoiceBag.getRelatedChoiceIds().

• fromDescription (optional): the owner to destination relationship type description.

• toDescription (optional): the destination to owner relationship description.

• cardinality (required): From the owner to the destination, can be:

  • *:1

    Each source has one destination

    Each destination has 0 to n sources

  • *:0

    Each source has 0 or 1 destination

    Each destination has 0 to n sources

  • *:*

    Each source has 0 to n destinations

    Each destination has 0 to n sources

  • *:1..*

    Each source has 1 to n destinations

    Each destination has 0 to n sources

    Note:

    For cardinalities *:* and *:1..*, the only valid value for onDelete is "O".

• onDelete (optional): 'C' to cascade delete destination choices, 'O' to make destination choices orphans (that is, only delete the relationship). Explicitly:

  • onDelete="C": Deleting a choice on the "zero or one" side of the relationship will attempt to also delete the choices on the "many" side

  • onDelete="O": Deleting a choice on the "zero or one" side of the relationship will not delete the choices on the "many" side

  For cardinalities *:0 and *:1, the default onDelete value is "C".

• propagateRules (optional): 'N' to not propagate rules (the default), 'D' to propagate rules from owner to destination, 'S' to propagate rules from destination to owner, 'B' to propagate rules in both directions. For more details, see the section "Propagation of Rules" in Oracle Real-Time Decisions Base Application Installation and Reference Guide.

• propagateEvents (optional): 'N' to not propagate events (the default), 'D' to propagate events from owner to destination, 'S' to propagate events from destination to owner, 'B' to propagate events in both directions. For more details, see the Section 9.2.11, "au" in Oracle Real-Time Decisions Base Application Installation and Reference Guide

Properties of criteria:

• id (required): the id of the criteria

• xml (required): the <ViewCriteria> xml of a view criteria defined on this choice group's VO (view object).

Projects

Projects are a special kind of choice group. You can specify additional attributes to projects by specifying a choice-group with id Project. Project attributes appear in the Decision Manager interface when creating projects, viewing projects and project audit trail entries, and in the model layer, where they can be accessed by the Oracle RTD public Java APIs.

2.2.2.4 User Interface Pages

The layout of the pages and tabs used when creating, editing, and viewing choices and projects is determined by XML metadata. These metadata tags may be in any .xml file in the top-level application implementation folder (for the reference implementation, this is clm\Build\metadata\ref), but is typically included in the individual choice group and project XML files.

The metadata tags that control the user interface pages for choices and projects are the following:

• views (optional): top-level tag that is the container for the Decision Manager user interface layout.

• choice-view (optional; within views): the Decision Manager user interface view for choice data of a particular choice group.

  Uniquely identified by choiceGroupId and view type. Supported types for choices and projects are "create", "edit", and "view". In addition, the view type "list" is supported for projects.

  Note:

  When type="list", the choice-view attribute can contain several <table> attributes, each of which can have multiple <column> attributes.

  Each table must have a unique id (in the context of the choice-view) and the attribute viewObjectName (which defines the VO used for the table). ActiveProjectsVO and DeployedProjectsVO are the supported VOs.

  Each column must have the attribute attribute-id. Attributes with type number, date, and string are supported, but not attributes with type clob.

  Columns can have filterable and sortable boolean attributes, for example, <column attribute-id ="Name" filterable ="false" sortable ="false" />. By default, both filterable and sortable are "true" - however, filterable=true is not supported for date attributes.

  For an example, see project.xml for the reference implementation.

• tab (optional; within choice-view): A tab contains one or more pages as its elements. It contains the attributes description, id, name, and type as its attributes. The type attribute can be either choice or report. The following example shows a tab with the type attribute of choice:

  <tab id="Definition" type="choice">
     <name>Definition</name>
     <description>Definition</description>
     <page id="Overview">
       <name>Overview</name>
       <description>Overview</description>
       <page-attributes-group>
         <page-attributes-group>
             <attribute id="Name"/>
             <attribute id="Description"/>
             <attribute id="ChoiceId" readonly="true" viewType="edit view"/>
          </page-attributes-group>
          <note viewType="edit"/>
        </page-attributes-group>
      </page>
     <page id="Attributes">
     <name>Attributes</name>
     <description>Attributes</description>
        <page-attributes-group>
           <page-attributes-group>
              <attribute id="approvalStatus"/>
              <attribute id="code"/>
              <attribute id="startDate"/>
              <attribute id="endDate"/>
              <attribute id="type"/>
              <attribute id="region"/>
           </page-attributes-group>
           <note viewType="edit"/>
         </page-attributes-group>
      </page>
  </tab>
  

• page (optional; within tab): The page that contains the elements required for an operation to be performed on a choice or project. The actual contents of the page are specified in the page-attributes-group tag (see below).

  A page corresponds to either a tab (displayed when choices and projects are edited or viewed) or a train stop (displayed during choice creation). This tab of train stop is embedded under the top level tabs defined by tab metadata (see above).

  Each page must have an id and a name, and may have a description. As well as for identification, the page id is used to assign permissions to a page.

  A page can have the viewType attribute, whose value designates which type of view it belongs to and for which operation it is displayed (one or more of the options "create", "edit", and "view"). If viewType is not specified, the page belongs to all the view types and is displayed for create, edit, and view operations.

  For example, with <page id="Review" viewType="create edit"/>, the page is displayed on create and edit views only.

• page-attributes-group (optional; within page): The attributes, relationships, audit trail notes, and text to be displayed on the page that are required for an operation to be performed on a choice or project. On the page, page attribute groups are separated from each other by a dotted line.

  Every page must have one and only one top level <page-attributes-group/>. Nested occurrences of <page-attributes-group/> are used to group attributes. In the Decision Manager user interface, dotted lines appear where nested page attribute groups are defined in the metadata.

• model-report (optional; within page-attributes-group): Within the Decision Manager metadata you can specify integrating a model report within a tab. The syntax is <model-report reportType="<type>"/>

  Where type is one of:

  • choiceHistory ; that is, Choice Performance Model Counts

  • predReport ; that is, Choice Analysis Predictiveness

  • bestFit ; that is, Choice Analysis Best Fit

  • drivers ; that is, Choice Analysis Drivers

  • modelQuality ; that is, Choice Analysis Model Quality

• bi-dashboard (optional; within page-attributes-group): Within the Decision Manager metadata you can specify integrating integrating a BI dashboard within a tab. The syntax is:

  <bi-dashboard path="<path>">
     <parameter name="<name>" value="<value>"/> 
     …
  </bi-dashboard>
  

  <path> is the path to the dashboard in the web catalog, for instance "/<shared/Decision Analytics - Base Marketing/Creatives/_portal/Creative Performance Dashboard"> and it supports multiple parameter name/value pairs.

  The following example shows how to code a Campaign choice group in the Campaign Performance Dashboard.

  <bi-dashboard path="/shared/Decision Analytics - Base Marketing/Campaigns/_portal/Campaign Performance Dashboard">
     <parameter name='Applications."App Name"' value="#{biParameters.serviceName}"/>
     <parameter name="Choices.HIERARCHY_ID_1" value="#{biParameters.choiceId}"/>
     <parameter name="dashboard.variables['DMFrequency']" value="#{biParameters.timeInterval}"/>
     <parameter name='Time."Calendar Date"' operator="between" value="#{biParameters.localizedStartDateString},#{biParameters.localizedEndDateString}" />
  </bi-dashboard>
  

• attribute (optional; within page-attributes-group): corresponds to the choice group or project attribute.

  May contain the readonly and viewType attributes. As with the page tag, viewType controls whether the attribute appears on some or all types of view.

  All attributes for viewType = "view" are readonly.

  Note:

  The following five built-in attributes are also supported: Name, Description, ChoiceId, EligibilityRule and LockOwner (this last one only when ownership-mode is on in the config XML file.

• relationship (optional; within page-attributes-group): corresponds to the relationship between choice groups.

  May contain the readonly and viewType sub-tags.

  All relationships for viewType = "view" are readonly.

  As with the attribute tag, viewType controls whether the relationship appears on some or all types of view.

• note (optional; within page-attributes-group): renders an Audit Trail Note field.

  Can be required and, as with the attribute tag, it can have viewType.

  Does not have the readonly option, and is not displayed for viewType = "view".

• text (optional; within page-attributes-group): appears as text message on the page.

• audit-trail (optional; within page-attributes-group): renders the Audit Trail for this choice.

2.2.2.4.1 Example of User interface XML for Placement Choice Group

<views>
    <choice-view choiceGroupId="Placement" type="create edit view">
      <tab id="Definition" type="choice">
        <name>Definition</name>
        <description>Definition</description>
        <page id="Overview">
          <name>Overview</name>
          <description>Overview</description>
          <page-attributes-group>
            <page-attributes-group>
              <attribute id="Name"/>
              <attribute id="Description"/>
              <attribute id="ChoiceId" readonly="true" viewType="edit view"/>
            </page-attributes-group>
            <page-attributes-group>
              <relationship id="Placement to Channel"/>
            </page-attributes-group>
            <note viewType="edit"/>
          </page-attributes-group>
        </page>
        <page id="Attributes">
          <name>Attributes</name>
          <description>Attributes</description>
          <page-attributes-group>
            <page-attributes-group>
              <attribute id="type"/>
              <attribute id="url"/>
            </page-attributes-group>
            <note viewType="edit"/>
          </page-attributes-group>
        </page>
        <page id="Rules">
          <name>Rules</name>
          <description>Rules</description>
          <page-attributes-group>
            <attribute id="EligibilityRule"/>
          <page-attributes-group>
            <note viewType="edit"/>
          </page-attributes-group>
          </page-attributes-group>
        </page>
        <page id="Confirm" viewType="create">
          <name>Confirm</name>
          <description>Confirm</description>
          <page-attributes-group>
            <text value="#{nls['ID_EXPLAIN_VALUE']}"/>
            <text value="#{nls['ID_EXPLAIN_ALLOWED']}"/>
            <attribute id="ChoiceId" readonly="false"/>
            <note/>
            <page-attributes-group>
              <text value="#{nls['CONFIRM_EXPLAIN_VALUE']}"/>
              <attribute id="Name" readonly="true"/>
              <attribute id="Description" readonly="true"/>
              <attribute id="type" readonly="true"/>
              <attribute id="url" readonly="true"/>
            </page-attributes-group>
            <page-attributes-group>
              <relationship id="Placement to Channel" readonly="true"/>
            </page-attributes-group>
            <attribute id="EligibilityRule" readonly="true"/>
          </page-attributes-group>
        </page>
      </tab>
      <tab id="Performance" type="report">
        <name>Performance</name>
        <description>Performance</description>
        <page id="PerformanceDashboard" viewType="view">
          <name>Dashboard</name>
          <description>Dashboard</description>
          <page-attributes-group>
            <bi-dashboard path="/shared/Decision Analytics - Base Marketing/Placements/_portal/Placement Performance Dashboard">
              <parameter name='Applications."App Name"'
                         value="#{biParameters.serviceName}"/>
              <parameter name="Choices.HIERARCHY_ID_4"
                         value="#{biParameters.choiceId}"/>
              <parameter name="dashboard.variables['DMFrequency']"
                        value="#{biParameters.timeInterval}"/>
              <parameter name='Time."Calendar Date"' operator="between"
                         value="#{biParameters.localizedStartDateString},#{biParameters.localizedEndDateString}" />
            </bi-dashboard>
          </page-attributes-group>
        </page>
        <page id="ChoiceHistory" viewType="view">
          <name>Model Counts</name>
          <description>Model Counts</description>
          <page-attributes-group>
            <model-report reportType="choiceHistory"/>
          </page-attributes-group>
        </page>
      </tab>
      <tab id="Analysis" type="report">
        <name>Analysis</name>
        <description>Analysis</description>
        <page id="PredReport" viewType="view">
          <name>Predictiveness</name>
          <description>Predictiveness</description>
          <page-attributes-group>
            <model-report reportType="predReport"/>
          </page-attributes-group>
        </page>
        <page id="BestFit" viewType="view">
          <name>Best Fit</name>
          <description>Best Fit</description>
          <page-attributes-group>
            <model-report reportType="bestFit"/>
          </page-attributes-group>
        </page>
        <page id="Drivers" viewType="view">
          <name>Drivers</name>
          <description>Drivers</description>
          <page-attributes-group>
            <model-report reportType="drivers"/>
          </page-attributes-group>
        </page>
        <page id="ModelQuality" viewType="view">
          <name>Model Quality</name>
          <description>Model Quality</description>
          <page-attributes-group>
            <model-report reportType="modelQuality"/>
          </page-attributes-group>
        </page>
      </tab>
      <tab id="Audit" type="report">
        <name>Audit Trail</name>
        <description>Audit Trail</description>
        <page id="AuditTrail" viewType="view">
          <name>Audit Trail</name>
          <description>Audit Trail</description>
          <page-attributes-group>
            <audit-trail/>
          </page-attributes-group>
        </page>
      </tab>
    </choice-view>
  </views>

2.2.2.5 Security XML Files

By default, all security metadata is in a file called security.xml but you may create as many files containing security information as you want.

There are different root nodes that apply to security:

• <application-roles> contains the definition of application roles.

• <enterprise-roles> contains the definition of enterprise roles, which are uploaded as WebLogic groups in a development environment, and can be used in production environment to map application roles to groups you define in the WebLogic or WebSphere console.

• <users> contains the definition of users, which are uploaded as WebLogic users in a development environment, but are not meant to be used in a production environment

<application-roles>

<application-roles> contains multiple application-role.

Each application role has a name and permissions.

<permissions> has multiple permission children, each having a <resource-name>, a <resource-type>, and <actions>.

The resource type can be perspective, choice group, project, choice view page, and cache. Cache is specifically for admin users.

For the perspective resource type:

• The resource name is the name of the perspective as defined in perspectives.xml, or _all_ to mean all perspectives.

• The only action is view, which means that the user having this application role will be able to see and select this perspective in the Decision Manager user interface.

For the choice group resource type:

• The resource name is the id of the choice group as defined in one of the other configuration files, or _all_ to apply to all choice groups.

• The actions are a comma separated list of one or multiples of:

  • create: to be able to create a choice of that choice group in a project

  • read: to be able to view choices of that choice group

  • update: to be able to edit a choice of that choice group in a project, and to be able to discard any changes (including addition and deletion) on a choice of that choice group

  • delete: to be able to delete a choice of that choice group in a project

  • own: to be able to edit (in the same project) and become owner of a choice that is owned by someone else

For the project resource type:

• The resource name must be _all_.

• The actions are a comma separated list of one or multiples of:

  • create: to be able to create a project

  • commit: to be able to commit a project

  • discard: to be able to discard a project and all changes within it

  • update: to be able to update a project

  • read: to be able to log in to the application and to use the Decision Manager user interface

For the choice view page resource type:

• The resource name has the following format {choiceGroupId} / {pageId}.

  Both {choiceGroupId} and {pageId} can be specific Ids or _all_:

  • _all_/_all_ means the permission is granted for all pages in all choice groups

  • _all_/Confirm means the permission is granted for all pages with pageId=Confirm in all choice groups

  • Offer/_all_ means the permission is granted for all pages in the Offer choice group.

• The actions are a comma separated list of one or multiples of:

  • create: to be able to create objects in the pages specified by <resource name>

  • view: to be able to view objects in the pages specified by <resource name>

  • update: to be able to objects in the pages specified by <resource name>

  • list: to be able to view lists of projects in the pages specified by <resource name>

    For "list" the choice group must be Project and the resource name must be a page representing a list of projects to be shown in the View Projects tab.

• Example

  The following <permission> metadata enables all pages of all choice groups to be viewed, and all Overview pages (technically, pages with pageId=Overview) in all choice groups to be edited:

  <permission>
     <resource-type>choice view page</resource-type>
     <resource-name>_all_/_all_</resource-name>
     <actions>view</actions>
  </permission>
  <permission>
     <resource-type>choice view page</resource-type>
     <resource-name>_all_/Overview</resource-name>
     <actions>update</actions>
  </permission>
  

For the cache resource type:

• This permission, to be used only by admin users, is for cleaning the RTD cache. This cache contains the type restrictions information retrieved from the Inline Service.

  Example:

  <permission>
    <resource-type>cache</resource-type>
    <resource-name>rtd-metadata</resource-name>
    <actions>reset</actions>
  </permission>
  

For the configuration resource type:

• This permission, to be used only by admin users, is for accessing the Inline Service Configuration dialog. This dialog lets administrators specify how to connect to RTD for retrieving type restrictions, displaying the rule editor and displaying reports.

  Example:

  <permission>
    <resource-type>configuration</resource-type>
    <resource-name>ils-configuration</resource-name>
    <actions>create,read,update,delete</actions>
  </permission>
  

<enterprise-roles>

<enterprise-roles> has multiple <enterprise-role>.

Each <enterprise-role> has a name and <application-roles>, which is a comma separated list of application roles that are granted to members of that enterprise role.

<users>

<users> has multiple <user>.

Each <user> has a name, a display name, a description and credentials which is the password in an encrypted form. See previous sections for how to get the correct credential string.

Each <user> has <application-roles>, which is a comma separated list of application roles that are granted to members of that enterprise role.

2.2.2.6 Folder for Choice Group Images

For each choice group you have defined, add a 16x16 png image in the images\group folder (under <metadata_modules_home>\<your_application>) named after the choice group id.

The file must be called <choiceGroupId>.png.

Both parts of the file name are case-sensitive:

• <choiceGroupId> must exactly match the name of the choice group id, as set up in the choice group configuration xml file (see Section 2.2.2.3, "Choice Group, Project, and Relationship-Types XML Files")

• png must be all lower-case

2.2.2.7 Inline Service Folder

The RTD_Base_Marketing Inline Service released with the RTD for Marketing Optimization application is in the service folder under <metadata_modules_home>\ref, that is, in clm\Build\metadata\ref\service. This Inline Service is described in more detail in Oracle Real-Time Decisions Base Application Installation and Reference Guide.

2.2.3 Install and Configure Oracle JDeveloper

To compile and create an EAR file for your Decision Manager applications, you must install JDeveloper 11g Release 1. Once installed, do the following:

1. Open JDeveloper and

   1. Select Tools, then Preferences.

   2. Select the Environment tab and set the Encoding to UTF-8.

   3. Click OK.

2. Create an ANT_HOME and a JAVA_HOME environment variable pointing to the location where ant and the Java JDK are installed, for instance:

   ANT_HOME=<Oracle JDeveloper Install dir>\Middleware\jdeveloper\ant
   JAVA_HOME=<path to Java JDK>
   

3. Add %ANT_HOME%\bin and %JAVA_HOME%\bin to your PATH.

4. Create a file called clm-build.properties in your home directory (on Windows, this folder can be reached using the variable %HOMEPATH%). This file should contain:

   jdeveloper.home=<Oracle JDeveloper Install dir>/Middleware
   

   For example, C:/JDeveloper/Middleware

Note:

Use the forward slash character "/" in the file, even on Windows.

2.2.4 Ant Tasks

After you have modified the metadata, you need to run the application generation tool ant to generate the application.

The clm\Build directory contains the ant tasks to perform the generation.

The ant targets are as follows:

• ear - creates EAR file for deployment in production mode

• clean - cleans projects

• generate - generates the application.

• clean-generated - removes generated code

The ant option "generate" takes two optional parameters:

• metadata.module: this specifies which subfolder of clm\Build\metadata must be used to generate the application. The default value is ref.

• changes: this specifies whether to warn you and abort the generation if it is about to overwrite files that have been modified. Use value overwrite to overwrite files. The default value is to omit this parameter, in which case ant will warn and fail.

Example:

To generate an application in clm\Build\metadata\myapp, call:

ant -Dmetadata.module=myapp generate

Then

ant ear (for deploying to production, otherwise deploy from JDeveloper)

Notes:

• After generation, the database schema may have changed. You should then run drop ils.sql then drop core.sql (or drop and recreate the database user), then load core.sql then load ils.sql. This will delete any choice you have in the database. To preserve choices, you can compare the previous and new sql and just make these changes. For instance, if you added a choice attribute, you can alter the table to add a column, and recreate the view associated with it.

• In most cases, you should not modify any of the files that are generated by ant generate, so you should not use –Dchanges=overwrite.

  Customization can be achieved without modifying any of the files created by ant generate. Use the extensibility of the ADF Framework or the Oracle RTD Decision Manager templates to extend the behavior of the application without modifying any of the core and generated files.

2.2.5 Java API

The behavior of the Oracle RTD Decision Management business layer and view controller layer can be further extended by the use of the Java API that comes with it. The javadoc for this Java API can be found in clm\lib\clm-model-api-javadoc.jar and also clm\lib\clm-ui-core-api-javadoc.jar.

2.2.6 Application Extensions

This section contains the following topics:

• Section 2.2.6.1, "Adding an Attribute to a Choice Group or Project"

• Section 2.2.6.2, "Adding a Choice Group"

• Section 2.2.6.3, "Creating a Relationship Type Between Two Choice Groups"

• Section 2.2.6.4, "Modifying Perspectives"

2.2.6.1 Adding an Attribute to a Choice Group or Project

In order to add an attribute to a choice group or project, follow these steps:

• Modify the xml where the choice group or project is defined in folder clm\Build\metadata\ref.

• Run application generation again: in folder clm\Build, run ant generate.

• Since adding an attribute to a project or choice group modifies the database, you have to recreate the database. In order to do this, call drop ils.sql then drop core.sql then load core.sql then load ils.sql (these files are in clm\Database\sql and clm\Database\sql\ils). If you do not want to lose your database data, you can compare the sql to the previous one and alter the table to add the column and recreate the associated view.

• You can now deploy the new version of the Decision Management application using JDeveloper.

• For new choice group attributes, you have to add the choice attribute to the choice group in your Inline Service as well. Make sure the id is the same as the one you entered in the XML metadata in the first step. Redeploy the Inline Service.

2.2.6.2 Adding a Choice Group

In order to add a choice group, follow these steps:

• Add an xml file for this new choice group in folder clm\Build\metadata\ref.

• Add an image for this choice group in folder clm\Build\metadata\ref\images\group.

• Run application generation again: in folder clm\Build, run "ant generate".

• Since adding a choice group modifies the database, you have to recreate the database. In order to do this, call drop ils.sql then drop core.sql then load core.sql then load ils.sql (these files are in clm\Database\sql and clm\Database\sql\ils). If you do not want to lose your database data, you can compare the sql to the previous one and add the new table, the new view and one row in the CHOICE_GROUP table.

• You can now deploy the new version of the Decision Management application using JDeveloper.

• You have to add the choice group in your Inline Service as well. Make sure the ids are the same as the ones you entered in the xml metadata in the first step. Make sure the choice group you add is under CLM Base choice group. Add the choice group in the CLM ILS Choice Groups application parameter. Redeploy the Inline Service.

2.2.6.3 Creating a Relationship Type Between Two Choice Groups

In order to create a relationship type between two choice groups, follow these steps:

• Edit relationship-types.xml in folder clm\Build\metadata\ref and add the new relationship type.

• Run application generation again: in folder clm\Build, run ant generate.

• Since adding a choice group modifies the database, you have to recreate the database. In order to do this, call drop ils.sql then drop core.sql then load core.sql then load ils.sql (these files are in clm\Database\sql and clm\Database\sql\ils). If you do not want to lose your database data, you can compare the sql to the previous one and add one row in the RELATIONSHIP_TYPE table.

• You can now deploy the new version of the Decision Management application using JDeveloper.

• You can (but do not have to) add choice attributes in both choice groups in the Inline Service to follow the relationship. For an example, see how Offer has a campaign choice attribute and a creatives choice attribute. Redeploy the Inline Service.

2.2.6.4 Modifying Perspectives

In order to modify perspectives, follow these steps:

• Edit perspectives.xml in folder clm\Build\metadata\ref\config.

• Run application generation again: in folder clm\Build, run ant generate.

• You can now deploy the new version of the Oracle RTD Decision Management application using JDeveloper.

2.3 Configuring and Deploying Base Marketing with Slices

This section shows you how to configure and deploy Base Marketing with Slices. It contains these topics:

• Section 2.3.1, "Preparing Base Marketing with Slices Application for Deployment"

• Section 2.3.2, "Build and Generate the EAR"

• Section 2.3.3, "Prepare the SQL Scripts for Database Setup"

• Section 2.3.4, "Install Oracle RTD Decision Manager Slices Application"

• Section 2.3.5, "Configuring Security"

• Section 2.3.6, "Mapping Users or Groups to Slice-based Roles"

2.3.1 Preparing Base Marketing with Slices Application for Deployment

To generate the clm.ear file for the Base Marketing With Slices application, perform the following tasks:

1. Update Oracle RTD Decision Manager Metadata Configuration Files

2. Update Relationship-Types and Relationship-Slices XML Files for Choice Groups

3. Understand User Interface Pages

4. Understand Security XML Files

5. Understand the Folder for Role and Slice Choice Group Images

6. Understand the Slices Inline Service Folder

2.3.1.1 Update Oracle RTD Decision Manager Metadata Configuration Files

This sections explains the changes made in metadata and its files for Slices feature.

To use Slices, you need to define in the metadata:

• Slice and Role choice groups

• Relationships between roles, slices and project choice groups, as declared in relationship-slices.xml from ref-slices metadata.

Relationships between all other choice groups and slices are generated automatically during code generation.

2.3.1.1.1 Config XML file

The attributes and its description remain the same as described in Section 2.2.2.1, "Config XML File" except that the values or default values for some of the attributes are those described here:

• inlineService: The default value of the inlineServiceName attribute would be RTD_Base_Marketing_Slices.

• datasourceJNDIName: The default value would be DM_SLICES. Modify it if datasource is created with different name.

• enterpriseAppName: The default value is RTD Base Marketing (with slices).

• webAppContextRoot: The default value is /dmsl. Modify it if necessary and ensure that the modified value is used when trying to access the Slices URL.

2.3.1.1.2 Perspectives XML File

In addition to perspectives explained in Section 2.2.2.2, "Perspectives XML File", Slices requires two additional perspectives:

• Roles

• Slices

The Roles and Slices perspectives is having Single root node with no multiple levels. They are defined in perspectives.xml as shown here:

<perspective name="Roles">
   <description>Roles</description>
   <root choiceGroupId="Role">
   </root>
</perspective>
<perspective name="Slices">
   <description>Slices</description>
   <root choiceGroupId="Slice">
   </root>
</perspective>
<perspective name="Segments">
   <description>Segments</description>
   <root choiceGroupId="Segment" />
</perspective>
<perspective name="Decisions">
   <description>Decisions</description>
   <root choiceGroupId="Decision" />
</perspective>

2.3.1.2 Update Relationship-Types and Relationship-Slices XML Files for Choice Groups

This section describes the new Choice Groups,”Role” and ”Slice”, added for Slices-based marketing application and the additions and modifications they require in the relationships metadata file.

2.3.1.2.1 Choice Group XML Files

In addition to the existing choice groups used for Base Marketing application, the Slices feature introduces two new choice groups:

• Role: role.xml (ref-slices/ folder)

• Slice: slice.xml (ref-slices/ folder)

The following table describes the properties and default values for the Role and Slice Choice groups:

Property	Role	Slice	Description
id	Role	Slice
name	Role	Slice
description	A Role	A slice
searchSortOrder	1011	1012
createSortOrder	1011	1012

Unlike other Choice Groups, for example Campaign or Creative, the Role and Slice Choice Groups have no attributes.

2.3.1.2.2 Relationship-Slices XML Files

The new file relationship-slices.xml has been added to define relationship between Project, Role and Slice Choice Groups.

For operations, Roles have relationship to slices:

• Role to Slice Create: Slices that should be assigned by default for newly created choices.

• Role to Slice Read: Slices assigned to choices that can be read but not changed.

• Role to Slice Write: Slices assigned to choices that can be read and changed.

  Note:

  Names of these relationships cannot be changed.

For operations, Projects are assigned to roles as follows:

• Project to Role Read: Project is read-only for users who have specified roles.

• Project to Role Write: Project can be changed by users who have specified roles.

Note:

Names of these relationships cannot be changed.

You should have at least one slice-related role to log in to an application. Some database initial script should be used to create an administrator user and ”slice-related role” in application (”ref-slices” metadata contains script ”insert ils data.sql”). Also, if some choices created via database initial script, they should be linked to some slices, because choices without slices can't be accessible via application.

After that, administrator will be able to create additional ”slice-related” roles and assign slices to choices.

2.3.1.2.3 Relationship-Types XML File

There is no change to this file for Slices based Marketing application as the relationship between other choice groups like Campaign, Creative etc and Slice choice groups would be generated automatically during code generation phase.

2.3.1.3 Understand User Interface Pages

The layout of the pages and tabs used when creating, editing, and viewing choices and projects is determined by XML metadata defined in role.xml, slice.xml and project.xml.

Key changes you should note are:

• project.xml:

  • Project to Role Read relationship is defined within the page-attributes-group on the Overview page.

  • Project to Role Write relationship is defined within the page-attributes-group on the Overview page

• role.xml:

  • Role to Slice Read relationship is defined within the page-attributes-group for the Slices and Confirm pages.

  • Role to Slice Write relationship is defined within the page-attributes-group for the Slices and Confirm pages.

  • Role to Slice Create relationship is defined within the page-attributes-group for the Slices and Confirm pages.

• slice.xml:

  By default, slice.xml has two pages, Overview and Confirm. Since its page does not have to display any other choice group information, the relationship is not defined here.

2.3.1.4 Understand Security XML Files

By default, all security metadata is in security.xml. For more information, see Section 2.2.2.5, "Security XML Files".

2.3.1.5 Understand the Folder for Role and Slice Choice Group Images

The Role.png and Slice.png image files are stored in <metadata_modules_home>\ref-slices\images\group.

2.3.1.6 Understand the Slices Inline Service Folder

The RTD_Base_Marketing_Slices Inline Service released with Oracle RTD is in the service folder under <metadata_modules_home>\ref-slices; that is, in clm\Build\metadata\ref-slices\service. This Inline Service is described in more detail in Oracle Real-Time Decisions Base Application Installation and Reference Guide.

2.3.2 Build and Generate the EAR

If you have made changes to the configuration:

1. From the clm\Build directory, run this command:

   ant generate –Dmetadata.module=ref-slices
   

2. Then run this command:

   ant ear
   

The clm.ear file is now in the folder clm\deploy and is ready to be used in production.

2.3.3 Prepare the SQL Scripts for Database Setup

To prepare the SQL scripts for the database, do the following:

1. Create the database user by following the steps in Section 1.2.3.2, "Oracle RTD Decision Management Database Creation".

2. Execute load core.sql and load ils.sql to set up the production database. These files are located in clm\Database\sql and clm\Database\sql\ils. respectively.

3. Provide the Inline Service. It should be located in clm\Build\metadata\ref-slices\service.

2.3.4 Install Oracle RTD Decision Manager Slices Application

This section describes how to install Oracle RTD Decision Manager Slices. This task comprises these steps:

1. Configure and Set Up the Application Server

2. Set Up the Oracle RTD Decision Manager Data Source for Slices

3. Deploy the Inline Service

4. Deploy Oracle RTD Decision Manager Slices

2.3.4.1 Configure and Set Up the Application Server

Configure and set up the application server as described in Chapter 1, "Installing Oracle RTD Decision Management".

2.3.4.2 Set Up the Oracle RTD Decision Manager Data Source for Slices

Create a data source with following properties:

• Name: DM_SLICES_DS or a similar value

• JNDI Name: The proper JNDI name.

  The JNDI name must be the JNDI name you specify in config.xml and in your Inline Service application parameter; by default, this is DM_SLICES

• Database Type: Oracle

Note:

Ensure that the Database User name and Password match the values that you set up in Section 2.3.3, "Prepare the SQL Scripts for Database Setup".

2.3.4.3 Deploy the Inline Service

Once deployed, RTD Slices requires its Inline Service to be running in the Oracle RTD instance. You should have received this Inline Service with the clm.ear file or it should be located in clm\Build\metadata\ref-slices\service.Using Decision Studio, deploy this Slices Inline Service to the Oracle RTD instance that is configured in config.xml or in any other RTD instance that can be accessed through Decision Manager Slices application.

2.3.4.4 Deploy Oracle RTD Decision Manager Slices

To deploy Oracle RTD Decision Manager Slices, do the following:

1. Ensure that the credentials used to access Oracle RTD from Oracle RTD Decision Manager are set up, as described in Section 1.2.3.4, "Storing Credentials to Enable Web Service Calls".

2. Deploy the Oracle RTD Decision Manager. Use the EAR either generated in Section 2.3.2, "Build and Generate the EAR".

3. Deploy the EAR for your application server.

The deployed Oracle RTD Decision Manager Slices application is now accessible at the URL http://<server>:<port>/dmsl.

The URL depends the value provided in config.xml for <webAppContextRoot>. By default dmsl is used as context root, as shown here.

<webAppContextRoot>/dmsl</webAppContextRoot>

If necessary, you can change dmsl to a different value and access URL by using that name.

2.3.5 Configuring Security

In addition to the security configuration defined in Section 1.4, "Security Configuration", Slices provides an additional security layer by introducing new Role called Slice-based Role. In order to view and apply Slice based permission to choices, a user needs to have Slice-based Role in addition to standard Roles and configuration defined in Section 1.6.

This section describes the tasks necessary to configure security for your Oracle RTD Slices implementation:

1. Define Slice-based Roles in security.xml

2. Create an Application Role (Standard Role) with Permission for Role and Slice Choice Groups in security.xml

3. Create an Application Role for a Slice-based Role in security.xml

4. Generate the Decision Manager Application

5. Deploy RTD Decision Manager

2.3.5.1 Define Slice-based Roles in security.xml

The choice group level permissions and Slice based permission together determine the actions allowed to a user.

To access choices in a Slice-based application, the application role should have at least one of the CRUD (Create, Read, Update or Delete) permissions on the Role and Choice groups, in addition to the Slice-based Role permission.

You work with Decision Manager within the scope of one of the Slice-based roles to which he or she belongs. The topmost drop-down in the user interface is a role selector with which you select a role from those to which you belong:

Description of the illustration slices01.gif

The current role chosen from the drop-down and the choice group, page, and perspective permissions act as a filter to restrict what you can do while acting in that role. Some examples are:

• A user could be an administrator with CRUD permission on all choice groups but when acting in a specific role, you would only be able to perform the actions allowed by that role.

• A user with few permissions could act in a role that allows many actions but might still be restricted to the subset for which he or she already has permission.

• Some pages might be only for roles that, for instance, allow a user to hide some attributes or make them read-only for some roles even if the user has permission to edit that attribute in other roles.

• Some perspectives can be made available only for some roles, which are restricted to the perspectives only a given role can see; for example, no administration perspective for someone with a basic user role.

  For example, if a user is mapped to the roles CLMSliceAdministrator and Cross Sell User Role and Cross Sell User Role has been selected, that user can only Create, Edit or View Cross Sell slice based choices but cannot view Acquisition slice based choices, even though the user is an Administrator.

security.xml contains the application roles that can be assigned to a user through Enterprise Manager or an application server, such as WebLogic.

The application roles defined in security.xml contains a set of permissions on the Choice Group, View Page, and so on that determine which privileges of a user or a group linked to these application roles.

RTD Slices enables users to create a new set of Slice-based application roles, with the user can define a Slice-based permission on choices in addition to a Choice Group permission.

The Slice-based Role—that is, choices of type Role choice group—are available for assignment to users through EM if the role is defined in security.xml with the same name used in the CLM database.

2.3.5.2 Create an Application Role (Standard Role) with Permission for Role and Slice Choice Groups in security.xml

To create an application role, do the following:

1. In clm/Build/metadata/ref-slices, edit security.xml or create a different file, such as groups.xml.

2. Create an application Role in security.xml that has either a choice group permission on individual choice groups like Role, Slice, and other choice groups or on _all_ (all choice groups). This ensures that users mapped to this role have permission to access respective choices. See the following example cases:

To create an application role having CRUD permission on Campaign, Slice, Role, and Offer choice group, you would enter the following in security.xml:

Example Case 1:

<application-role>
   <name>CLMSliceManager</name>
   <permissions>
      <permission>
         <resource-type>choice group</resource-type>
         <resource-name>Campaign,Slice,Role,Offer</resource-name>
         <actions>create,read,update,delete,own</actions>
      </permission>
   </permissions>
</application-role>

Example Case 2:

To create an application role that does not have CRUD permission on Slice and Role, you would enter the following code in security.xml. This code indicates that, except for Role and Slice choices, all other choices have permission for CRUD operations.

<application-role>
   <name>CLMSliceManager</name>
   <permissions>
      <permission>
         <resource-type>choice group</resource-type>
         <resource-name>^Role,Slice</resource-name>
         <actions>create,read,update,delete,own</actions>
      </permission>
   </permissions>
</application-role>

To create an application role having permission for both Roles and Slices perspectives:

1. Use Roles and Slices as the value for the <resource-name> attribute for the perspective type.

2. Use _all_ as the value for the <resource-name> attribute of perspective type.

Example Case 1:

This example gives the user view permission on the Roles, Slices, and Campaign perspective.

<permission>
  <resource-type>perspective</resource-type>
  <resource-name>Roles,Slices,Campaigns</resource-name>
  <actions>view</actions>
</permission>

Example Case 2:

This example gives the user view permission on all perspectives except Roles and Slices.

<permission>
  <resource-type>perspective</resource-type>
  <resource-name>^Roles,Slices </resource-name>
  <actions>view</actions>
</permission>

Note:

If security.xml or any of its related files, such as groups.xml, is modified or added, then build, generate, and deploy the application by following the steps in Section 2.3.5.4, "Generate the Decision Manager Application".

2.3.5.3 Create an Application Role for a Slice-based Role in security.xml

To add or create an application role in Oracle RTD Decision Manager metadata and to map it to Decision Manager Slice based Role choices (in Decision Manager metadata database), do the following:

The following illustration lists the Slice-based Roles defined in CLM database.

Description of the illustration slices02.gif

1. Note the names of the Roles that you want to make available to users.

2. In clm/Build/metadata/ref-slices, edit security.xml, or create a different file, such as groups.xml.

3. Create an entry in security.xml or groups.xml as shown here:

   <application-role>
     <name>Shared Role</name>
   </application-role>
   <application-role>
     <name>Acquisition Super User Role</name>
   </application-role>
   <application-role>
     <name>Acquisition User Role</name>
   </application-role>
   

Note that the names of the application roles should match those for the Role based choices created in the Decision Manager database.

The Shared Role choice created in the Decision Manager database should have an entry for the application role in security.xml where the <name> attribute has Shared Role as its value, as shown in the following example.

<application-role>
  <name>Shared Role</name>
</application-role>

Note:

If security.xml or any of its related files, like groups.xml is modified or added, then build, generate, and deploy the application by following the steps in Section 2.3.5.4, "Generate the Decision Manager Application".

2.3.5.4 Generate the Decision Manager Application

To generate the Decision Manager application, do the following:

1. Open a command prompt and navigate to the clm/Build directory.

2. Run the following command:

   ant generate –Dmetadata.module=ref-slices
   

3. In JDeveloper, verify that the group now shows up in jazn-data.xml and is mapped to the CLMSliceAdministrator application role.

2.3.5.5 Deploy RTD Decision Manager

Deploy the Decision Manager application to WebLogic Server. For deployment instructions, see Section 1.2.3.5, "Oracle RTD Decision Management Application Deployment".

2.3.6 Mapping Users or Groups to Slice-based Roles

This section explains how to map the users and groups created in your organization to the Slice-based Decision Manager application roles and/or the Standard roles.

Before you begin, ensure that Slice-based Role choices are already created in Decision Manager following instruction given in user guide.

In a production environment, you typically manage your enterprise users and groups outside of Oracle RTD Decision Manager and only map these users and groups to Decision Manager application roles.

To map users or groups to Decision Manager application roles, do the following:

1. Open the Enterprise Manager on the Administration Server.

2. Log in with the administrator username and password.

3. In the Target Navigation Pane, select the RTD Base Marketing (with slices) deployment: Application Deployments then Internal Applications then RTD Base Marketing (with slices).

4. In the RTD Base Marketing (with slices) window, from the Application Deployment dropdown menu, select Security then Application Roles and click Search application roles.

5. Click CLMSliceAdministrator, CLMSliceAuthor or CLMSliceConsumer depending on the level of permissions you want for your users or groups.

6. Click Edit the selected application role.

7. Click Add roles.

8. Repeat steps 4 through step 7 to add Slice based Role like Shared Role, Cross Sell Super User Role, and so on.

9. In the Type dropdown list, change Application role to User.

10. Search for your user and click OK.

11. To add a group, click Add roles and in the Type drop-down list, change Application role to Group.

12. Search for your group and click OK.

13. Click OK.

2.4 Configuring Logs

Oracle RTD Decision Management uses Java Logging API. There are two ways to configure Java Logging API (http://java.sun.com/j2se/1.5.0/docs/guide/logging/overview.html):

• Update global logging configuration of the JRE which is used to start WebLogic: JAVA_HOME/jre/lib/logging.properties

• Create separate logging properties file (for example c:\src\clm\logging.properties) and pass it in the -Djava.util.logging.config.file argument to the Weblogic.Server startup command.

  To pass this argument append the line:

  set JAVA_OPTIONS=%JAVA_OPTIONS% -Djava.util.logging.config.file= c:\src\clm\logging.properties

  to

  C:\Oracle\Middleware\user_projects\domains\<RTDCLM_domain>\bin\setDomainEnv.cmd

Sample logging.properties file:

# Specify the handlers to create in the root logger
.level= INFO
handlers = weblogic.logging.ServerLoggingHandler
# Register handlers for the oracle.rtd.clm. and its child loggers
oracle.rtd.clm.handlers = java.util.logging.FileHandler, java.util.logging.ConsoleHandler, weblogic.logging.ServerLoggingHandler
oracle.rtd.clm..useParentHandlers = false
oracle.rtd.clm.level = ALL
#Console handler
java.util.logging.ConsoleHandler.level = INFO
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
# Set the default logging level for new FileHandler instances
weblogic.logging.ServerLoggingHandler.level = ALL
#File handler
java.util.logging.FileHandler.pattern = %h/java%u.log
java.util.logging.FileHandler.limit = 50000
java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.FileHandler.level=ALL

This configuration logs message with level INFO to the WebLogic Server Startup Console and all messages to the java*.log file in the user home directory. To change log level for Oracle RTD Decision Management applications replace oracle.rtd.clm.level = ALL

with oracle.rtd.clm.level = SEVERE|WARNING|INFO|CONFIG|FINE|FINER|FINEST.

Additional info can be found at the following site:

https://download.oracle.com/docs/cd/E14571_01/web.1111/e13739/logging_services.htm