Integrating with BPEL Process-Based Services

This chapter provides an overview of integrating with Business Process Execution Language (BPEL) processes, lists prerequisites for integrating with BPEL processes, and discusses how to:

• Configure the PeopleSoft-delivered BPEL node.

• Consume BPEL process services.

• Provide PeopleSoft services to BPEL processes.

Understanding Integrating with BPEL Processes

PeopleSoft enables you to integrate with BPEL processes.

Oracle BPEL Process Manager

You can use any BPEL runtime engine for integrations with BPEL processes. The developer version of Oracle BPEL Process Manager is the BPEL engine that is referenced in this chapter.

See Also

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

Oracle JDeveloper Installation Guide

PeopleTools Installation Guide for your database

Oracle BPEL Process Manager Quick Start Guide

Oracle BPEL Process Manager Developer's Guide

PeopleSoft-Delivered Application Classes for BPEL Integrations

PeopleSoft provides several application classes for launching and controlling BPEL process instances. The following application classes are located in the PT_BPEL application package and are accessible in PeopleSoft Application Designer:

These classes are for use only when you use Oracle BPEL Process Manager as the BPEL runtime engine.

• AsyncFFSend

  This class provides the onSend handler implementation when calling a BPEL web service in an asynchronous fire and forget fashion.

• BPELUtil

  This class provides utility methods for interacting with BPEL processes from PeopleSoft systems.

• IBUtil

  This class provides utility methods to access PeopleSoft Integration Broker metadata.

See Also

BPEL Classes

Monitoring BPEL Process-Based Integrations

PeopleTools provides the following tools and logs for monitoring, tracing, and debugging integrations on PeopleSoft systems:

• Service Operations Monitor.

• Integration gateway logs.

• PeopleSoft application server logs.

In addition, your BPEL runtime engine may provide additional tools for monitoring integrations. For example, Oracle BPEL Process Manager provides the Oracle BPEL Process Manager Console for managing, administering, and debugging processes that are deployed on the BPEL server. In addition, the BPEL server logs may also provide additional details. Check your BPEL runtime engine documentation for additional information about monitoring tools that are provided.

See Also

Managing Error Handling, Logging, Tracing, and Debugging

PeopleTools 8.51 PeopleBook: Integration Broker Service Operations Monitor

Securing BPEL Process-Based Integrations

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 BPEL runtime engine that you are using and to implement those security options that fulfill your security requirements.

See Also

Setting Up Secure Integration Environments

Security Documentation for your BPEL runtime engine

Prerequisites for Integrating with BPEL Processes

For creating integrations with BPEL processes, you must have PeopleSoft Integration Broker configured and running.

Note. This section discusses prerequisite configuration steps on the PeopleSoft system for creating integrations with BPEL processes. Check your BPEL runtime engine software documentation for setup and configuration steps that you must perform on the runtime engine prior to performing integrations.

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

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

• PeopleSoft delivers a node, BPEL, specifically for BPEL integrations when you are using Oracle BPEL Process Manager as the runtime engine. If you are using Oracle BPEL Process Manager, you must configure this node. Steps to configure the BPEL node are provided elsewhere in this chapter.

The Understanding Creating and Implementing Integrations chapter of this PeopleBook contains additional information about creating and implementing integrations on PeopleSoft systems.

See Also

Understanding PeopleSoft Integration Broker Metadata

Using the Integration Broker Quick Configuration Page

Configuring the PeopleSoft-Delivered BPEL Node

PeopleTools delivers a node called BPEL for use for BPEL integrations when you are using Oracle BPEL Process Manager as the runtime engine.

Note. You must configure the BPEL node only if you are using Oracle BPEL Process Manager as the BPEL runtime engine.

To configure BPEL node properties:

1. Select PeopleTools, Integration Broker, Integration Setup, Nodes.

2. Search for and open the node BPEL.

   The Node Definitions page appears.

3. Modify any other fields on the Node Definitions page as required.

   See Defining Node Parameters.

4. Click the Properties link at the bottom of the page.

   The Node Properties page appears.

   Note. To view the complete BPEL property name in any of the Property Name fields, insert your cursor in a field and use your keyboard arrow keys to scroll through and view the complete field name.

5. Set the value of the BPELCONSOLEURL property to the URL of the BPEL console.

6. Set the BPELDOMAIN property to the name of the domain that you are using for the BPEL server.

7. Click the OK button.

Note. Do not set any values for the BPELDOMAINPWD property. This property is reserved for future use.

See Also

Adding and Configuring Nodes

Consuming BPEL Process–Based Services

This section provides an overview of consuming BPEL process-based services and discusses how to:

• Deploy BPEL processes.

• Import WSDL documents from BPEL processes.

• Consume synchronous BPEL operations.

• Consume asynchronous request/response BPEL operations.

• Consume asynchronous one-way BPEL operations.

In addition, the end of this section provides development considerations for consuming BPEL web services.

Understanding Consuming BPEL Process-Based Services

This section provides overview information about consuming BPEL process-based services.

Development Considerations

When consuming BPEL process-based services, consider that:

• XML content representing the payload must be constructed carefully and exactly.

• The XML namespace in the top-level element of the XML fragment representing the payload is obtained from the WSDL of the BPEL service operation.

• The LaunchSyncBPELProcess and LaunchASyncBPELProcess methods do not specify the actual endpoints to which a message is sent. This endpoint is inferred by PeopleSoft Integration Broker at runtime based on the active routing that is associated with the service operation. An exception is raised if no routing exists or if more than one active routing exists.

• When using the LaunchSyncBPELProcess and LaunchASyncBPELProcess methods, you must configure the routings for the message so that exactly one active routing exists for a message. Failure to supply exactly one routing results in a runtime exception.

• PeopleSoft Integration Broker automatically maps an external service operation to an internal PeopleSoft operation. If you attempt to import an external operation that contains the same name as an internal operation that already exists, PeopleSoft Integration Broker provides the new operation with a unique name and new metadata that maps the internal name to the external name. Make sure to use the unique internal name when calling any of the application class methods in the PT_BPEL application package.

• For the asynchronous request/response operations, you must select the correct callback (response) operation for a given service request. This is achieved during the Convert step in the Consume Web Service wizard.

Deploying BPEL Processes and Importing WSDL Documents

The first two steps for consuming any type of BPEL service are to deploy the BPEL process and import the generated WSDL document into the PeopleSoft system.

The following two sections discuss performing these tasks and must be completed before consuming BPEL operations.

Deploying BPEL Processes

The first step in consuming a BPEL process-based service is to deploy the BPEL process in the BPEL runtime engine, thereby generating a WSDL document. See the documentation for your BPEL runtime engine for information about performing this task.

The PeopleSoft system can consume WSDL documents from a UDDI repository, WSDL URL, WSIL URL, or file.

When deploying a BPEL process, note the URL of the WSDL document. You must provide the document location when consuming the WSDL into the PeopleSoft system.

Consuming WSDL Documents from BPEL Processes

To consume WSDL from a BPEL process into the PeopleSoft system use the Consume Web Service component in the PeopleSoft Pure Internet Architecture.

During the consume WSDL process you are prompted to choose a receiving node. If Oracle BPEL Process Manager is your BPEL runtime engine, it is preferred to select the PeopleTools-delivered BPEL node as the receiving node. The BPEL node is delivered with BPEL-server related information, such as the BPEL console URL and BPEL domain, already added. However, during consumption you can use the default WSDL_NODE or any other external node.

Make a note of the web service operation for the process that you are importing as you will call this operation in PeopleCode.

See Also

Consuming Services

Consuming Synchronous BPEL Operations

This section provides an overview of consuming synchronous BPEL operations and discusses how to:

• Create synchronous BPEL requests.

• Invoke synchronous BPEL operations.

• Process synchronous BPEL responses.

Understanding Consuming Synchronous BPEL Operations

Before consuming synchronous BPEL operations, you must deploy a BPEL process and import the generated WSDL document into the PeopleSoft system.

See Deploying BPEL Processes, Consuming WSDL Documents from BPEL Processes.

Creating Synchronous BPEL Requests

In this step, you use the PeopleSoft-delivered BPEL application classes to create a request message and initialize it with the message content, or payload. The payload is the content that will be sent as part of the soap body to invoke the BPEL process.

