In this tutorial, you learn how to configure PeopleSoft Integration
Broker to publish an Application Message as an outbound SOAP message to an external
Oracle Enterprise Service Bus (ESB) process. You create an XSD from a WSDL file
that is generated by Peopelsoft and provide that XSD file as input to the ESB
service. You also learn how to create, deploy, and test an ESB service to receive
the published Application Message (a Sales Order from PeopleSoft.)
Place the cursor over this icon to load and view all the screenshots for this tutorial.
(Caution: This action loads all screenshots simultaneously, so response time may be slow depending on your Internet connection.)
Note: Alternatively, you can place the cursor
over an individual icon in the following steps to load and view only the screenshot
associated with that step. You can hide an individual screenshot by clicking it.
Overview
This integration example highlights PeopleSoft as a Web Service
provider for services that are consumed by Oracle SOA Suite Enterprise Service
Bus (ESB). A common business scenario is where an event is generated in Peoplesoft
and a number of external applications need to be made aware of the availability
of this event. For example, generation of a new Sales Order, new employee record,
or new journal entry are events that require order data, employee data or journal
data to be published to external system. In this tutorial, when a new Sales
Order is created in PeopleSoft CRM, an AppMessage is created, wrapped in a SOAP
envelope, and published using Integration Broker to Oracle ESB. As part of this
task, message schemas are extracted and provided to the ESB for service consumption.
ESB then consumes the message and routes it to any external application. This
tutorial uses a file system as an external application to which messages are
routed.
Have installed Oracle SOA Suite 10g (10.1.3.1).
You can download the software from Oracle Technology Network web site.
2.
Have installed Oracle Jdeveloper 10g (10.1.3.2).
You can download the software from Oracle Technology Network web site.
3.
Have access to Peoplesoft CRM 9 with PeopleTools
v8.48. For the PeopleSoft domain ensure that the PUB/SUB server is
up and that the process scheduler is started (you need psadmin screen
to perform these tasks).
This tutorial uses CRM 9.0 and CRM_SALES ORDER is the
application message that is published. CRM9.0 with PeopleTools 8.48 delivers
this message and the integration points out of the box. If you are using
a module other than CRM 9.0, for example HCM, then you need to apply the
steps mentioned here to your module. There will be differences in the
applications and functional steps, but for out of the box delivered integrations
(such as say, PERSON_BASIC_SYNC Application Message which is commonly
found in many peoplesoft modules) the majority of the PeopleTools configuration
steps are the same.
To perform steps described in this tutorial, first
make sure that PeopleSoft Configuration is ready. Verify that the PeopleSoft
Gateway is accessible and that the Peoplesoft Integration Broker service is
ready to create an outbound event message route as described below. Then define
the message type to be consumed by a Web Service consumer such as an Enterprise
Service Bus process.
1.
Define the Integration Broker Gateway:
Navigate to PeopleTools -> Integration Broker -> Configuration
-> Gateways
Click Search in the Gateways window to view a list of available
integration gateways. PeopleSoft Integration Broker is delivered out of
the box with one local gateway and details for that gateway are returned.
You can search explicitly for gateway ID = LOCAL as well.
Note: You can use this gateway as the default local
gateway or create a new gateway and designate that as the default local
gateway.
Enter URL in the following format http://<hostname>:<port>/PSIGW/PeopleSoftListeningConnector
(replace hostname and port with values appropriate to your installation).
Note that the URL value is case sensitive.
.
Click the Load Gateway Connectors button to load
the connectors delivered with PeopleSoft Integration Broker. Click Save
to save the changes. You will configure the HTTPTARGET connector for integration
with Oracle ESB in a later step in this tutorial.
Click the Ping Gateway button to make sure the
gateway status is active.
Notice the message that the gateway is activesee a response
as below
2.
Activate Integration Broker Domain.
Be sure to activate the pub/sub messaging server domain. This task has
to be performed using PSADMIN screens. Verify with your Peoplesoft system
administrator or you can find more details on this in Peoplebooks.
From the menu in the left side frame, navigate to PeopleTools ->
Integration Broker -> Configuration -> Quick Configuration.
In the Integration Broker Domains section of the page, locate
your machine name and notice that its Domain Status is Active.
Otherwise, click the Domain Status link from the Domains section
and select status to be active from the Domain Status drop down list.
Click Save.
3.
Set Up Integration Broker Service Configuration.
a.
Navigate to PeopleTools -> Integration
Broker -> Configuration -> Service Configuration. Verify
the settings on this page. This information is used for WSDL and
SOAP endpoints as well as schema and service namespaces.
b.
Set the Service Namespace and Schema
Namespace fields. You can accept the defaults.
In the Target Location field enter URL
in the following format http://<hostname>:<port>/PSIGW/PeopleSoftListeningConnector
(replace hostname and port with values appropriate to your installation).
Click Save.
4.
Verify that the GetWSDL and GetSchema Service Operations and Routings
are Active.
Make sure the GetWSDL and GetSchema service operations for the IB_UTILITY
service are Active and have Active Routings. These operations must be
available for WSDLs and Schemas to be generated. IB_UTILITY is a system
service that has these two operations to generate Schemas and WSDLs.
The IB_UTILITY Service record is retrieved.
From the Operations list, click the GETROUTINGS.V1 link to
view details about that service Operation.
c.
Verify that the Service Operation is active.
Click the Routings tab.
d.
Verify one and only one routing row is active.
If more than one routing row is active, click on the name of each
row to be inactivated and unselect the Active check box in the Routing
Definitions page.
e.
Perform steps 2-5 again for each of the other
Service Operations. (***??)
5.
Create Transformation Program to Append Namespace to Message.
A BPEL or ESB service requires namespace from a document root node. For
Outbound messages, namespaces are not added to Document Root Node by default.
Hence, you need to create an outbound message as PeopleCode Application
Engine Transformation program. This transformation program can generate
and append namespace to the document node. For example, consider the following
situation:
Before Transformation
<CRM_SALES_ORDER>
After Transformation
<CRM_SALES_ORDER xmlns="http://xmlns.oracle.com/Enterprise/Tools/schemas/CRM_SALES_ORDER.VERSION_1">
a.
Click Windows Start -> Programs -> PeopleTools
-> Application Designer, and open and login to Application
Designer
b.
In the Application Designer, select File >
New from the menu.
In the New Definition popup window, select
App Engine Program and click OK.
Name the App Engine Program as ADD_MSG_NS
and click Save.
c.
Click the Properties Button.
In the Program Properties window, click the Advanced
Tab.
Select Transform Only from the Program Type drop down
list.
Click OK.
d.
Highlight Step01 in the Definition page.
From the Insert menu, click Action. This inserts an
action in the Step01 Step.
e.
Change the Action Type to PeopleCode
f.
Double click the Action line to Edit the
Action.
Enter the following Peoplecode
/* Get the data from the AE Runtime */
Local TransformData &incomingData = %TransformData;
/* Set a temp object to contain the incoming document */
Local XmlDoc &inputDoc = &incomingData.XmlDoc;
/*This is the sample format to return<CRM_SALES_ORDER
xmlns="http://xmlns.oracle.com/Enterprise/Tools/schemas/CRM_SALES_ORDER.VERSION_1">*/
SQLExec("SELECT IB_SCHEMANAMESPACE FROM PSIBSVCSETUP", &sNameSpace);
&msgName = %TransformData.DestMsgName;
&msgVersion = %TransformData.DestMsgVersion;
&rootNode = &inputDoc.DocumentElement;
&rootNode2 = &rootNode.AddAttribute("xmlns", &sNameSpace | "/" | &msgName | "." | &msgVersion);
Click Save.
6.
Verify whether the CRM_SALES_ORDER Service Operation is active.
Navigate to PeopleTools -> Integration Broker -> Integration
Setup -> Service Operations. Search for the Service CRM_SALES_ORDER.
In the Services Operation section, click the CRM_SALES_ORDER link
to view details about this service.
Verify that the service is active.
7.
Activate Message Queue:
The CRM_SALES_ORDER message/service is in the SALES_ORDER_LOAD
queue, so we need to ensure that the queue is Running.
Navigate to PeopleTools -> Integration Broker -> Integration
Setup -> Queues. Search for the Queue SALES_ORDER_LOAD.
Ensure that the Queue Status is set to Run. Select the
Unordered check box so messages do not get backed up if a message
errors out. Click Save to save the page.
Nodes represent any organization, application or system that play a
part in integration. For example, nodes can represent customers, business
units, suppliers, other trading partners, external or third-party software
systems, and so on. Node definitions define the locations to or from
which messages can be routed. Because an application can send messages
to itself, a default local node definition that represents the application
is delivered as part of the integration engine.
Create a Node for your SOA Suite system.
a.
Open an Internet Explorer window and browse
to PeopleSoft URL. Login with a valid Userid and Password.
b.
From the menu on the left, navigate to PeopleTools
-> Integration Broker -> Integration Setup -> Nodes.
To create a new Node, click the Add a New
Value tab.
c.
Enter a unique name for the node.This tutorial
uses node name VICKY.
Click Add.
A node by name VICKY is now added. Click the
node name link in the search result to set the node definition.
d.
On the Node Definitions Tab, perform the following:
Enter a Description
Select External as the Node Type
Select None as the Authentication Option
Enter VP1 as the Default UserID (this is not used for Outbound
integration)
Click Save.
e.
Click the Connectors tab to set the
communication protocol.
The Gateway ID should already be set to LOCAL.
If not, enter LOCAL.
Click the Lookup Connector ID magnifying glass next to
Connector ID field and select HTTPTARGET from the
popup list.
You will see three HTTP properties. In value field
of property with ID PRIMARYURL, enter your ESB Console
URL http://<your IP Address>:<port>/esb/esb/EsbConsole.html
Click the Ping Node button to test connectivity to
the ESB Console.
You should receive a Success message as shown
in the following screenshot. If it is not successful, check your
URLIP Address and return to the Connector page to try again.
Click Save. We could click the routing
tab and add the routing but we will navigate a different way so
you get familiar with the other pages.
2.
Creating a Routing
A routing definition defines the sending and receiving nodes for a
transaction, and specifies any inbound and outbound transformations
to invoke. A routing definition must exist on each system that is participating
in a particular transaction.
For example, let's say that System A (local node) is going to send
a service operation to System B (ESB), a point-to-point routing needs
to be created between the two systems.
a.
In the PeopleSoft instance, from the menu on
the left, navigate to PeopleTools -> Integration Broker
-> Integration Setup -> Services.
b.
Enter CRM_SALES_ORDER in the search
field and click Search .
c.
In the Services page > Existing Operations
section, click the CRM_SALES_ORDER.VERSION_1 service operation.
d.
Create a routing to distribute the message
upon firing. On the Service Operation screen, select the ROUTINGS
tab.
e.
Create a routing to your specific node by typing
a unique name in the Routing Name field (ex. ROUTE_<nodename>)
and click the ADD button. This tutorial adds a routing
called ORDER2VICKYESB.
f.
Enter the following info on the Routing Definitions
tab
Description: Enter a description
Sender Node: Enter PSFT_CR (this is your local node name)
Receiver Node: This should be the node you created
g.
Click the Connector Properties tab.
h.
The Gateway ID should be LOCAL and the
Connector ID should be HTTPTARGET.
Setup the Connector Properties to match the
following:
HEADER CONTENT-TYPE text/xml; charset=utf-8
HEADER SOAPACTION "execute"
HEADER SENDUNCOMPRESSED Y
HTTPPROPERTY METHOD POST
HTTPPROPERTY SOAPUpContent Y
PRIMARYURL URL http://<your_ip_address>:port/event/PeopleSoft/Inbound/ReceivePSFTOrder_RS
By default only 3 properties are shown. To add
more properties so you can set the above values, click the + sign
corresponding to a property row below which you want to create
the new property row. To choose property ID, name, and value from
a list of available values, use the search icon relative to each
field. Otherwise you can directly type the value in the field.
Note: the SoapAction and Primary URL
must match the service that we will create in ESB.
i.
Now we need to add a transformation to add
proper Namespace to the outbound message. Click the Parameters
Tab.
j.
For the Message.Ver intoTransform
1 field, select CRM_SALES_ORDER.VERSION_1
k.
For the Transform Program 1 field, select
the transformation that was created in a previous step (ie ADD_MSG_NS)
l.
For the Message.Ver out of Transforms
field, select CRM_SALES_ORDER.VERSION_1
m.
Click Save.
3.
Creating XSD file from Generated WSDL
You need to import the XSD schema of the CRM_SALES_ORDER message into
the ESB project that you will create in the next section. The Provide
Web Service function generates a WSDL with inline XSD schema for
any Service/Service Operation with an "Any to Local" Inbound
Routing. Even though this tutorial is an Outbound integration and not
an Inbound integration, we will add an inbound routing so the WSDL can
be generated and we can pull the inline XSD.
Perform the following are the steps to generate a WSDL and to copy/paste
the schema from it to create a XSD file.
a.
Generate an Inbound Routing for our Service.
From the menu the menu on the left, navigate to PeopleTools
-> Integration Broker -> Services Operation. Enter CRM_SALES_ORDER
in the search field and click Search.
b.
In the Services Operation section, click the
CRM_SALES_ORDER link to view details about this service.
c.
In the Default Service Operations Version
> Routing Actions Upon Save section, select the Generate
Any-to-Local check box. Had the routing action been generated
previously, you will see the Regenerate Any-to-Local check
box instead.
d.
Click Save. This generates an Inbound
Routing and you receive a confimation message window. Acknowledge
and dismiss the window.
You can see the Inbound Routing by click on
the Routings tab.
e.
Now generate the WSDL. Navigate to PeopleTools
-> Integration Broker -> Web Services -> Provide Web
Service.
f.
In Step 1, enter CRM_SALES_ORDER as
the Service Name and click Search.
Make sure the CRM_SALES_ORDER Service
check box is selected and click the Next button.
In Step 2, select the Service Operation CRM_SALES_ORDER.VERSION_1
check box and click the Next button.
In Step 3, click the View WSDL link to
view the WSDL.
g.
Within the WSDL Viewer window, right click and
click Select All. Copy the content to a clip board.
Open a Notepad file on your system and paste
the copied content into it. The in-line schema that we want are
all lines beginning with tags <xsd:> or </xsd:>.
Remove all lines starting with <wsdl: or </wsdl:
at the start and end of the file so what is left is all lines
between tags <xsd:schema ….> and </xsd:
schema>.
In Notepad, select File > SaveAs to
save this file on your machine as CRM_SALES_ORDER.xsd.
Start JDeveloper: Double click jdevw.exe file
icon from the directory where you installed JDeveloper.
In the Application Navigator tab in JDeveloper,
right click Applications and select New Application…from
the popup menu.
b.
In the Create Application screen, name
the Application PeoplesoftESB and accept all default settings.
Click OK.
c.
Select Cancel in the Create Project dialog
box to dismiss it. You will create ESB project in a different way
in the next step.
2.
Create an ESB Project
a.
In the Applications Navigator, right click the
application node PeoplesoftESB that is created in the previous
step and select New Project from popup menu.
b.
The New Gallery dialog box opens.
Select Projects from Categories >
General and ESB Project from the list on the right pane,
Click OK.
c.
The Create ESB Project dialog box opens.
Nname the ESB project as ReceivePSFTOrder.
Accept all other default options and click OK. The newly
created ESB project ReceivePSFTOrder.esb is then displayed in the
Design Tab.
3.
Create an ESB System and Service Group
Ensure that the ReceivePSFTOrder.esb is open in the Design Tab.
a.
In the top tool bar of the Design window,
click the Create System/Group icon. This is the first of
the three icons.
b.
The Create ESB System or Service Group dialog
box opens.
In the Create ESB System or Service Group dialog box,
enter the following values:
Property Name
Value
Create
System
Name
Peoplesoft
Click OK.
c.
Now follow these steps to create the ESB service
group:
In the Design tab, click once again on the Create System/Group
icon from the top of the Design window.
The Create ESB System or Service Group dialog box opens.
In the Create ESB System or Service Group dialog box, enter
the following values:
Property Name
Value
Create
Service Group
Name
Inbound
System/Group
Observe this field is automatically populated with the ESB
system name Peoplesoft created in step b above.
If you would like to choose a different syste/service group,
click the browse icon and select the system/service group
from the available list.
Click OK.
4.
Adding a Routing Service to Receive PeopleSoft Order
a.
Right click in the design window, and select
Create ESB Service->Routing Service.
b.
Name the routing service as ReceivePSFTOrder_RS.
Observe that Peoplesoft.Inbound is automatically
populated as the System/Group value.
c.
Select Generate WSDLFromSchema
radion option. In the Request Tab click Browse to
browse scema location.
d.
In the Type Chooser window, click on the
Import Schema File icon (first icon of the two available
at the top right corner of the window)
e.
In the Import Schema File, click the Browse
File System... flash icon to browse the schema file.
f.
Browse to the location where the CRM_SALES_ORDER.xsd
schema file was saved from a previous step.
g.
Click OK to add the schema file to the
project.
h.
Expand Imported Schemas > CRM_SALES_ORDER.xsd
and select the CRM_SALES_ORDER element. Click OK.
i.
Make sure that the operation name is execute.
You will use this name in Peoplesoft instance. Click OK to
create the Routing Service.
j.
Notice that the routing service appears in the
design panel.
5.
Create an Adapter Services to Write Order to a File
a.
Anywhere in the ReceivePSFTOrder.esbv design
frame right click and select Create Adapter Service -> File
Adapter
b.
Name the adapter service as WriteToFile
and make sure the System/Group is Peoplesoft.Inbound
which was created in a previous step.
c.
If the System/Group is blank, click the browser
icon to find it.
d.
Click the Configure adapter service WSDL
search icon (the one next to WSDL file field)
e.
In the Adapter Configuration Wizard Welcome screen
(step 1), click Next.
f.
In step 2, accept the default service name and
click Next.
g.
In step 3, Choose Write File as the Operation
Type. The Operation Name will be Write. Click Next.
h.
In step 4, enter the directory to which the file
will be output. For example, you may use c:\temp as the directory
for Outgoing files.
Enter File Naming Convention as Order_%SEQ%.xml.
Click Next.
i.
In step 5, click the Browse button next
to Schema location.
j.
Select Project Schema Files ->CRM_SALES_ORDER.xsd
-> CRM_SALES_ORDER, and click OK.
k.
Return to step 4 configuration, Click Next
and then click Finish.
l.
Click OK to close the Adapter Service
window.
m.
Click OK to finish the file adapter service
creation process.
6.
Create Routing Rule to the File Adapter Service
.
a.
Double click the ReceivePSFTOrder_RS service
to create the routings to the Adapter Services you just created.
b.
Expand Routing Rules
c.
Click the green color + sign corresponding
to the execute operation to create a new routing rule to
the WriteToFile service.
d.
In the Browse Target Service Operation
window, expand Services in project > Peoplesoft > Inbound
> WriteToFile. Select WriteToFile > and click OK.
e.
A new routing rule is created which can be seen
in panel as shown below.
f.
Note: No Transformation is necessary since both
the Routing Service and the WriteToFile adapter service use the
same schema.
From JDeveloper menu bar, click the Save All
button to save your work.
g.
In the ReceivePSFTOrder.esb design window, the
visual diagram should look like the below screenshot:
7.
Register with ESB
.
a.
Start your SOA Suite instance.
b.
Register the ReceivePSFTOrder service to ESB.
In JDeveloper, right click on ReceivePSFTOrder in the
Applications Navigator and select Register with ESB >
OBE_Interation.
Note: OBE_Interation is name of the integration
server connection used for this tutorial. Use appropriate connection
for your system.
c.
You should see registration success information
in the ESB Registration Summary window. Othewise, verify your integration
server connection or connection to Peoplesoft instance.
d.
Open an Internet Browser window, and navigate to the ESB Control
Center http://<IPAddress>:<port>/esb/esb/EsbConsole.html
or navigate to Start > All Programs > OracleSOAHome > Oracle
ESB > ESB Control. Login to ESB Control Center using username
OC4Jadmin and password welcome1.
Verify the system and service group were correctly
published.
e.
In the Services section, expand Peoplesoft
> Inbound node. Click the ReceivePSFTOrder_RS Service
and click on the Definition tab.
View the service definitions to verify that the
WSDL URL and the SOAP Endpoint URI values match what you entered
in the Peoplesoft Routing Definition.
Note: this SOAP Endpoint URI should be
matched with your peoplesoft configuration.
Finally, we are ready to test by creating
a new Sales Order. The customer name and product ID used in our example here
are based on our local configuration. For your CRM instance, use a customer
and a product that exists in your system.
1.
Open an Internet Explorer window to the PeopleSoft URL and login to
PeopleSoft instance with appropriate Userid and Password.
From the menu on the left, navigate to Orders and Quotes -> Add
Order to open a New Order Form.
2.
In the Customer Field box, enter Adventure 54 and click
the Search button to bring up the customer record.
3.
In the Line Summary section > Add Product(s) field,
enter 10009 and click the Add button to retrieve the product
data.
4.
Click Submit.
5.
A message that the order has successfully been submitted is displayed
along with an Order ID at the top of the page.
6.
Return to the ESB Control Center browser window or start it if not
already open.
Click the Instance icon to see any new instance can be noticed.
7.
Click the Go arrow button that appears next to the Search
field to search for all the Instances. If you don't see any new instance,
review the Troubleshooting section.
8.
Highlight the retrieved Instance to see the Instance Diagram.
9
For final confirmation of a successful run, use Windows Explorer to
verify that the order file (Order_#.xml) was indeed created in the c:\temp
folder which is you identified in FileAdapater creation.
Bookmark
