Integrating PeopleSoft CRM with Oracle E-Business Suite Using Oracle BPEL Process Manager
by Lawrence Pravin

A step-by-step approach for integrating PeopleSoft 8.9 CRM with Oracle Applications 11i using BPEL

Review complete BPEL Cookbook index

Downloads for this article: Sample Code Oracle BPEL Process Manager

Many organizations have heterogeneous application portfolios that cross different departments, geographic locations, or subsidiaries. While multiple ERP systems may be necessary to meet the requirements of the business unit, they essentially result in data fragmentation. Integration of these systems is complex and traditionally handled in a proprietary manner; nevertheless, companies invest significant energy in integrating information spread across multiple ERP systems to make better business decisions.

BPEL provides a standard, process-centric way to integrate disparate systems. Oracle's BPEL Process Manager, a key tool in Oracle Fusion Middleware for delivering service-oriented architecture (SOA), supports the industry-standard BPEL specification backed by Microsoft, IBM, SAP and BEA, and is widely recognized as an enterprise blueprint for reducing the cost, complexity, and inflexibility of integration projects.

In this installment of The BPEL Cookbook, I'll present an approach for integrating PeopleSoft 8.9 CRM (PeopleTools 8.46) with Oracle Applications 11i using BPEL. Specifically, via a sample business scenario, you'll learn how PeopleSoft is configured to expose its modules as Web services and how the BPEL Applications adapter is configured to interact with Oracle apps.

Functional Scenario

In a typical order management business scenario, an order is entered into the CRM system and fulfillment occurs through the back-office ERP. In this example, we are using PeopleSoft as the front-office application to manage marketing, sales, and service operations and Oracle E-Business suite for ERP (order management, inventory, and financials). The business process considered here is the Quote-to-Order process.

One part of this business process—quote and order entry—is executed in the CRM system, while order fulfillment is performed in the ERP system. To optimize internal operations, the entire cross-application Quote-to-Order business process needs to be automated.

Here is the functionality available in this business process integration (see Figure 1):

• A sales order in PeopleSoft can be created either by converting a quote into a sales order or directly through the Order Capture Screen.
• Upon submission, the system will check for the required information and change the status to OPEN; otherwise the status will be HOLD.
• This Sales Order Process will invoke and submit the order information to the Integration Process. This in turn will invoke BPEL Process Manager.
• BPEL Process Manager converts the messages data into the format required by Oracle ERP Order Management module.
• The sales order creation takes place in the Oracle ERP application, and the order acknowledgment is propagated to PeopleSoft.

• During the order creation process the salesperson may wish to check the availability of the material to promise the delivery date.
• PeopleSoft CRM will make a synchronous call to ERP application to get the on-hand available quantity using the Item/Product Availability inquiry component.
• BPEL Process Manager will transmit this ATP Check request to Oracle ERP.
• Oracle ERP will check the available quantity for the specific item from the inventory. It will send back the relevant availability details to BPEL Process Manager.
• BPEL Process Manager will pass on this ATP response information to PeopleSoft CRM. Based on this operation, the customer will be promised the actual delivery date.

• After propagating the sales order to ERP application, the order is booked in ERP, the acknowledgment is sent to BPEL Process, and in turn is propagated to PeopleSoft CRM system where the order status will be changed to "In Process".
• Oracle ERP will propagate the changes to the order status from time to time. This status from ERP is mapped to equivalent status in CRM.

Figure 1

Here we will focus on the order creation step. For further details about other steps in this process, please refer to the Oracle Apps Integration Cookbook .

Now that you understand the functional business process, let's see how it's accomplished at the architecture level. Figure 2 provides a high-level overview of the participating components for a typical integration between PeopleSoft CRM and Oracle Applications with Oracle BPEL Process Manager as the integration platform.

Figure 2