The first step is to create a BPELUtil object.

&bpel = create PT_BPEL:BPELUtil();

Next, create the request message and specify the operation to invoke. In the following pseudo code example, PROCESS is the operation to be invoked.

&payload = "<?xml version='1.0'?>
	<SyncCalcProcessRequest xmlns='http://xmlns.oracle.com/SyncCalc'>
	<messageid>TestId::0123456789</messageid><op>+</op><input1>9</input1>
	<input2>3</input2></SyncCalcProcessRequest>";

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

Invoking Synchronous BPEL Operations

To invoke a synchronous BPEL operation, use the LaunchSyncBPELProcess method of the BPELUtil application class.

The following example shows pseudo code for invoking a synchronous operation.

&reply = &bpel.LaunchSyncBPELProcess(&OP_NAME="PROCESS", &msg, "", "");

Processing Synchronous BPEL Responses

The following PeopleCode example shows sample pseudo code for processing a synchronous BPEL response.

If All(&reply) Then
   &responseStr = &reply.GenXMLString();
   End-If;

Example: Consuming Synchronous BPEL Operations

The following pseudo code provides an example of all the PeopleCode discussed earlier in this section.

import PT_BPEL:*;

Local PT_BPEL:BPELUtil &bpel;
Local string &url,  &transactionId, 
&payload, &responseStr, &OP_NAME;
Local Message &msg, &reply;
Local XmlDoc &xml;

/* --- creating a BPELUtil object---*/
&bpel = create PT_BPEL:BPELUtil();

/* --- setting operation name --- */
&OP_NAME="PROCESS";
&transactionId = "TestId::0123456789";

&payload = "<?xml version='1.0'?><SyncCalcProcessRequest xmlns=
'http://xmlns.oracle.com/SyncCalc'><messageid>TestId::0123456789</messageid>
<op>+</op><input1>9</input1><input2>3</input2></SyncCalcProcessRequest>";

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

&reply = &bpel.LaunchSyncBPELProcess(&OP_NAME, &msg, "", "");
If All(&reply) Then
   &responseStr = &reply.GenXMLString();
   End-If;
&url = &bpel.GetSyncBPELProcessInstanceUrl("BPEL", &transactionId);

See Also

BPEL Classes

Consuming Asynchronous Request/Response BPEL Operations

This section provides an overview of consuming asynchronous request/response BPEL operations and discusses how to:

• Create an asynchronous request/response BPEL request.

• Invoke an asynchronous request/response BPEL operation.

• Create a handler to process the asynchronous request/response BPEL response.

• Add a handler to a service operation to process the asynchronous request/response BPEL response.

This section also features a comprehensive example of the PeopleCode discussed in this section.

Understanding Consuming Asynchronous Request/Response BPEL Operations

Before consuming asynchronous request/response BPEL operations, you must deploy a BPEL process and import the generated WSDL document into the PeopleSoft system.

When you consume an Asynchronous Request/Response WSDL, you must identify the request and callback operations correctly in the Consume Web Service wizard.

See Deploying BPEL Processes, Consuming WSDL Documents from BPEL Processes.

Understanding Updating Asynchronous Request/Response WSDL for BPEL Callback Operations

If you are using Oracle BPEL Process Manager to generate WSDL for a PeopleSoft system to consume, you must modify the generated WSDL before attempting to consume it in the PeopleSoft system.

Note. This section applies only if you are using Oracle BPEL Process Manager 11g to generate WSDL for consuming in the PeopleSoft system.

If you are using earlier versions of Oracle BPEL Process Manager or another BPEL runtime engine, you may disregard the information presented in this section.

The WSDL created by Oracle BPEL Process Manager 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. You must add the following code to the WSDL document prior to consuming it in the PeopleSoft system.

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

Creating Asynchronous Request/Response BPEL Requests

In this step, you use the PeopleSoft-delivered BPEL application classes to create a request message and initialize it with the message content, or payload. The payload is the SOAP request (envelope) that will be sent to the BPEL process as a service.

&bpel = create PT_BPEL:BPELUtil();

Next, create the request message and specify the operation to invoke. In the following pseudo code example, CALCULATE is the operation to be invoked:

