Skip Headers
Oracle® Fusion Middleware Platform Developer's Guide for Oracle Real-Time Decisions
11g Release 1 (11.1.1)

Part Number E16630-06
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

9 PHP Client

This chapter explains how to integrate an Inline Service with the Oracle RTD PHP Client, using the CrossSell Inline Service as an example.

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:

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

    For more details about supported versions, see the documents referenced in Section 6.4, "System Requirements and Certification."

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

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

  4. Start Real-Time Decision Server. For more information, see Oracle Fusion Middleware Administrator's Guide for Oracle Real-Time Decisions.

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

  6. Install either PHP Soap or NuSoap (release 0.7.3) from SourceForge.

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

Two working examples of using the PHP Client may be found at RTD_HOME\client\Client Examples\PHP Client Example:

The rest of this section consists of the following topics:

9.2.1 Deploying the PHP Client Example

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:

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

  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.

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

  4. Enter a customer ID (such as 5) and click OK.

The example is explained in more detail in the sections that follow.

9.2.2 Setting up 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.

    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/

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

9.2.3 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 the following:

  1. Copy the contents of the lib directory to <php_includes>/nusoap.

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

9.2.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"=>"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);

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

9.2.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.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>";
      }
   }

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