Enterprise Integration Points (EIPSs) are Web service connections that allow PeopleSoft applications to work smoothly with third-party systems and other PeopleSoft software. Upon submission of an order in PeopleSoft CRM, an EIP in PeopleSoft transforms it to XML format. This Order XML is then passed on to the attached PeopleCode method ( WSDL_ORDER ). (PeopleCode is the PeopleSoft programming language for enforcing business rules or performing other customizations.) WSDL_ORDER will convert the received Order XML into SOAP XML and send this request to the PeopleSoft remote node. The remote node is what handshakes with a configured Web service in BPEL Process Manager.

A Web service can be invoked from PeopleSoft by mapping the remote node to the WSDL using Web Service Invocation Framework (WSIF) binding, which is strongly supported by BPEL Process Manager. Upon receiving this SOAP XML, the PeopleSoft node will invoke the Web service based on the WSDL imported and configured to this node. The Web service is invoked and executed in BPEL Process Manager.

BPEL Process Manager processes the order data as SOAP XML and sends it to Oracle Applications; it internally leverages the Oracle Applications (OA) Adapter to communicate with 11i. OA Adapter is a pure JCA 1.5 Resource Adapter that can be used to send and receive messages from E-Business Suite. Oracle Applications exposes some of the seeded API and table to external Applications via this adapter.

Oracle Applications processes the order and sends the acknowledgment; BPEL Process Manager receives this response and forwards it to the PeopleSoft node. The node will then respond to the PeopleCode, which requested for the Web service. The latter will retrieve the XML data and submit it to the configured component interface in PeopleSoft. A component interface is what exposes PeopleSoft components for synchronous access from another application (written in Java or PeopleCode).

That's the high-level flow of Order data from PeopleSoft to Oracle Apps and back. In the next section, you'll learn how to expose PeopleSoft CRM modules as Web services, build a BPEL process, and configure the OA Adapter.

Once the order is submitted in PeopleSoft CRM, order information needs to be passed to Oracle Apps. There are three key steps in this process.

1. Design the business process in Oracle BPEL Process Manager.
2. Configure the Oracle Applications Adapter.
3. Configure PeopleSoft.

Let's take a deep drive into each of these steps:

In this step you will use BPEL Designer to create a process. BPEL Process Manager will receive the SOAP XML containing sales order information from PeopleSoft and transform it to the OA Adapter's XML format. (The schema will be generated by the OA Adapter automatically when the partner link is created for the calling API.) Then, the OA Adapter Partner link will be invoked and transformed and the Order XML submitted to Oracle Apps. The Oracle API will process the order and return the order number in output acknowledgment XML.

BPEL Process Manager handles remote and binding faults. When a connection is not available, it retries five times and then throws an exception. When a binding exception occurs, the binding fault will be handled.

A typical example of an integration business process designed for BPEL Process Manager is shown below.

(Click image to enlarge)

The critical activities in the process would be:

1. Select Applications > New Application Workspace > New Project > BPEL Process Project.
2. Import Schema to define input and output variables of the BPEL Process.
3. 1. From the structure window select project schemas > import Schema.
      Enter the input schema name (createorder.xsd).
   2. From the structure window, select Message Types.
   3. • Select CreateOrderRequestMessage and map CreateOrderIn root element of createorder.xsd.
      • Select CreateOrderResponseMessage and map CreateOrderOut root element of createorder.xsd.
   4. From the structure window, select Variables.
   5. • Confirm that InputVariable is mapped to CreateOrderRequestMessage.
      • Confirm that OutputVariable is mapped to CreateOrderResponseMessage.
4. Create the partner link for OA Adapter.
5. 1. Add a partner link activity from component palette to the CreateOrder Process and name it "CreateOrderPL".
   2. Click on Define Adapter Service and follow the steps below.
   3. Configure BPEL Process Manager and OA Adapter for the partner link (more on that later).
6. Add an Invoke activity to call OA Adapter.
7. 1. Drag and drop the invoke activity to the process and double-click on it.

   2. 
      
      
      
   3. Map the partner link to CreateOrderPL and create the input and output variables.
8. Add a transform activity above the invoke activity for transforming PeopleSoft outbound XML to Oracle Apps inbound XML.
9. 1. Double-click on the transform activity. Select the inputVariable as source variable, invokeCreateOrderInputVariable as target variable, and click on the create mapping icon as shown below.

   2. 
      
      
      
   3. Map the source and target schemas as shown below.

   4. 
      
      
      
10. Add another transform activity below the invoke activity for transforming Oracle Apps outbound XML to PeopleSoft inbound XML.
11. 1. Double click on the transform activity. Select invokeCreateOrderOutputVariable as source variable, outputVariable as target variable, and click on the create mapping icon.

    2. 
       
       
       
    3. Map the source and target schemas, as shown below.

    4. 
       
       
       

The following files, all available in the sample code download, will recreate the process described above in BPEL Designer.

You have now completed the design of the BPEL Process. Next, we'll take a detailed look at the configuration at the PeopleSoft end.

OA Adapter is deployed in Oracle Containers for J2EE in managed mode. It can be used to send and receive messages from E-Business Suite. Here are the steps involved in configuring the adapter.

1. Define an Adapter Service and select Oracle Applications Adapter.

2. 
   
   
   
3. Enter a service name. This name will be used as the Web service for the selected API/table.

4. 
   
   
   
5. Select a database connection that is defined in the project. If there is no DB connection available, click on New and follow the wizard.

6. 
   
   
   
7. Select the Table/Views/APIs interface to the Oracle Application Data.

8. 
   
   
   
9. Search for and select the PROC_ORDERENTRY_ARRAY API that is to be invoked from BPEL Process.

10. 
    
    
    

    Note: In this case, PROC_ORDERENTRY_ARRAY is the wrapper API written for the PROCESS_ORDER pre-seeded API because BPEL Process Manager will not support the oracle record type. Instead, you will use object types in a wrapper procedure similar to the record types used in PROCESS_ORDER. This interface is responsible to processing the sales order in Oracle Apps.

11. The API will be added to the Adapter Service.

12. 
    
    
    
13. The Oracle Applications partner link will be added to the BPEL Process, and APPS_PROC_ORDERENTRY_ARRAY.xsd will be created.

14. 
    
    
    

    A WSDL file will be created by the Adapter Service for the PROC_ORDERENTERY_ARRAY API, which behaves like a Web service and binds to the ERP using WSIF.

    The following files in the sample code download will help you configure the OA Adapter in BPEL Designer.

This completes the design of the BPEL process and the configuration of OA Adapter. Next (and finally), we'll configure PeopleSoft.

Now that you have created the BPEL process, let's look at the four-step process in configuring PeopleSoft.

• In Step 1, import the BPEL process WSDL into PeopleSoft. You will then use the imported WSDL to configure a node. This node will eventually communicate with the BPEL process.
• In Step 2, configure the Sales Order EIP to invoke this node whenever a new sales order is created.
• Finally, before the node sends the order information to BPEL process, you would need to transform it into a SOAP XML. Hence, in Step 3 and 4, you will write a small PeopleCode function to perform this transformation and establish its relationship with the node.

Let's drill down into each of these steps.

In this step, you will configure a node to interact with BPEL Process. You will define the request and response messages and channels on which these messages will travel.

First, import CreateOrder.wsdl (created previously) into PeopleSoft using the URL option. This identifies CreateOrder as the process, which will be invoked when an order is created in PeopleSoft. Upon importing the WSDL into PeopleSoft, the Integration Broker adds it to the WSDL repository.

To import CreateOrder.wsdl, select PeopleTools > Integration Broker > Web Services > Import WSDL.

You can now access the WSDL in the WSDL repository using the WSDL Repository page.

Once the CreateOrder WSDL is imported into PeopleSoft, a remote node has to be configured to communicate with the BPEL process. To define this communication, you have to add the corresponding request message, response message, and message channel.

To create a new remote node:

1. Select the Create a New Node Definition button.

2. 
   
   
   
3. In the Node Name field, enter BPEL_CREATEORDER for the new node definition.
4. In the Node Description field, enter a descriptive name for the node.
5. From the Authentication drop-down list, select an authentication method. The valid options are None (Default), Certificate, or Password.
6. (Optional) In the Password field, enter a password.
7. (Optional) In the Confirm Password field, re-enter the password.

Click on the Next button to proceed to the next page in the WSDL Operation Wizard, where you select request and response messages for the service. Request and response messages are unstructured messages that you create in PeopleSoft to represent SOAP Request and Response messages.

To create a new request or response message:

1. Select the Create a New Message option in the appropriate section.
2. To create a new request message, select the option in the Request Message section. Enter the BPEL_ORDER_REQ in the message name field.
3. To create a new response message, select the option in the Response Message section. Enter the BPEL_ORDER_RES in the message name field.
4. Newly created messages default the message version to VERSION_1. PeopleSoft Integration Broker populates the Message Version field with this value.
   
   
   
   

   PeopleSoft Integration Broker automatically assigns the new message to the new message channel. At end of the wizard configuration, the outbound synchronous transaction is created on the node using the new messages.

5. Enter the New Message channel Name in the channel name field as BPEL_SERVICES.
   
   
   

This completes Step 1. You imported the WSDL to tell PeopleSoft which Web service to call. You also defined node, messages, and channels to pass information to the Web service (BPEL Process CreateOrder). In the next step, you will establish a relationship between the Sales Order EIP and this newly configured node.

This step will create a link between the CRM_SALES_ORDER EIP and the new node. When the CRM_SALES_ORDER EIP is published to the integration broker, the above-created link will send the CRM_SALES_ORDER message to the above-created node as a request message.

• Select the Node Definition from the People Tools > Integration Setup; search for BPEL_CREATEORDER node.

• 
  
  
  
• In the above selected node, change the Transaction type as "Outbound Asynchronous" and enter Request Message as "CRM_SALES_ORDER".

In this step, you will create the Application Engine program WSDL_ORDER. (Application Engine is the PeopleSoft high-volume application processor. Application Engine programs are developed with the Application Designer and can leverage common PeopleTools objects such as records, PeopleCode, and SQL objects.) WSDL_ORDER will transform the sales order message received from the EIP to a BPEL request (SOAP message) and publish the transformed message on the node channel.

Add the following code to transform and send the request to the above-created node. Once the request is submitted to the node, the node will invoke the Web service configured to it. The Web service will be invoked and the response is sent back to the node, which sends the XML message to the PeopleCode method.

/* Get the data from the AE Runtime */
Local TransformData &transformData = %TransformData;
 
Local File &logFile = GetFile("TestSyncReqResStep3.log", "W", %FilePath_Absolute);
 
Local string &destNode = &transformData.DestNode;

&logFile.WriteLine("DestNode: " | &destNode);
 
/* Set a temp object to contain the incoming document */
Local XmlDoc &xmlDoc = &transformData.XmlDoc;

Local string &xmlStr = &xmlDoc.GenXmlString();
 
&logFile.WriteLine("Transformed XML : " | &xmlStr);

/* Maps the &xmlDoc  to the BPEL_ORDER_REQ and publish to the BPEL_CREATEORDER node. 
   Node will invoke BPEL CreateOrder process. 
   Response will be assigned to &response variable. */

Local XmlDoc &response = SyncRequestXmlDoc(&xmlDoc, Message.BPEL_ORDER_REQ, Node.BPEL_CREATEORDER);
 

&logFile.WriteLine("Response XML Data: " | &response.GenXmlString());
 
&logFile.Close();

In this step, you will relate the transformation code to the CreateOrder node. Hence, whenever BPEL Process Manager is invoked, this transformation code will be executed.

Create a new relationship WSDL_ORDER and map it to the node WSDL_ORDER. To do that:

Select Relationships from the People Tools > Integration Setup and select Add New Value.

• Map the initial node as BPEL_CREATEORDER , Request Message Name as CRM_SALES_ORDER , Transaction Type as OA , Result node as BPEL_CREATEORDER, and Request Message Name as CRM_SALES_ORDER and their versions will be selected by default. Then click on Add.

• Map the Transformation Request as WSDL_ORDER.

With heterogeneous applications across multiple different business units, organizations have challenges aggregating information. Integrating these systems represents a huge investment. Now, as demonstrated here, such organizations have a choice to easily integrate such applications using standards like BPEL.

Send us your comments