&payload = "<?xml version='1.0'?>
<ASyncCalcProcessRequest  xmlns='http://xmlns.oracle.com/ASyncCalc'>
<op>+</op><input1>9</input1><input2>3</input2></ASyncCalcProcessRequest>";

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

Invoking Asynchronous Request/Response BPEL Operations

To invoke an asynchronous BPEL operation, use the LaunchASyncBPELProcess method of the BPELUtil application class.

The following example shows pseudo code for invoking an asynchronous operation.

&responseStr = &bpel.LaunchASyncBPELProcess(&OP_NAME="CALCULATE", &msg, "", "");

Creating Handlers to Process Asynchronous Request/Response BPEL Responses

When you imported the asynchronous request/response BPEL WSDL document into the PeopleSoft system, the system automatically created a request message and response message for each service operation that is contained in the WSDL document.

To process the response, you must create a handler and add it to the service operation definition.

To create a handler for the response to an asynchronous request/response operation, use PeopleSoft Application Designer to extend the PS_PT:Integration:INotificationHandler application class and use the OnResponse method to code the response. When PeopleSoft Integration Broker receives the response for the service operation, Integration Broker will use the handler code to process the response.

The following example shows a sample pseudocode application class that is designed to handle the response:

import PS_PT:Integration:INotificationHandler;

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

/* constructor */
method ASyncTestHandler
end-method;

method OnNotify
   /+ &MSG as Message +/
   /+ Extends/implements PS_PT:Integration:INotificationHandler.OnNotify +/
   
   Local File &MYFILE;
   &MYFILE = GetFile("C:\temp\item.txt", "W", %FilePath_Absolute);
   
   If &MYFILE.IsOpen Then
      &MYFILE.WriteLine("--- Response Received ---");
      &MYFILE.WriteLine(&MSG.GenXMLString());
      &MYFILE.Close();
   End-If;
   
end-method;

Adding Handlers to Operations to Process Asynchronous Request/Response BPEL Responses

After you create the response handler, you must add it to the service operation definition. To perform this task, use the Service Operations–Handlers page. To access this page, select PeopleTools, Integration Broker, Integration Setup, Service Operations, and click the Handlers tab.

Example: Consuming Asynchronous Request/Response BPEL Operations

The following pseudo code provides a full example of all the PeopleCode discussed earlier for creating the asynchronous request and invoking the service operation.

import PT_BPEL:*;

Local PT_BPEL:IBUtil &ibutil;
Local PT_BPEL:BPELUtil &bpel;
Local string &url, &domain, &pwd, &opType, &asyncUrl, &transactionId, 
&payload, &responseStr, &OP_NAME;
Local number &routings;
Local Message &msg, &reply;
Local XmlDoc &xml;

/* --- creating a BPELUtil object --- */
&bpel = create PT_BPEL:BPELUtil();

/* --- setting operation name --- */
&OP_NAME = "CALCULATE";

&payload = "<?xml version='1.0'?><ASyncCalcProcessRequest xmlns=
'http://xmlns.oracle.com/ASyncCalc'><op>+</op><input1>9</input1>
<input2>3</input2></ASyncCalcProcessRequest>";

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

&responseStr = &bpel.LaunchASyncBPELProcess(&OP_NAME, &msg, "", "");
/*The Instance URL would be available only after the instance is created on the⇒
 BPEL engine. Programmatically wait for URL if needed*/
&url = &bpel.GetASyncBPELProcessInstanceUrl(&responseStr);

See Also

Managing Service Operation Handlers

BPEL Classes

Consuming Asynchronous Fire-and-Forget (One-Way) BPEL Operations

This section provides an overview of consuming asynchronous fire-and-forget BPEL operations and discusses how to:

• Create an asynchronous fire-and-forget BPEL requests.

• Invoke an asynchronous fire-and-forget BPEL operation.

• Add handlers to assign correlation IDs to requests.

Note. BPEL asynchronous fire-and-forget operations correspond to asynchronous one-way operations in PeopleSoft systems.

This section also features a comprehensive example of the PeopleCode discussed in this section.

Understanding Consuming Asynchronous Fire-and-Forget BPEL Operations

