11 Using the Oracle RTD PHP Client

The Oracle RTD PHP Client is a new feature introduced in Oracle RTD Version 3.0.0.1.

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 Oracle Real-Time Decisions Platform Developer's Guide.

This chapter contains the following topics:

• Section 11.1, "Before You Begin"

• Section 11.2, "Integrating with an Inline Service Using the Oracle RTD PHP Client"

• Section 11.3, "Deploying the PHP Client Examples"

11.1 Before You Begin

You must perform the following tasks first before you can work with the PHP Client example:

1. 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

2. Install the Oracle RTD files and deploy Oracle RTD to an application server. See Oracle Real-Time Decisions Installation and Administration Guide for full information.

3. 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.

   See Oracle Real-Time Decisions Installation and Administration Guide for information about populating the Oracle RTD Database with the CrossSell example data. See Part III, "Decision Studio Reference" in Oracle Real-Time Decisions Platform Developer's Guide for information about deploying Inline Services.

4. Start Real-Time Decision Server. For more information, see Oracle Real-Time Decisions Installation and Administration Guide.

5. Install and configure an environment suitable for evaluating PHP 5.2 scripts, such as Apache with mod_php.

6. Install either the PHP Soap library from the PHP Installer (version 5.2 or later), or the NuSoap library (release 0.7.3 or later) from SourceForge.

11.2 Integrating with an Inline Service Using the Oracle RTD PHP Client

In general, integration using the Oracle RTD PHP Client includes the following steps:

1. Prepare an Oracle RTD PHP Client .ini file.

2. Prepare Client objects.

3. 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

4. Use Oracle RTD PHP method syntax to create requests for Informants.

5. Use Oracle RTD PHP method syntax to parse responses from Advisors.

6. Close the connection.

   Note:

   The Oracle RTD PHP Client API reference may be found in RTD_HOME\client\Client Examples\PHP Client Example\docs.

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

11.3 Deploying the PHP Client Examples

This section consists of the following topics:

• Section 11.3.1, "Installing PHP Client Library and Example Files"

• Section 11.3.2, "Editing the NuSoap Path Library Location"

• Section 11.3.3, "Preparing the Oracle RTD PHP Client .ini File"

• Section 11.3.4, "Creating the Oracle RTD PHP Client"

• Section 11.3.5, "Creating the Request"

• Section 11.3.6, "Examining the Response"

• Section 11.3.7, "Closing the Loop"

• Section 11.3.8, "Testing the PHP Client Example"

11.3.1 Installing PHP Client Library and Example Files

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 Web server, as described in the following section.

To deploy the PHP Client example to Apache:

1. Place the Oracle RTD PHP Client library:

   • RTD_HOME\client\Client Examples\PHP Client Example\rtd

   into a location on your PHP include path.

   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

2. 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.

11.3.2 Editing the NuSoap Path Library Location

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 one of 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.

11.3.3 Preparing the Oracle RTD PHP Client .ini File

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.

• 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

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/

Editing the .ini files

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:

1. 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.

2. Search for the entry:

   endPointUrl = http://localhost:8080
   

3. Change the URL localhost:8080 to match the host and port of the Real-Time Decision Server that you are using.

4. 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 request timeout duration. It will also maintain locally 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.

11.3.4 Creating the Oracle RTD PHP Client

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"=>"g:/php/includes/rtd/DecisionService.wsdl",
      "clientClass"=>"Oracle_Rtd_Client_Impl",
      "appsCacheClass"=>"Oracle_Rtd_Client_File_Cache",
      "appsCacheFile"=>"c:/temp/rtd_default.dat",
      "clientTimeout"=>2,
      "endpointUrl"=>"http://192.168.0.196:8081/"
   ));

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);

11.3.5 Creating the Request

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);

11.3.6 Examining the Response

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.2, "Determining the Response of an Advisor" in Oracle Real-Time Decisions Platform Developer's Guide 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>";
      }
   }

For an example of the Web page output, see Section 11.3.8, "Testing the PHP Client Example."

11.3.7 Closing the Loop

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.3, "Knowing How to Respond to the Server" in Oracle Real-Time Decisions Platform Developer's Guide.

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);

11.3.8 Testing the PHP Client Example

To access the application, open a web browser and enter one of the following URLs (or as specified in Section 11.3.1, "Installing PHP Client Library and Example Files," step 2):

http://apache_host:port/example.php (for PHP)

or

http://apache_host:port/example_nusoap.php (for NuSoap)

This displays the choice response from the Advisor call in the Inline Service, together with the choice attributes, such as shown in the following sample output: