Enterprise PeopleTools 8.50 PeopleBook: PeopleSoft Integration Broker

Integrating with Oracle ESB-Based Services

This chapter discusses how to:

Consume and invoke Oracle ESB-based services.
Provide and invoke PeopleSoft services in Oracle ESB.

Understanding Integrating with Oracle ESB-Based Services

This section provides and overview of integration with Oracle ESB-based services.

Oracle ESB

Oracle Enterprise Service Bus (ESB) is a component of Oracle Fusion Middleware that separates integration concerns from applications and business logic. It moves data among disparate applications, both within and outside of an enterprise. It provides a messaging infrastructure and uses open standards to connect, transform, and route business documents.

Oracle ESB cannot provide services. Instead, it virtualizes endpoints and mediates between a client and a provider of a service.

For more information about Oracle ESB visit the Oracle Technology Network online and enter the keywords Oracle ESB.

Software Components

You must install the following software components to perform integrations using Oracle ESB:

Software Component	Description
PeopleTools	Installs the PeopleSoft application server and the web. Also installs PeopleSoft Integration Broker and the PeopleSoft SOA, including the integration gateway, publication/subscription system, Provide Services Wizard, Consume Services Wizard, and so on.
Oracle SOA Suite	Installs the Oracle services-oriented architecture, including Oracle Enterprise Manager.
Oracle JDeveloper Studio	Oracle JDeveloper Studio features the Oracle BPEL Designer and the ESB Designer used to develop BPEL and ESB projects.

Check the My Oracle Support website for the currently certified versions of Oracle SOA and Oracle JDeveloper Studio for use with PeopleTools.

Check PeopleTools and Oracle documentation for installation tips and useful information.

See Also

PeopleTools Installation Guide for your database

Oracle SOA Suite Quick Start Guide

Oracle SOA Suite Installation Guide

Oracle JDeveloper Installation Guide

Oracle BPEL Process Manager Quick Start Guide

Oracle Enterprise Service Bus Quick Start Guide

Oracle Enterprise Service Bus Installation Guide

http://www.oracle.com/technology/products/index.html

Securing Oracle ESB-Based Services

PeopleSoft Integration Broker provides a number of options that you can use to secure integrations. These include securing integrations at one or more of the following levels:

Web server.
Gateway level.
Application server level.
Node level.
User level.
Service operation level.
And so on.

It is important to fully investigate these security options and implement those that best suit your business needs.

It is also important that you investigate the security options available for the Oracle SOA Suite and Oracle JDeveloper and to implement those security options that fulfill your security requirements.

Prerequisites for Integrating with Oracle ESB–Based Services

For creating integrations with Oracle ESB services you must have PeopleSoft Integration Broker configured and running.

Note. This section discusses prerequisite configuration steps on the PeopleSoft system for integrating with Oracle ESB services. Check your Oracle documentation for setup and configuration steps that you must perform on Oracle JDeveloper, Oracle BPEL Process Manager, and Oracle ESB.

The following list is a partial checklist of items to configure:

In PeopleTools ensure that the application server and web server are installed and running.
On the Nodes-Node Definitions page, create a node to represent Oracle ESB. Set the Node Type field to External for this node.
When configuring the integrationGateway.properties file, be sure to set the ig.isc.serverURL property equal to the name of the machine running the integration engine.
When configuring the PeopleTools application server, set the PUB/SUB option to Yes. This value is required for asynchronous integrations.
On the Integration Broker Quick Configuration page, be sure to activate the application server domain by setting the Domain Status to Active.
On the Integration Broker Services Configuration page, be sure to set the service namespace, the schema namespace, and the target location.
To load files into PeopleTools from the file system, set PS_FILEDIR and PS_SERVDIR in the system variables on your machine.

Understanding PeopleSoft Integration Broker Metadata

Consuming and Invoking Oracle ESB-Based Services

This section discusses how to:

Provide Oracle ESB-based services for consuming in PeopleSoft.
Consume Oracle ESB-based services.
Invoke synchronous Oracle ESB-based services.
Invoke asynchronous Oracle ESB-based services.

Understanding Consuming and Invoking Oracle ESB-Based Services

This section provides information about consuming Oracle ESB-Based services.

Oracle ESB Projects When PeopleSoft is a Consumer

Oracle ESB cannot provide a service. It can only mediate between a client and the provider of the service.

Hence, if Peoplesoft is the consumer of an ESB service, the ESB project will contain a SOAP service (like BPEL) that will implement the business logic. Further there will be a routing service that will route the SOAP request message from Peoplesoft to the underlying webs ervice implementation.

Service Routing Types

There are two types of routing services: synchronous and asynchronous. The type of routing service determines the type of ESB project. An ESB project with a synchronous routing service defined is a synchronous ESB project; an ESB project with an asynchronous routing service defined is an asynchronous ESB project.

Oracle ESB Nested and Nonnested WSDL

PeopleSoft systems can consume WSDL documents that are nested or nonnested. This section provides additional information on each type.

Using nested WSDL documents allows you to separate the different elements of a service definition into independent documents that you can consume as needed.

Using nested WSDL helps you to write clearer definitions by enabling you to separate the definitions according to their level of abstraction. It also maximizes the ability to reuse service definitions.

The following example shows a nested WSDL document. The document is separated into three smaller documents: data type definitions, abstract definitions, and specific service bindings.

The following example shows a data type definition WSDL document:

//data type definitions WSDL//
<schema attributeFormDefault="unqualified"
     elementFormDefault="qualified"
     targetNamespace="http://xmlns.oracle.com/SynchAdd_BPEL"
     xmlns="http://www.w3.org/2001/XMLSchema">
     <element name="SynchAdd_BPELProcessRequest">
          <complexType>
               <sequence>
                    <element name="input1" type="integer"/>
                    <element name="input2" type="integer"/>
               </sequence>
          </complexType>
     </element>
</schema>

The following example show an abstract definition WSDL document:

<?xml version="1.0" encoding="UTF-8" ?>
<definitions name="NestedAsyncFFAdd_RS"
     targetNamespace="http://oracle.com/esb/namespaces/NestedAsyncFFAdd_ESB"
     xmlns="http://schemas.xmlsoap.org/wsdl/"
     xmlns:tns="http://oracle.com/esb/namespaces/NestedAsyncFFAdd_ESB"
     xmlns:inp1="http://xmlns.oracle.com/SynchAdd_BPEL">
     <types>
          <schema xmlns="http://www.w3.org/2001/XMLSchema">
<import namespace="http://xmlns.oracle.com/SynchAdd_BPEL"
schemaLocation="SyncAdd_Req.xsd" />
</schema>
</types>
<message name="SynchAdd_BPELProcessRequest_request">
<part name="SynchAdd_BPELProcessRequest"
element="inp1:SynchAdd_BPELProcessRequest" />
</message>
<portType name="NestedESBAsyncFFAdd_ppt">
<operation name="NestedESBAsyncFFAdd">
<input message="tns:SynchAdd_BPELProcessRequest_request" />
</operation>
</portType>
</definitions>

The following example shows a service bindings WSDL document:

<?xml version="1.0" encoding="UTF-8" ?>
<definitions targetNamespace="http://oracle.com/esb/namespaces/NestedAsyncFFAdd_⇒
ESB/concrete"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:tns="http://oracle.com/esb/namespaces/NestedAsyncFFAdd_ESB/concrete"
xmlns:ws="http://www.example.com/webservice" xmlns:http="http:
//schemas.xmlsoap.org/wsdl/http/"
xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"
xmlns:esb="http://www.oracle.com/esb/" xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/" xmlns:wsdl="http:
//schemas.xmlsoap.org/wsdl/"
xmlns:import="http://oracle.com/esb/namespaces/NestedAsyncFFAdd_ESB">
<import namespace="http://oracle.com/esb/namespaces/NestedAsyncFFAdd_ESB"
location="http://bng-psft-
0100:8888/esb/slide/ESB_Projects/PS_Consumer_NestedAsyncFFAdd_ESB/NestedAsyncFFAdd_
ESB_NestedAsyncFFAdd_RS.wsdl" />
<binding name="__soap_NestedAsyncFFAdd_RS_NestedESBAsyncFFAdd_ppt"
type="import:NestedESBAsyncFFAdd_ppt">
<soap:binding xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" style="document"
transport="http://schemas.xmlsoap.org/soap/http" />
<operation name="NestedESBAsyncFFAdd">
<soap:operation xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" style="document"
soapAction="NestedESBAsyncFFAdd" />
<input>
<soap:body xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" use="literal" />
</input>
</operation>
</binding>
<binding name="__esb_NestedAsyncFFAdd_RS_NestedESBAsyncFFAdd_ppt"
type="import:NestedESBAsyncFFAdd_ppt">
<esb:binding />
<operation name="NestedESBAsyncFFAdd">
<esb:operation eventname="
NestedAsyncFFAdd_ESB.NestedAsyncFFAdd_RS.NestedESBAsyncFFAdd" />
<input />
</operation>
</binding>
<service name="ESB_NestedAsyncFFAdd_RS_Service">
<port name="__soap_NestedAsyncFFAdd_RS_NestedESBAsyncFFAdd_ppt"
binding="tns:__soap_NestedAsyncFFAdd_RS_NestedESBAsyncFFAdd_ppt">
<soap:address xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" location="http:⇒
//bng-psft-
0100:8888/event/NestedAsyncFFAdd_ESB/NestedAsyncFFAdd_RS" />
</port>
<port name="__esb_NestedAsyncFFAdd_RS_NestedESBAsyncFFAdd_ppt"
binding="tns:__esb_NestedAsyncFFAdd_RS_NestedESBAsyncFFAdd_ppt"/>
</service>
<plt:partnerLinkType name="NestedESBAsyncFFAdd_pptLT">
<plt:role name="NestedESBAsyncFFAdd_pptProvider">
<plt:portType name="tns:NestedESBAsyncFFAdd_ppt" />
</plt:role>
</plt:partnerLinkType>

Oracle ESB WSDL Bindings

A WSDL document binding provides the protocol and data format specification for a particular port type.

Oracle ESB WSDL documents can have SOAP bindings or Oracle ESB native bindings.

Note. Oracle ESB WSDL documents to be consumed by PeopleSoft system must be of the SOAP type. SOAP binding adhere to the SOAP protocol. Choosing the Oracle ESB native binding type may result in unpredictable behavior in PeopleSoft systems.

PeopleSoft Integration Broker Consume Services Wizard

To consume Oracle ESB-based services use the PeopleSoft Integration Broker Consume Services Wizard. The wizard enables you to consume WSDL provided by integration partners. In turn, the wizard creates PeopleSoft service, service operation, message, and routing definitions for the WSDL, thereby enabling you to manage and invoke the service in PeopleSoft.

See Understanding the Consume Web Service Wizard.

Providing Oracle ESB–Based Services for Consuming in PeopleSoft

This section lists the general steps for providing Oracle ESB–based services for consuming in PeopleSoft systems. All steps are performed in Oracle ESB except where otherwise noted:

Create the ESB project.

Remember that the type of routing service (synchronous or asynchronous) you associate to the project determines the project type (synchronous or asynchronous).
Register the project with the Oracle ESB server.

Use the Oracle ESB Console to verify that you successfully registered the project.
On the machine on which Oracle ESB is deployed, verify that the virtual host and port values are set.

By default the virtual host is set to localhost. You must set the virtual host to the IP address or host name.
On the Definitions tab, note the WSDL URL of the routing service.

Note. Write down the WSDL URL of the routing service. You must enter this URL in the PeopleSoft system to consume the service.

Consuming Oracle ESB-Based Services

To consume WSDL from an ESB-based service into the PeopleSoft system use the Consume Web Service component in the PeopleSoft Pure Internet Architecture.

As you use the Consume Services Wizard keep the following points in mind:

The source of the WSDL is a WSDL URL. Enter the URL of the routing service that you noted on the Definitions tab in Oracle ESB.
When prompted to select service ports select the service(s) who's name start with “SOAP.” This ensures that the PeopleSoft system uses the correct binding type to create the routing metadata.
Make a note of the service operations that you consume. You need these names when you create PeopleCode to create the request message and invoke the service.
When prompted to select a receiving node select the Use Exiting Node option. Next, enter or search for the external node that you created to represent the ESB system.
When consuming asynchronous services you can use the default queue option or select a different queue.

See Also

Consuming Services

Invoking Synchronous Oracle ESB-Based Services

This section discusses how to:

Manage routing definitions for invoking synchronous Oracle ESB-based services.
Set message and error logging for invoking synchronous Oracle ESB-based services.
Invoke a synchronous Oracle ESB-based service.

Prerequisites for Invoking Synchronous Oracle ESB-Based Services

Before you can invoke a synchronous Oracle ESB-based service, you must first consume it. Consuming Oracle ESB-based services is described elsewhere in this section.

See Consuming Oracle ESB-Based Services.

Managing Routing Definitions for Invoking Synchronous Oracle ESB-Based Services

The PeopleSoft Integration Broker Consume Services Wizard creates an outbound routing definition for the consumed service.

Before you invoke a synchronous Oracle ESB-based service in the PeopleSoft system, ensure the following for the routing definition:

On the Routings-Connector Properties page (PeopleTools, Integration Broker, Integration Setup, Routings. Click the Connector Properties tab) and perform the following tasks:

Ensure that the Connector ID field is set to HTTPTARGET.
Ensure that the value in the Primary URL field is set to the endpoint URL.
Set any other HTTP target connector properties as desired.

Setting Message and Error Logging for Invoking Synchronous Oracle ESB-Based Services

To capture the maximum amount to message and error logging and information when you invoke the service, set the following options:

On the Routings- Routing Definitions page (PeopleTools, Integration Broker, Integration Setup, Routings), set the value in the Log Detail field to Header and Detail.
In the integrationGateway.properties file, set the ig.log.level property equal to 5.

A setting of 5 is the default value.

Invoking a Synchronous Oracle ESB-Based Service

The following sample PeopleCode demonstrates one way to invoke the synchronous ESB-based service:

Local string &payload, &responseStr;
Local Message &msg, &reply;
Local XmlDoc &xml;

/* --- set input request message--- */
&payload = "<?xml version='1.0' encoding='UTF-
8'?><SynchAdd_BPELProcessRequest
xmlns='http://xmlns.oracle.com/SynchAdd_BPEL'><input1>1234</input1><input2>12
34</input2></SynchAdd_BPELProcessRequest>";
MessageBox(0, "Request Message", 0, 0, &payload);

&xml = CreateXmlDoc(&payload);
&msg = CreateMessage(Operation.ESBSYNCADD, %IntBroker_Request);
&msg.SetXmlDoc(&xml);

&reply = %IntBroker.SyncRequest(&msg);

   If All(&reply) Then
     &responseStr = &reply.GenXMLString();
     MessageBox(0, "Request Message", 0, 0, (&responseStr));
   Else
     WinMessage("Error. No reply (or NULL) from LaunchSyncBPELProcess");
End-If;

On execution the system displays the request message that the system sends to Oracle ESB.

If the invocation is successful, the system displays another box that shows the response from Oracle ESB as shown in the following example:

Use the PeopleSoft Integration Broker message logs to view the flow of the messages. You can also use the Integration Broker Service Operations Monitor to view information about the outbound transaction.

Use the Oracle ESB Console to check for the ESB instance and for the successful invocation of the ESB service.

See Managing Integration Gateway Message and Error Logging, Monitoring Synchronous Service Operations.

Invoking Asynchronous Oracle ESB-Based Services

This section discusses how to:

Create acknowledgements for invoking asynchronous Oracle ESB-based services.
Manage routing definitions for invoking asynchronous Oracle ESB-based services.
Set message and error logging for invoking asynchronous Oracle ESB-based services.
Invoke an asynchronous Oracle ESB-based service.

Understanding Invoking Asynchronous Oracle ESB-Based Services

An asynchronous service is also referred to as a fire-and-forget service.

Prerequisites for Invoking Asynchronous Oracle ESB-Based Services

Before you can invoke an asynchronous Oracle ESB-based service, you must first consume it. Consuming Oracle ESB-based services is described elsewhere in this section.

See Consuming Oracle ESB-Based Services.

Creating Acknowledgments for Invoking Asynchronous Oracle ESB-Based Services

To handle acknowledgement data for an asynchronous service operation, create an OnReceive handler that uses the OnAckReceive method that is implemented as an application class. After doing so, you must register the application class with the PeopleSoft service operation.

The following code example shows sample code to create the handler:

import PS_PT:Integration:IReceiver;

class AsynchFF_AckReceive implements PS_PT:Integration:IReceiver
   method AsynchFF_AckReceive();
   method OnAckReceive(&MSG As Message) Returns integer;
end-class;

/* constructor */
method AsynchFF_AckReceive
end-method;

method OnAckReceive
   /+ &MSG as Message +/
   /+ Returns Integer +/
   /+ Extends/implements PS_PT:Integration:IReceiver.OnAckReceive +/
   /* Variable Declaration */

If &MSG.IsStructure Then

   /* if message is rowset-based */
   Local string &str = &MSG.GenXMLString();

Else
   /* if message is nonrowset-based */
   Local XmlDoc &xmldoc = &MSG.GetXmlDoc();
   Local string &str1 = &xmldoc.GenXmlString();
   Local File &MYFILE;

   &MYFILE = GetFile("C:\Temp\ESB\PS_Consume\ESBasynchffack.txt", "W",
%FilePath_Absolute);
   If &MYFILE.IsOpen Then
      &MYFILE.WriteString(&str1);
      &MYFILE.WriteLine("");
      &MYFILE.WriteString(String(%Operation_Done));
      &MYFILE.Close();
     End-If;
   End-If;

   Return (%Operation__Done);
end-method;

To create an acknowledgement for consumed asynchronous Oracle ESB-based services:

Create an OnReceive handler that uses the OnAckReceive method that is implemented as an application class.

See Implementing Handlers Using Application Classes.
Open the service operation definitions for the consumed service operation.
Click the Handler tab.

The Service Operations-Handlers page appears.

Add a handler with the following characteristics:

Name	Enter any name. For example: AckReceive.
Type	From the drop-down list select OnReceive.
Implementation	From the drop-down list select Application Class.
Status	From the status drop-down list select Active.

Click the Details link.

The Handler Details page appears.

At a minimum enter the following details about the application class:

Package Name	Enter the package name that contains the class that you want to specify.
Path	Enter :(a colon).
Class ID	Enter the name of the application class that contains the method that you want to specify.
Method	From the drop-down list select OnAckReceive.

Managing Routing Definitions for Invoking Asynchronous Oracle ESB-Based Services

The PeopleSoft Integration Broker Consume Services Wizard creates an outbound routing definition for the consumed service.

Before proceeding to invoke the service, ensure the following on the routing definition:

On the Routings-Routing Definitions page (PeopleTools, Integration Broker, Integration Setup, Routings), in the OnReceive Handler field, enter or select OnAckReceive.

This is the acknowledgement.
On the Routings-Connector Properties page (PeopleTools, Integration Broker, Integration Setup, Routings. Click the Connector Properties tab).
- Ensure that the Connector ID field is set to HTTPTARGET.
- Ensure that the value in the Primary URL field is set to the endpoint URL.
- Set any other HTTP target connector properties as desired.

Setting Message and Error Logging for Invoking Asynchronous Oracle ESB-Based Services

To capture the maximum amount of message and error logging and information when you invoke the service, in the integrationGateway.properties file, set the ig.log.level property equal to 5.

A setting of 5 is the default value.

Invoking an Asynchronous Oracle ESB-Based Service

The following sample PeopleCode demonstrates one way to invoke the asynchronous Oracle ESB-based service:

Local string &payload, &responseStr;
Local Message &msg, &reply;
Local XmlDoc &xml;

/* --- setting the input request message --- */

&payload = "<?xml version='1.0' encoding='UTF-8'?><SynchAdd_BPELProcessRequest
xmlns='http://xmlns.oracle.com/SynchAdd_BPEL'><input1>6789</input1><input2>6789<⇒
/inpu
t2></SynchAdd_BPELProcessRequest>";
MessageBox(0, "Request Message", 0, 0, &payload);

&xml = CreateXmlDoc(&payload);

&msg = CreateMessage(Operation.ESBASYNCFFADD, %IntBroker_Request);

&msg.SetXmlDoc(&xml);

%IntBroker.Publish(&msg);
&responseStr = &msg.TransactionId;

MessageBox(0, "Message Transaction ID-Response from LaunchAsyncBPELProcess", 0, 0,
&responseStr);

MessageBox(0, "Acknowledgement from ESB", 0, 0, "For Ack Msg from ESB , go look at⇒
 the
file C:\temp\ESB\PS_Consume\ESBasynchffack.txt");

When you execute the PeopleCode the PeopleSoft system the following information in consecutive message boxes:

The request message that it sends to Oracle ESB.
The transaction ID for the asynchronous request.
The file location of the acknowledgement it received from Oracle ESB

displays

You can use the PeopleSoft Integration Broker message logs to view the flow of the messages. You can also use the Integration Broker Service Operations Monitor to view information about the outbound transaction.

You can also use the Oracle ESB Console to check for the message instance and for the successful invocation of the ESB service.

See Managing Integration Gateway Message and Error Logging, Monitoring Asynchronous Service Operations.

Providing and Invoking PeopleSoft Services in Oracle ESB

This section discusses how to:

Provide PeopleSoft services to Oracle ESB
Invoke PeopleSoft services in Oracle ESB

Understanding Providing and Invoking PeopleSoft Services in Oracle ESB

This section provides an overview of providing and invoking PeopleSoft services in Oracle ESB.

Oracle ESB Projects When PeopleSoft is a Provider

To invoke a PeopleSoft service in Oracle ESB, you must create a project in Oracle ESB.

See Oracle Enterprise Service Bus Quick Start Guide

PeopleSoft Integration Broker Provide Services Wizard

To provide PeopleSoft services to Oracle ESB you use the PeopleSoft Integration Broker Provide Services Wizard. The wizard enables you to generate WSDL documents based on services you create in PeopleSoft Integration Broker. You then provide the generated WSDL to Oracle ESB.

Prerequisites for Providing and Invoking PeopleSoft Services in Oracle ESB

You must create the PeopleSoft services you wish to provide, prior to using generating WSDL and providing the WSDL to Oracle ESB.

Other prerequisites may exist in Oracle JDeveloper or Oracle ESB. Refer to the Oracle documentation for more information.

Providing PeopleSoft Services

Use the PeopleSoft Integration Broker Provide Web Service Wizard to generate a WSDL document for the service you wish to provide to Oracle ESB.

The wizard provides you the option to publish the WSDL to a UDDI repository that you define, or to the WSDL repository in PeopleSoft Integration Broker. You can choose either publishing option.

The last page is the WSDL Generation Log which provides the name of the services and URL for each WSDL document generated. You will use this information when you invoke the services in Oracle ESB.

See Also

Providing Services

Invoking PeopleSoft Services in Oracle ESB

This section describes how to invoke synchronous and asynchronous services in Oracle ESB.

Creating an ESB Project to Invoke PeopleSoft Services

After you use the PeopleSoft Integration Broker Provide Web Service wizard to generate WSDL, the next step is to invoke the services in Oracle ESB, To do so, you must create an ESB project type in Oracle JDeveloper.

See Oracle Enterprise Service Bus Quick Start Guide

The following are general steps to follow to configure the Oracle ESB project after you initially create it. Refer to the Oracle documentation for detailed information and instructions:

Modify the project so that the SOAP service points to the PeopleSoft WSDL URL generated when you provided the service in PeopleSoft,
Use the Make option to build the project.
Use the Register with ESB option to register the project with Oracle ESB.

This command allows you to register the services created using Oracle JDeveloper to the Enterprise Service Bus.

A message appears that indicates you successfully registered the services with the Oracle ESB server.

To view, monitor or make runtime adjustments to the ESB configuration, use the Oracle ESB Console.

When you have successfully registered the services on the Oracle ESB Server, you can view them in the Services Panel in Oracle JDeveloper. Click the ESB system to view the ESB system flow in the Configuration Area on the right side.

Invoking a Service in Oracle

As of the printing date of this PeopleBook, Oracle ESB does not feature a test page. To test and invoke ESB web services, use the Oracle SOA Suite’s Oracle Enterprise Manager.

See Oracle Enterprise Manager documentation.