Before consuming asynchronous fire-and-forget BPEL operations, you must deploy a BPEL process and import the generated WSDL document into the PeopleSoft system.

See Deploying BPEL Processes, Consuming WSDL Documents from BPEL Processes.

Creating Asynchronous Fire–and–Forget BPEL Requests

In this step, you use the PeopleSoft-delivered BPEL application classes to create a request message and initialize it with the message content, or payload. The payload is the SOAP request (envelope) that will be sent to the BPEL process as a service.

The first step is to create a BPELUtil object.

&bpel = create PT_BPEL:BPELUtil();

Next, create the request message and specify the operation to invoke. In the following pseudo code example, FIREANDFORGET is the operation to be invoked:

&payload = "<?xml version='1.0'?>
<ASyncFFProcessRequest xmlns='http://xmlns.oracle.com/ASyncFF'>
<input>test</input></ASyncFFProcessRequest>";

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

Invoking Asynchronous Fire and Forget BPEL Operations

To invoke an asynchronous BPEL operation, use the LaunchASyncBPELProcess method of the BPELUtil application class.

The following example shows pseudo code for invoking an asynchronous operation:

&responseStr = &bpel.LaunchASyncBPELProcess(&OP_NAME, &msg, "", "");

Adding Handlers to Assign Correlation IDs to Requests

You can create a handler to add a WSA_MessageID to the SOAP request header before the request is dispatched for the BPEL process.

To create a such a handler use PeopleSoft Application Designer to extend the PS_PT:Integration:ISend application class and use the AsyncFFSend method.

The following example shows a sample pseudocode application class to perform this task:

import PS_PT:Integration:ISend;
import PT_BPEL:IBUtil;

class AsyncFFSend implements PS_PT:Integration:ISend
   method AsyncFFSend();
   method OnRequestSend(&MSG As Message) Returns Message;
end-class;

/* constructor */
method AsyncFFSend
end-method;

method OnRequestSend
   /+ &MSG as Message +/
   /+ Returns Message +/
   /+ Extends/implements PS_PT:Integration:ISend.OnRequestSend +/
   
   &MSG.IBInfo.WSA_MessageID = &MSG.TransactionId;
   Return &MSG;   
end-method;

Example: Consuming Asynchronous Fire-and-Forget BPEL Processes

The following pseudo code provides a full example of all the PeopleCode discussed earlier for creating the asynchronous request and invoking the service operation.

import PT_BPEL:*;

Local PT_BPEL:BPELUtil &bpel;
Local string &url, &payload, &responseStr, &OP_NAME;
Local Message &msg, &reply;
Local XmlDoc &xml;

/* --- creating a BPELUtil object --- */
&bpel = create PT_BPEL:BPELUtil();

/* --- setting operation name --- */
&OP_NAME = "FIREANDFORGET";

&payload = "<?xml version='1.0'?><ASyncFFProcessRequest xmlns='http:
//xmlns.oracle.com/ASyncFF'><input>test</input></ASyncFFProcessRequest>";

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

&responseStr = &bpel.LaunchASyncBPELProcess(&OP_NAME, &msg, "", "");

Example: Consuming Asynchronous Fire-and-Forget BPEL Processes
/*The Instance URL would be available only after the instance is created on the⇒
 BPEL engine. Programmatically wait for URL if needed*/
&url = &bpel.GetASyncBPELProcessInstanceUrl(&responseStr);

See Also

Managing Service Operation Handlers

BPEL Classes

Providing PeopleSoft Services to BPEL Processes

This section provides an overview of providing services to BPEL processes and discusses how to:

• Provide PeopleSoft synchronous operations to BPEL processes.

• Provide PeopleSoft asynchronous request/response operations to BPEL processes.

Understanding Providing PeopleSoft Services to BPEL Processes

This section provides overview information for providing services to BPEL processes.

Container Messages and Message Parts

If using container messages and message parts, create rowset-based parts in nonrowset-based containers. Doing so ensures that the XSchema that is generated for messages will not include PeopleTools-specific auditing information (PSCAMA). Typically, you do not want this auditing information to be included in the generated XSchema when integrating with BPEL processes.

Provide Web Service Wizard

When providing services to systems using BPEL, consider the following guidelines:

• The providing web services step using the Provide Web Service wizard described in this section is for synchronous and asynchronous request/response operations and is required only for an external client to be able to consume a PeopleSoft service.

• When providing the service, the WSDL document is exported to the WSDL repository in the PeopleSoft Pure Internet Architecture. Optionally, you can select to export the WSDL to a UDDI repository. PeopleSoft uses relative path URL for schemas referenced in the WSDL documents the system generates.

• After generating the WSDL document, carefully inspect the results using the WSDL Generation Log (the last page of the Provide Web Services wizard).

  The WSDL Generation Log contains the Generated WSDL URL. Copy this URL and store it somewhere carefully. You will need this WSDL URL later when calling the PeopleSoft-provided web service operation from the BPEL process.

See Also

Managing Container Messages

Providing Services

Providing Synchronous PeopleSoft Operations to BPEL Processes

This section discusses how to:

• Build synchronous PeopleSoft services.

• Provide synchronous PeopleSoft services as WSDL documents.

• Consume the service in a BPEL process and invoke the BPEL process.

Building Synchronous PeopleSoft Services

This section lists the steps for building synchronous PeopleSoft services. Detailed documentation for each step is provided elsewhere in this PeopleBook. See the end of this section for links to the appropriate documentation.

1. Define request and response messages to be associated with the service operation.

   Use the appropriate XSchema for each message.

   Schema for the messages are needed for generating the WSDL. If rowset-based messages are used in the operation, simply save the message definition to generate the schema. If nonrowset messages are used in the operation, you must manually provide schema. These schema will determine the request and response format during integration.

   Examples of XSchema for request and response messages are provided at the end of this section.

2. Create a handler to process the request message.

   Extend the PS_PT:Integration:IRequestHandler application class using the OnRequest method. The output of the handler will be communicated back as the response to the received request.

   An code example of an OnRequest handler is provided at the end of this section.

3. Create a new service.

4. Add a synchronous operation to the service.

   • Generate an any-to-local routing definition for the operation.

   • Add permissions to the service operation.

   • Add the OnRequest handler that you created in step 2 to the operation by referencing the package name, path, and class ID of the handler that you created in step 2.

See Sending and Receiving Messages, Managing Service Operation Handlers, Managing Services, Configuring Service Operation Definitions.

Providing Synchronous PeopleSoft Services as WSDL Documents

Use the Provide Web Services wizard to export the service and generate a WSDL document.

See Providing Services.

Consuming Services in BPEL Processes and Invoking Services from BPEL Processes

The last step is to consume the PeopleSoft-provided service in a BPEL process and then invoke the consumed service.

See the documentation that is provided with your BPEL runtime engine for the steps that are necessary to accomplish this step.

Example 1: Providing Synchronous Operations – Sample Request Message

The following pseudo code shows an example of a request message:

<?xml version="1.0"?> 
<xsd:schema targetNamespace="http://xmlns.oracle.com/Enterprise/Tools
/schemas/PSFTCALCREQUESTMESSAGE.V1" xmlns="http://xmlns.oracle.com
/Enterprise/Tools/schemas/PSFTCALCREQUESTMESSAGE.V1" xmlns:xsd="http:
//www.w3.org/2001/XMLSchema"> 
  <xsd:element name="PSFTCalcRequestMessage" type=
  "PSFTCalcRequestMessage_Type⇒
Shape"/> 
  <xsd:complexType name="PSFTCalcRequestMessage_TypeShape"> 
    <xsd:sequence> 
      <xsd:element name="op" type="xsd:string"/> 
      <xsd:element name="input1" type="xsd:decimal"/> 
      <xsd:element name="input2" type="xsd:decimal"/> 
    </xsd:sequence> 
  </xsd:complexType> 
</xsd:schema>

Example 2: Providing Synchronous Operations – Sample Response Message

The following pseudo code shows an example of a response message:

<?xml version="1.0"?> 
<xsd:schema targetNamespace="http://xmlns.oracle.com/Enterprise/Tools
/schemas/PSFTCALCRESPONSEMESSAGE.V1" xmlns="http://xmlns.oracle.com
/Enterprise/Tools/schemas/PSFTCALCRESPONSEMESSAGE.V1" xmlns:xsd="http:
//www.w3.org/2001/XMLSchema"> 
  <xsd:element name="PSFTCalcResponseMessage" type=
"PSFTCalcResponseMessage_TypeShape"/> 
  <xsd:complexType name="PSFTCalcResponseMessage_TypeShape"> 
    <xsd:sequence> 
      <xsd:element name="result" type="xsd:decimal"/> 
    </xsd:sequence> 
  </xsd:complexType> 
</xsd:schema>  

Example 3: Providing Synchronous Operations – OnRequest Handler

The following pseudo code shows an example of creating an OnRequest handler by extending the PS_PT:Integration:IRequestHandler application class:

import PS_PT:Integration:IRequestHandler;

class InboundSyncRequestHandler implements PS_PT:Integration:IRequestHandler
   method InboundSyncRequestHandler();
   method onRequest(&MSG As Message) Returns Message;
   method onError(&MSG As Message) Returns string;
end-class;

method InboundSyncRequestHandler
end-method;

method onRequest
   /+ &MSG as Message +/
   /+ Returns Message +/
   /+ Extends/implements PS_PT:Integration:IRequestHandler.OnRequest +/
   
   Local Message &response;
   Local File &MYFILE;
   Local XmlDoc &xml, &inxml;
   Local string &payload, &oper, &input1, &input2;
   Local array of XmlNode &nodes;
   Local XmlNode &node;
   
   &nodes = CreateArray(&node);
   &inxml = &MSG.GetXmlDoc();
   &nodes = &inxml.GetElementsByTagName("op");
   &oper = &nodes [1].NodeValue;
   &nodes = &inxml.GetElementsByTagName("input1");
   &input1 = &nodes [1].NodeValue;
   &nodes = &inxml.GetElementsByTagName("input2");
   &input2 = &nodes [1].NodeValue;
   
   &payload = "<?xml version='1.0'?><PSFTCalcResponseMessage xmlns=
'http://xmlns.oracle.com/Enterprise/Tools/schemas
/PSFTCALCRESPONSEMESSAGE.V1'><result xmlns=">9</result></PSFTCalcResponse⇒
Message>";
   
   &xml = CreateXmlDoc(&payload);
   &response = CreateMessage(Operation.PSFTCALCULATE, %IntBroker_Response);
   &response.SetXmlDoc(&xml);
   
   Return &response;
end-method;

method onError
   /+ &MSG as Message +/
   /+ Returns String +/
   /+ Extends/implements PS_PT:Integration:IRequestHandler.OnError +/
   
   Local integer &nMsgNumber, &nMsgSetNumber;
   Local string &str;
   
   &nMsgNumber = &MSG.IBException.MessageNumber;
   &nMsgSetNumber = &MSG.IBException.MessageSetNumber;
   &str = &MSG.IBException.DefaultText;
   
   Return &str;
end-method;

Providing Asynchronous PeopleSoft Request/Response Operations to BPEL Processes

This section discusses how to:

• Build asynchronous request/response PeopleSoft services.

• Provide an asynchronous request/response PeopleSoft service as a WSDL document.

• Consume the service in a BPEL process and invoke the BPEL process.

Building Asynchronous Request/Response PeopleSoft Services

This section lists the steps for building asynchronous request/response PeopleSoft services. Detailed documentation for each step is provided elsewhere in this PeopleBook. See the end of this section for links to the appropriate documentation.

1. Define request and response messages to be associated with the service operation.

   Use the appropriate XSchema for each message.

   Examples of XSchema for request and response messages are provided at the end of this section.

2. Create a handler to process the request message.

   Extend the PS_PT:Integration:INotificationHandler application class using the OnNotify method. The output of the handler will be communicated back as the response to the received request.

   A code example of an OnNotify handler is provided at the end of this section.

3. Create a new service.

4. Add an Asynch Request/Response operation to the service.

   • Generate an any-to-local routing definition for the operation.

   • Add permissions to the service operation.

   • Add the OnNotify handler that you created in step 2 to the operation by referencing the package name, path, and class ID of the handler.

For Asynchronous Request/Response PeopleSoft services, you must invoke the UpdateConnectorResponseProperty method of the BPELUtil class in OnNotify before sending the asynchronous response to BPEL. This will override the default content-type from text/plain to text/xml as expected by BPEL. If this is not done, BPEL will return an HTTP 415 Unknown Media-Type error.

See Sending and Receiving Messages, Managing Service Operation Handlers, Managing Services, Configuring Service Operation Definitions.

Providing Asynchronous PeopleSoft Services as WSDL Documents

Use the Provide Web Services wizard to export the service and generate a WSDL document.

See Providing Services.

Consuming Services in BPEL Processes and Invoking Services from BPEL Processes

The last step is to consume the PeopleSoft-provided service in a BPEL process and then invoke the consumed service.

See the documentation that is provided with your BPEL runtime engine for the steps that are necessary to accomplish this step.

Example 1: Providing Asynchronous Request/Response Operations – Sample Request Message

The following pseudo code shows an example of a request message:

<?xml version="1.0"?> 
<xsd:schema targetNamespace="http://xmlns.oracle.com/Enterprise/Tools
/schemas/PSFTCALCREQUESTMESSAGE.V1" xmlns="http://xmlns.oracle.com
/Enterprise/Tools/schemas/PSFTCALCREQUESTMESSAGE.V1" xmlns:xsd="http:
//www.w3.org/2001/XMLSchema"> 
  <xsd:element name="PSFTCalcRequestMessage" type=
"PSFTCalcRequestMessage_TypeShape"/> 
  <xsd:complexType name="PSFTCalcRequestMessage_TypeShape"> 
    <xsd:sequence> 
      <xsd:element name="op" type="xsd:string"/> 
      <xsd:element name="input1" type="xsd:decimal"/> 
      <xsd:element name="input2" type="xsd:decimal"/> 
    </xsd:sequence> 
  </xsd:complexType> 
</xsd:schema>

Example 2: Providing Asynchronous Request/Response Operations – Sample Response Message

The following pseudo code shows an example of a response message:

<?xml version="1.0"?> 
<xsd:schema targetNamespace="http://xmlns.oracle.com/Enterprise/Tools
/schemas/PSFTCALCRESPONSEMESSAGE.V1" xmlns="http://xmlns.oracle.com
/Enterprise/Tools/schemas/PSFTCALCRESPONSEMESSAGE.V1" xmlns:xsd="http:
//www.w3.org/2001/XMLSchema"> 
  <xsd:element name="PSFTCalcResponseMessage" type=
"PSFTCalcResponseMessage_TypeShape"/> 
  <xsd:complexType name="PSFTCalcResponseMessage_TypeShape"> 
    <xsd:sequence> 
      <xsd:element name="result" type="xsd:decimal"/> 
    </xsd:sequence> 
  </xsd:complexType> 
</xsd:schema>   

Example 3: Providing Asynchronous Request/Response Operations – Sample OnNotify Handler

The following pseudo code shows an example of creating an OnNotify handler by extending the PS_PT:Integration:INotification application class. Note that you must invoke the UpdateConnectorResponseProperty method of the BPELUtil class before performing the publish.

import PS_PT:Integration:INotificationHandler;

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

method OnNotify
   /+ &MSG as Message +/
   /+ Extends/implements PS_PT:Integration:INotificationHandler.OnNotify +/
   
   Local Message &response;
   Local string &payload;
   Local XmlDoc &xml;
   Local File &MYFILE;
   
&payload = "<?xml version='1.0'?><PSFTCalcResponseMessage xmlns=
'http://xmlns.oracle.com/Enterprise/Tools/schemas
/PSFTCALCRESPONSEMESSAGE.V1'><result xmlns=">9</result></PSFTCalcResponse⇒
Message>";
   
   &xml = CreateXmlDoc(&payload);
   &response = CreateMessage(Operation.PSFTASYNCCALCULATE, 
%IntBroker_Response);
   &response.SetXmlDoc(&xml);
   &response.IBInfo.WSA_MessageID = &MSG.IBInfo.WSA_MessageID;
   &response.IBInfo.WSA_ReplyTo = &MSG.IBInfo.WSA_ReplyTo;
   &bpel.UpdateConnectorResponseProperties(&response);
   %IntBroker.Publish(&response);
end-method;