|Oracle® Fusion Middleware Platform Developer's Guide for Oracle Real-Time Decisions
11g Release 1 (11.1.1)
Part Number E16630-01
Oracle RTD features several robust and easy-to-use ways to integrate with enterprise operational systems:
Smart Clients: For Java and .NET environments, these components manage communication to Integration Points on Real-Time Decision Server.
PHP Client: Integrates a Web application with a deployed Inline Service through PHP client integration classes
Zero Clients: Access to Integration Points is available through Web services as a zero client approach.
This chapter, and the following chapters in Part II, outline how to use these ways to integrate with deployed Inline Services running on Oracle RTD.
See Part I, "Getting Started" for information about using Decision Studio to deploy Inline Services. For information about the integration APIs, see the Decision Studio online help.
Note:The following terms are referenced throughout the Oracle RTD documentation:
RTD_HOME: This is the directory into which the Oracle RTD client-side tools are installed.
RTD_RUNTIME_HOME: This is the application server specific directory in which the application server runs Oracle RTD.
This chapter contains the following topics:
Oracle Real-Time Decisions offers multiple means of integration. To choose the best means for your environment you should consider the platform you are working on, performance needs and the additional functionality offered by RTD Smart Client over other methods of integration.
This section contains the following topics:
The Oracle RTD Smart Client for Java is a component that allows easy, managed integration to deployed Inline Services for operational systems. If you are working in a Java environment, the Java Smart Client is the preferred means of integration. The Java Smart Client offers two important features above and beyond the other methods of integration: session key mapping (to facilitate HTTP session affinity management by an external load balancer) and default response handling. The Release 11g version of the Oracle RTD client will also support the ability of a user to inject a user defined session key and value pair into the HTTP header (using the setHttpHeader method). By default, a session key having name RTDSESSIONKEY and value of rtd session id will be added to the HTTP header. This will allow users to utilize a hardware load balancer to manage session affinity.
The factory methods of the Java Smart Client interface take parameters representing the minimal information required to establish contact either to a single server or a member of a cluster. After connecting, the component's full configuration is downloaded from the server. This way only a small set of parameters must be managed in the client application, while most of the component's configuration is centrally managed by the server's administration console.
The configuration information returned by the server to the client is shared by all the instances of the Smart Client created in the same Java virtual machine. There is a client-side class called a client-side dispatcher that manages this shared configuration and also manages session-affinity information used to dispatch requests to the correct server, based on session keys in the request.
The Java Smart Client is thread-safe, but for optimal performance a separate Java Smart Client should be created for each thread. Separate instances of the Java Smart Client share information and connections, so there is practically no penalty to having multiple instances.
Several factory methods are available to create a Java Smart Client. Most either directly or indirectly reference a properties file in the file system or on a Web server. The properties file supplies addresses for connecting to one or more servers in a single cluster as well as other properties that configure the connection to the server. Factory methods are also available to directly supply an HTTP URL and port or use a default address.
During client initialization, the detailed configuration is saved in a local file called the client configuration cache, where it can be accessed should the client restart when the server is unavailable. The configuration cache contains information such as the client's set of default responses for all integration points in all Inline Services. The client's configuration cache is updated automatically by the client whenever it changes in the server.
Part of the configuration information downloaded to a client from the server includes a set of default responses to use if the client loses contact with the server or the server fails to respond to an integration point request in a timely fashion. This maintains the Service Level Agreement (SLA) between Real-Time Decision Server and client application regardless of individual transactional availability.
These default responses are configured at the granularity of the individual integration points; each integration point relies on its own specialized default response. When any default responses are reconfigured on the server, the changes are propagated automatically to the client, bundled together with normal integration point responses.
The Java Smart Client automatically keeps track of any HTTP cookies that are returned by the Web Container of Real-Time Decision Server. The next time the same Inline Service key is used in a request, its cookies are included in the HTTP request so that the external load balancer can route the request to the server instance that is already handling that Inline Service key.
To achieve clustering using other methods of integration, the application must track the Inline Service keys itself.
For the .NET environment, a .NET Smart Client component is available. This component offers a way to call the same interfaces provided by the Java Smart Client. However, it does not offer the added functionality of maintained session affinity or default values.
JSP client integration tags are provided for developers to integrate Web applications with deployed Inline Services. These JSP tags deliver client interfaces that are equivalent to the APIs provided by the Java Smart Client.
PHP client offers a convenient way to integrate a Web application with a deployed Inline Service, through the PHP client integration classes. PHP allows you to generate interactive Web pages. The PHP classes provided offer functionality similar to the Java Smart Client.
Any client can access Real-Time Decision Server through Web services. Web service operations are defined in a WSDL file and definitions are contained in a schema file. Users can create their own standard web client using Oracle RTD's WSDL file.
Example Inline Services are included with Decision Studio. One of these is a cross selling example.
The CrossSell Inline Service simulates a simple implementation for a credit card contact center. As calls come into the center, information about the customer and the channel of the contact is captured.
Based on what we know of this customer, a cross selling offer is selected that is extended to the customer. The success or failure of that offer is tracked and sent back to the server so that the underlying decision model has the feedback that helps to refine its ability to make a better cross selling recommendation.
The CrossSell Inline Service is used to demonstrate the various means of integration in this guide.
To use the CrossSell Inline Service, you must create and populate some specific tables, as described in the section "Populating the CrossSell Example Data" in Oracle Fusion Middleware Administrator's Guide for Oracle Real-Time Decisions.
In order to get recommendation results that are not random and are based on model learning data, you should also run a Loadgen script, as described in Section 12.3.6, "Example Projects."
Several Integration Points are included in the CrossSell example. Use the following instructions to familiarize yourself with these Integration Points.
Informants execute on the server when supplied with the proper parameters. Advisors execute and also return data. In order to supply the correct parameters for calls to Integration Points, we must first identify the Object IDs.
This section contains the following topics:
Note:The Object ID of the Integration Point may or may not be the same as the label. Object IDs are used to reference Integration Points in method calls.
To identify Object IDs:
Open Decision Studio by running
Select File > Import to open the CrossSell Inline Service. Import appears.
Select Existing Project into Workspace and click Next. Browse for the CrossSell project at the location
\examples\CrossSell. Select OK and click Finish, opening the project.
Using the Inline Service Explorer, expand Integration Points. Then, expand the Informants and Advisors folders to view the Integration Points, as shown in Figure 6-1.
Figure 6-1 Informants and Advisors in the Inline Service Explorer
Use the Object ID Toggle icon to show the Object ID in the Inline Service Explorer:
When the Toggle icon is highlighted, the Object IDs show in the Inline Service Explorer; when the Toggle icon is not highlighted, the display label is shown.
To invoke an Integration Point, we must supply values for the session keys and arguments expected by the Integration Point. In the request, we must use the Object IDs defined by Decision Studio for the Integration Point's session keys and arguments. The key name must match one of the session key names defined in Decision Studio for the Integration Point.
To identify session keys and arguments.
Select the CallStart Integration Point. On the Request tab of the editor of the Integration Point, under the Session Keys list, a path to the session key is shown starting with
session; the last name in the path is the Object ID of the session key.
Note:If the session key is not displayed in object format, use the Object ID Toggle icon to change the display settings:
Only the final object ID is necessary for the session key. For example, in the case shown above, only the final string,
customerId, is used.
To identify the arguments of the Integration Point, use the detail pane of to view the Incoming Attribute column of the Request tab. The CallStart incoming argument is channel.
Integration Points that deliver responses are called Advisors. An Advisor's Response tab in Decision Studio determines the response, by identifying a parameterized Decision object that gets implicitly invoked by the Advisor. The Decision object's responsibility is to select the best Choices from its assigned Choice Group. The choice attributes that are returned are determined by the configuration set on the definition of the Choice Group.
In our example, the OfferRequest integration point is an Advisor. It returns a single cross sell offer when it is invoked.
To determine the response of an advisor:
In Decision Studio, select the OfferRequest Integration Point to view the editor.
On the Response tab, under Decision, look up the Decision that OfferRequest uses to return a response. It should be OfferDecision.
Double-click OfferDecision under Decisions to view its detail pane.
On the Selection Criteria tab, under Number of Choices to Select, find the number of responses that OfferRequest provides.
On the Selection Criteria tab, under Choice Group, find the Choice Group that OfferRequest uses. It should be Offers.
Under Choices, double-click Offers to see the choice attributes associated with this Choice Group. These attributes will be returned when a call to the Advisor is made.
Tip:In Decision Studio, use the Test view to call the Advisor and see what is returned. That way, you can see the offer returned and the attributes that come with it. To access the Test view, click the Test tab next to the Problems tab. Click the Send icon to send the request to the server:
To enable Oracle RTD's self-learning models to be updated, it is important that the success or failure of a choice be submitted back to the RTD Server. Where choice groups are tied to choice event models, in order to know what feedback the server needs, you must identify the events tied to that model, as follows:
In Decision Studio, double-click the Offer Acceptance Choice Event Model. The editor appears on the right.
On the Choice tab, under Positive Outcome Events, you can see the Events that the server is interested in for learning. These are:
These outcomes are to be reported to the server from your Inline Service to give the proper feedback to the model.
The OfferResponse Integration Point is responsible for reporting this information.
For general information about Oracle RTD web services and the security polices they use, see Appendix B, "Oracle RTD Web Services and Clients."
Refer to the system requirements and certification documentation for information about hardware and software requirements, platforms, databases, and other information. Both of these documents are available on Oracle Technology Network (OTN).
The system requirements document covers information such as hardware and software requirements, minimum disk space and memory requirements, and required system libraries, packages, or patches:
The certification document covers supported installation types, platforms, operating systems, databases, JDKs, and third-party products: