Consuming and Invoking Oracle Mediator/ESB-Based Services

This section discusses how to:

  • Provide Oracle Mediator/ESB-based services for consuming in PeopleSoft.

  • Consume Oracle Mediator/ESB-based services.

  • Invoke synchronous Oracle Mediator/ESB-based services.

  • Invoke asynchronous Oracle Mediator/ESB-based services.

  • Invoke asynchronous request/request Oracle Mediator services.

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

Oracle Mediator/ESB Projects When PeopleSoft is a Consumer

Oracle Mediator/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 a Mediator or ESB service, the Mediator/ESB project will contain a SOAP service 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 web service implementation.

Service Routing Types

There are three types of routing services: synchronous, asynchronous, and asynchronous request/response.

Note: Oracle Mediator provides the ability to consume asynchronous request/response services. You cannot consume these types of services uses Oracle ESB.

The type of routing service determines the type of Mediator or ESB project. A Mediator or ESB project with a synchronous routing service defined is a synchronous Mediator/ESB project; and a Mediator/ESB project with an asynchronous routing service defined is an asynchronous Mediator/ESB project. Mediator projects with an asynchronous request/response service defined is an asynchronous request/response service.

Oracle ESB Nested and Non-Nested WSDL

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

Note: PeopleSoft supports integrations with Oracle ESB nested WSDL documents. This feature is not available with Oracle Mediator.

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_ESB"
     xmlns="http://www.w3.org/2001/XMLSchema">
     <element name="SynchAdd_ESBProcessRequest">
          <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_ESB">
     <types>
          <schema xmlns="http://www.w3.org/2001/XMLSchema">
<import namespace="http://xmlns.oracle.com/SynchAdd_ESB"
schemaLocation="SyncAdd_Req.xsd" />
</schema>
</types>
<message name="SynchAdd_ESBProcessRequest_request">
<part name="SynchAdd_ESBProcessRequest"
element="inp1:SynchAdd_ESBProcessRequest" />
</message>
<portType name="NestedESBAsyncFFAdd_ppt">
<operation name="NestedESBAsyncFFAdd">
<input message="tns:SynchAdd_ESBProcessRequest_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 Mediator/ESB WSDL Bindings

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

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

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

Asynchronous Request/Response Callback Operations

The WSDL created by Oracle Mediator for asynchronous request/response integrations does not contain a service definition for the callback operation. The PeopleSoft system does not recognize the callback until the service definition is defined.

As a result, save the WSDL document to the file system and add the following section to the WSDL document. Then consume the WSDL document in the Consume Web Services Wizard, selecting the File option when specifying the WSDL source.

<wsdl:service name="asyncrrcalcesbcallback_client_ep">
   <wsdl:port name="AsyncRRCalcESBCallback_pt" binding="client:
    AsyncRRCalcESBCallbackBinding">
      <soap:address xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
       location="http://Client.EndPoint.Set.By.Caller"/>
   </wsdl:port>
</wsdl:service>

PeopleSoft Integration Broker Consume Services Wizard

To consume Oracle Mediator/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.

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

  1. Create the Mediator/ESB project.

    Remember that the type of routing service (synchronous, asynchronous, or asynchronous request/response) you associate to the project determines the project type (synchronous, asynchronous, asynchronous request/response).

  2. Register the project with the Oracle Mediator/ESB server.

    Use the Oracle Mediator/ESB Console to verify that you successfully registered the project.

  3. On the machine on which Oracle Mediator/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.

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

To consume WSDL from a Mediator/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 Mediator/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 Mediator/ESB system.

  • When consuming asynchronous services you can use the default queue option or select a different queue.

This section discusses how to:

  • Manage routing definitions for invoking synchronous Oracle Mediator/ESB-based services.

  • Set message and error logging for invoking synchronous Oracle Mediator/ESB-based services.

  • Invoke a synchronous Oracle Mediator/ESB-based service.

Prerequisites for Invoking Synchronous Oracle Mediator/ESB-Based Services

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

See Consuming Oracle Mediator/ESB-Based Services.

Managing Routing Definitions for Invoking Synchronous Oracle Mediator/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 Mediator/ESB-based service in the PeopleSoft system, perform these tasks:

  1. Access the Routings – Connector Properties page (PeopleTools > Integration Broker > Integration Setup > Routings. and click the Connector Properties tab).

  2. Ensure that the Connector ID field is set to HTTPTARGET.

  3. Ensure that the value in the Primary URL field is set to the endpoint URL.

  4. Set any other HTTP target connector properties as desired.

Setting Message and Error Logging for Invoking Synchronous Oracle Mediator/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.

Invoking a Synchronous Oracle Mediator/ESB-Based Service

The following sample PeopleCode demonstrates one way to invoke a synchronous Mediator/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_ESBProcessRequest
xmlns='http://xmlns.oracle.com/SynchAdd_ESB'><input1>1234</input1><input2>12
34</input2></SynchAdd_ESBProcessRequest>";
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 LaunchSyncESBProcess");
End-If;

On execution the system displays the request message that the system sends to Oracle Mediator/ESB. If the invocation is successful, the system displays another box that shows the response from Oracle Mediator/ESB.

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.

See Managing Integration Gateway Message and Error LoggingViewing Monitor Output for Synchronous Service Operations Data.

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

This section discusses how to:

  • Create acknowledgements for invoking asynchronous Oracle Mediator/ESB-based services.

  • Manage routing definitions for invoking asynchronous Oracle Mediator/ESB-based services.

  • Set message and error logging for invoking asynchronous Oracle Mediator/ESB-based services.

  • Invoke an asynchronous Oracle Mediator/ESB-based service.

Understanding Invoking Asynchronous Oracle Mediator/ESB-Based Services

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

Prerequisites for Invoking Asynchronous Oracle Mediator/ESB-Based Services

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

See Consuming Oracle Mediator/ESB-Based Services.

Creating Acknowledgments for Invoking Asynchronous Oracle Mediator/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 Mediator/ESB-based services:

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

    See Implementing Handlers Using Application Classes.

  2. Open the service operation definitions for the consumed service operation.

  3. Click the Handlers tab.

    The Service Operations-Handlers page appears.

  4. Add a handler with the following characteristics:

    Field or Control

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

  5. Click the Details link.

    The Handler Details page appears.

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

    Field or Control

    Definition
    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 Mediator/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 Mediator/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 Mediator/ESB-Based Service

The following sample PeopleCode demonstrates one way to invoke the asynchronous Oracle Mediator/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_ESBProcessRequest
xmlns='http://xmlns.oracle.com/SynchAdd_ESB'><input1>6789</input1><input2>6789
</input2></SynchAdd_ESBProcessRequest>";
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 LaunchAsyncESBProcess", 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:

  1. The request message that it sends to Oracle Mediator/ESB.

  2. The transaction ID for the asynchronous request.

  3. The file location of the acknowledgement it received from Oracle Mediator/ESB

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 Mediator/ESB Console to check for the message instance and for the successful invocation of the Mediator/ESB service.

See Managing Integration Gateway Message and Error LoggingMonitoring Asynchronous Service Operation Transactions.

This section discusses invoking asynchronous request/response Oracle Mediator-based services.

Prerequisites for Invoking Asynchronous Request/Response Oracle Mediator-Based Services

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

See Consuming Oracle Mediator/ESB-Based Services.

Invoking an Asynchronous Request/Response Oracle Mediator-Based Service

To invoke an asynchronous request/response Oracle Mediator-based service, you must use an OnResponse handler. The following code shows a sample OnResponse handler:

import PS_PT:Integration:INotificationHandler;
import PT_ESB:ESBUtil;

class Esb_AsyncRR implements PS_PT:Integration:INotificationHandler
   method Esb_AsyncRR();
   method OnResponse(&MSG As Message);
end-class;

/* constructor */
method Esb_AsyncRR
end-method;

method OnResponse
   /+ &MSG as Message +/
   
   Local Message &request, &response;
   Local File &MYFILE;
   Local XmlDoc &xml, &inxml;
   Local string &payload, &oper, &input1, &input2, &result_st;
   Local integer &result_no;
   Local array of XmlNode &nodes;
   Local XmlNode &node;
   Local PT_ESB:ESBUtil &obj = create PT_ESB:ESBUtil();
   &nodes = CreateArray(&node);
   &request = &MSG;
   &inxml = &request.GetXmlDoc();
   &nodes = &inxml.GetElementsByTagName("input1");
   &input1 = &nodes [1].NodeValue;
   &nodes = &inxml.GetElementsByTagName("input2");
   &input2 = &nodes [1].NodeValue;
   &result_no = Integer(&input1) * Integer(&input2);
   &result_st = String(&result_no);
   
   &payload = "<?xml version='1.0'?><PSFTCalcResponseMessage xmlns='
   http://xmlns.oracle.com/Enterprise/Tools/schemas/PSFTCALCRESPONSEMESSAGE.V1'>
   <result>" | &result_st | "</result></PSFTCalcResponseMessage>";
   &xml = CreateXmlDoc(&payload);
   &response = CreateMessage(Operation.ESBASYNCRR, %IntBroker_Response);
   &response.SetXmlDoc(&xml);
   &response.IBInfo.WSA_MessageID = &request.IBInfo.WSA_MessageID;
   &response.IBInfo.WSA_ReplyTo = &request.IBInfo.WSA_ReplyTo;
   
   &obj.UpdateConnectorResponseProperties(&response);
   %IntBroker.Publish(&response);
   
   
end-method;