A convenient way to integrate a Web application with a deployed Inline Service is to use 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 discussed in a previous chapter.
This chapter contains the following topics:
You must perform the following tasks first before you can work with the PHP Client example:
Install a Java Development Kit (JDK), with the JAVA_HOME environment variable set to its location. To obtain a JDK, go to the site:
http://developers.sun.com/downloads
For more details about supported versions, see the documents referenced in Section 6.4, "System Requirements and Certification."
Install the Oracle RTD files and deploy Oracle RTD to an application server. See Oracle Fusion Middleware Installation Guide for Oracle Business Intelligence for full information.
The PHP Client example works with the sample CrossSell Inline Service. Because of this, you must first populate the Oracle RTD Database with the CrossSell example data, then deploy the CrossSell Inline Service using Decision Studio. For details, see the section "Populating the CrossSell Example Data" in Oracle Fusion Middleware Administrator's Guide for Oracle Real-Time Decisions and Part III, "Decision Studio Reference" for information about deploying Inline Services.
Start Real-Time Decision Server. For more information, see Oracle Fusion Middleware Administrator's Guide for Oracle Real-Time Decisions.
Install and configure an environment suitable for evaluating PHP 5.2 scripts, such as Apache with mod_php. Please consult the documents referenced in Section 6.4, "System Requirements and Certification" for supported versions and operating systems.
Install either PHP Soap or NuSoap (release 0.7.3) from SourceForge.
In general, integration using the Oracle RTD PHP Client includes the following steps:
Prepare an Oracle RTD PHP Client .ini file.
Prepare Client objects.
Create a request that identifies the following:
The Integration Point to connect to
The parameters to identify the session
Any other information the Integration Point needs to determine an outcome
Use Oracle RTD PHP method syntax to create requests for Informants.
Use Oracle RTD PHP method syntax to parse responses from Advisors.
Close the connection.
Two working examples of using the PHP Client may be found at RTD_HOME\client\Client Examples\PHP Client Example:
example_nusoap.php demonstrates the use of the Oracle RTD PHP Client with NuSoap
example.php implements the same functionality but uses PHP Soap
The rest of this section consists of the following topics:
For this example, the CrossSell Inline Service is exercised by a simple PHP page to demonstrate how to use the PHP Client.You need to deploy the PHP Client example to your application server, as described in the following section.
To deploy the PHP Client example to Apache:
Place the Oracle RTD PHP Client library:
RTD_HOME\client\Client Examples\PHP Client Example\rtd
either into a location on your PHP include path or to the web site pages folder, such as htdocs for the Apache HTTP server.
This rtd folder should contain the following files:
DecisionService.wsdl
rtd.client.base.php
rtd.client.nusoap.php
rtd.client.phpsoap.php
rtd_client_conf.ini
rtd_client_nusoap_conf.ini
Note:
As part of your setup, you must ensure that the.ini file that you use is appropriate for your environment. For more information, see Section 9.2.2, "Setting up the Oracle RTD PHP Client .ini File."Place the appropriate Oracle RTD PHP Client example - example.php for PHP Soap or example_nusoap.php for NuSoap - into a path from which your Apache server is configured to serve PHP scripts, for example, /home/www/example.php.
To access the application, open a Web browser and go to:
http://apache_host:port/example.php (for PHP)
or
http://apache_host:port/example_nusoap.php (for NuSoap)
Enter a customer ID (such as 5) and click OK.
The example is explained in more detail in the sections that follow.
The .ini files provided by Oracle RTD are the following:
rtd_client_conf.ini (for PHP Soap)
rtd_client_nusoap_conf.ini (for NuSoap)
The PHP client properties in these files are as follows:
wsdl - wsdl file location. Use with PHP Soap.
Note:
If the PHP Client library is in a location on your PHP include path, you can specify the wsdl location in either of the following ways:You can provide a full path name, such as c:\php\includes\rtd\DecisionService.wsdl
If you have copied the DecisionService.wsdl file into the web site pages folder, such as htdocs for the Apache HTTP server, then you can provide a relative path name for the wsdl property. For example, rtd\DecisionService.wsdl.
clientClass - Client class name
appsCacheClass - Cache class name
appsCacheFile - temp file for default response
clientTimeout - Oracle RTD integration point invoke timeout in seconds. This is optional.
endpointUrl - url for the decision service
username - user name to connect to the server
password - password to connect to the server
Example of rtd_client_conf.ini
The following is an example of rtd_client_conf.ini:
# RTD integration service wsdl file path wsdl=rtd/DecisionService.wsdl clientClass=Oracle_Rtd_Client_Impl appsCacheClass=Oracle_Rtd_Client_File_Cache # temp file for default response appsCacheFile=c:/temp/rtd_default.dat # RTD integration point invoke timeout in seconds clientTimeout=2 # RTD service url endpointUrl=http://localhost:8080/
Example of rtd_client_nusoap_conf.ini
The following is an example of rtd_client_nusoap_conf.ini:
# client class name clientClass=Oracle_Rtd_Client_Nu # cache class name appsCacheClass=Oracle_Rtd_Client_File_Cache # temp file for default response appsCacheFile=c:/temp/rtd_default_nusoap.dat # RTD integration point invoke timeout in seconds clientTimeout=2 # RTD service url endpointUrl=http://localhost:8080/
Oracle RTD provides Client example initialization files as a basis for your configuration. You must ensure that the settings in the files match your system. If necessary, edit the files so that they are correct for your configuration setup.
For example, if your Real-Time Decision Server server is not running on localhost or its listening port is not 8080, you must edit the appropriate .ini file before deploying the Oracle PHP Client example, as follows:
In RTD_HOME\client\Client Examples\PHP Client Example\rtd, open the appropriate file, rtd_client_conf.ini or rtd_client_nusoap_conf.ini,with a text editor.
Search for the entry:
endPointUrl = http://localhost:8080
Change the URL localhost:8080 to match the host and port of the Real-Time Decision Server that you are using.
Save the file.
How the Client Properties are Used
When a client application creates an Oracle RTD PHP Client, it passes a set of properties to an Oracle RTD PHP Client factory that represents the component's endpoint configuration.
If no argument is given, the Client factory derives its settings by applying parse_ini_file to rtd_client_conf.ini.
The factory method uses the settings to connect to the server. When the Oracle RTD PHP Client has connected to the server, it downloads a more complete set of configuration information, such as the set of default responses that the client should use if it ever needs to run when the server is unavailable.
The detailed client configuration is saved in a local file, the Oracle RTD PHP Client configuration cache, and is updated automatically whenever the server's configuration changes.
The Oracle RTD client library assumes that nusoap.php is located in a directory structure of the form <php_includes>/nusoap/nusoap.php, where <php_includes> is among the PHP installation's include directories.
However, nusoap files download into the directories lib and sample.
Users must do the following:
Copy the contents of the lib directory to <php_includes>/nusoap.
In rtd.client.nusoap.php, edit the following entry:
include_once "nusoap/nusoap.php"
to reflect the actual nusoap library location.
The following include is used to support Oracle RTD integration with NuSoap:
include_once "rtd/rtd.client.nusoap.php"
To create the Oracle RTD PHP Client, open the source file for the Example PHP script appropriate for your environment (example.php for users of PHP Soap and example_nusoap.php for NuSoap users).
The following include is used to support Oracle RTD integration with NuSoap:
include_once "rtd/rtd.client.nusoap.php";
The following include is used to support Oracle RTD integration with PHP Soap:
include_once "rtd/rtd.client.phpsoap.php";
example.php and example_nusoap.php demonstrate different ways of obtaining an instance of the Oracle RTD PHP Client.
A client may be obtained with settings given explicitly inline, as is shown by example.php:
$client = Oracle_Rtd_Client_Factory::createClient(array(
"wsdl"=>"C:/OracleBI/RTD/client/Client Examples/PHP Client Example/rtd/DecisionService.wsdl",
"clientClass"=>"Oracle_Rtd_Client_Impl",
"appsCacheClass"=>"Oracle_Rtd_Client_File_Cache",
"appsCacheFile"=>"C:/temp/rtd_default.dat",
"clientTimeout"=>2,
"username"=>"your name",
"password"=>"your password",
"endpointUrl"=>"http://localhost:9704/"
));
In example_nusoap.php, the settings are parsed from a .ini file that has been placed in the same directory as the example PHP script, and may be found in RTD_HOME\client\Client Examples\PHP Client Example\rtd\rtd_client_nusoap_conf.ini:
$config = parse_ini_file("rtd_client_nusoap_conf.ini");
$client = Oracle_Rtd_Client_Factory::createClient($config);
This line of code creates a Request object:
$request = $client->createRequest();
A request must be configured with the destination Inline Service:
$request->setServiceName(“CrossSell”);
The selection of an Inline Service may be further specialized with a Deployment State. If omitted then the Inline Service deployed in the highest State receives the Request (Production is higher than QA, which is higher than Development):
$request->setDeploymentState(“Development”);
The details of a Request are specific to each Inline Service. In this example, the CallStart Informant requires a Session Key named customerId and an additional parameter named channel:
$request->setIntegrationPointName(“CallStart”); $request->setSessionKey(“customerId”, 3); $request->setArg(“channel”, “Call”);
After populating the request, the client application calls the invoke method of the Client, sending the Request to the RTD Server:
$client->invoke($request);
When an Advisor is invoked, a number of response items, also known as Choices, will be returned. Your application must be prepared to handle these items. See Section 6.2.3, "Determining the Response of an Advisor" for more information.
In the client PHP script, the selected Choices are accessible through the Response interface returned by the Client's invoke method. This object provides access to an array of ResponseItem objects, each one corresponding to a Choice object selected by the Advisor's Decision.
The Choice's name may be accessed with the getId() method, and the Choice's attributes are available through getAttributes():
$request->setIntegrationPointName(“OfferRequest”); $response = $client->invoke($request);
In the PHP example scripts, the response items are each printed to the web page in the order given by the RTD server:
$items = $response->getResponseItems();
foreach ($items as $item) {
echo "<h1>" . $item->getId() . "</h1>";
foreach ($item->getAttributes() as $key => $value) {
echo $key . ': '.$value."<br>";
}
}
Many Inline Services are designed to be self learning. In the CrossSell Inline Service, the OfferResponse Informant reports interest in a cross sell offer back to a Choice Event Model. For simplicity, this example registers an "Interested" Choice Event for the highest ranked Choice among the response items.
if ($response->size() > 0) {
$request->setIntegrationPointName("OfferResponse");
$request->setArg("choiceName", $response->get(0)->getId());
$request->setArg("choiceOutcome", "Interested");
$client->invoke($request);
}
For more information about Choice Event models and Choices, see Section 6.2.4, "Identifying Event Responses to Oracle RTD."
Finally, the session is closed by invoking the CallResolution Informant, which in the CrossSell example has been designed to terminate the session, freeing resources and triggering tasks to run that wait for the end of a session.
$request->setIntegrationPointName("CallResolution");
$client->invoke($request);