Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle

Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter An Oracle White Paper

September 2008

Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 2

Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft

Adapter

INTRODUCTION

The Oracle AS Adapter for PeopleSoft is part of the Oracle AS Adapter install.

The Oracle AS Adapter for PeopleSoft can be deployed as both a web service

servlet as well as JCA 1.5 Resource Adapter. The Adapter Framework is used for

the bidirectional integration of the JCA 1.5 resource adapters with BPEL / ESB.

Adapter framework is based on open standards and acts as a pseudo JCA 1.5

container for deployment on top of J2EE JCA 1.0 containers. It manages the Life-

cycle (start/stop/endpoint activation/endpoint deactivation) as well as the

message-inflow system contracts for receiving adapter events and forwarding it to

the BPEL / ESB process.

The Oracle AS Adapter for PeopleSoft supports 3 ways of receiving PeopleSoft

events – HTTP, TCP and FILE. PeopleSoft Message Objects define PeopleSoft

events and they are published from PeopleSoft Application Messaging. The

PeopleSoft Application Messaging is used for configuring a process for publishing

PeopleSoft Message Objects to other 3rd party applications and has a FILE

publisher component for the above purpose. With PeopleTools 8.1 Series,

PeopleSoft can publish the message through a FILE protocol only. Hence Oracle

AS adapter for PeopleSoft extends Application Messaging by providing a TCP

Handler. This TCP Handler helps PeopleSoft to publish the message through the

TCP protocol also. So, for PeopleTools 8.1 series PeopleSoft adapter allows you

to receive messages through FILE and TCP channel.

This document provides step by step details on how to receive the event

notification from PeopleSoft backend to BPEL through PeopleSoft adapter. This

document applies to PeopleTools version 8.16, 8.17, 8.18, 8.19, 8.20, 8.21 and 8.22

for generating peoplesoft events.

Oracle AS PeopleSoft adapter supports File

and TCP protocols for receiving events in

the PeopleTools 8.1 series.


This document has been developed using the 10.1.3.1 SOA Suite & Adapters

installed on the windows platform, PeopleTools version 8.17 and HRMS

8.30.00.000 application version. Hence, if you are using a different platform /

version, then correlate the terms and commands specific to that operating system

by referring the user guides of the specific component.

Configuring the Oracle AS adapter for PeopleSoft

The Oracle AS Application Explorer is used to configure the Oracle AS Adapter

for PeopleSoft. WSDL files are created for both JCA Outbound (Request-

Response service – BPEL invoke) and JCA Inbound (Event Notification – BPEL

receive) Interactions and saved to a local directory. These WSDLs are exposed to

the BPEL Designer via the WSIL servlet. The JDeveloper based design-time

wizard has a WSIF browser that is launched from the BPEL Partner Link activity

to explore the WSDLs generated by the Oracle AS Adapter Application Explorer.

Configuration of the Adapter Target

Navigate to Start -> All Programs -> OracleAS 10g adapters -> Application

Explorer to start the Application Explorer. On top left, right click on configuration

and select “New”. Following window shows up. Enter the details as shown

below:

Following new configuration window shows up. Select “JCA” for Service

Provider. Enter the adapter installed folder for the Home.

Oracle AS Application Explorer is a GUI

Tool which can be used to connect to the

PeopleSoft using the adapter. This tool

provides the meta data exploration for the

PeopleSoft objects.


A new configuration by name jca_sample has been created and that will be shown

in the Application Explorer as shown below:

Select jca_sample, right click and select connect to connect to the jca

configuration. That will show two new nodes “Adapters” and “Events”.

Expand the Adapters node and select the PeopleSoft adapter to create a new target

for the PeopleSoft adapter. Right click on the adapter name to select the Add

Target option.


After creating the target, enter the password, then right click on the target and

select connect to connect to the target(Refer the PeopleSoft adapter user guide for

details on creating the Adapter target).

After connecting to the target, nodes for component interfaces and messages will

be shown in the Application Explorer.


Configuration of the Channel

Select the “Events” tab and then select the “PeopleSoft” node within the events

node.

Select the “Channels” under the “PeopleSoft” node and then right click on the

channel to “Add Channel”.

Channel establishes the connection

between PeopleSoft and BPEL at run time.


Following “Add Channel” window shows up.

Provide the following information:

Enter a name for the channel, for example, WORKFORCE_SYNC.

Enter a brief description (optional).

From the Protocol list, select TCP Listener.

Then click the “Next” button at the bottom of the window.

Following window shows up. Enter the details as per below given details.


Select the check box for is XML. Then click the “OK” button.

The channel that was created shows as like below in the Application Explorer.

The channel appears under the channels node in the left pane. An X over the icon

indicates that the channel is currently stopped.

Host Hostname where the SOAsuite and the adapters are up and

running. You cannot assign any remote host name.

Listener

port

Port on which to listen for PeopleSoft event data. Take a

note of this number as you should use the same port

number when configuring the Message Node in the

peoplesoft GUI.

Synchroni

zation

Type

Choose from the following synchronization options:

■RECEIVE_REPLY

■RECEIVE_ACK

Do not start the channel, as it is managed by BPEL PM Server. If you start the

channel for testing purposes, stop it before runtime.


Generating WSDL for Message

After you create a channel and verify that it is not started, you must generate

WSDL for the event using Application Explorer.

Go to the Adapter target and select the ‘Messages” node.

Messages node explode and the list of message object shows up:


Scroll down and select the message named as “WORKFORCE_SYNC”.

Right click and select the “Create Inbound JCA Service(Event)” option.

Window for “Export WSDL” shows up. Name of the WSDL shows up

automatically. Select following:

Element form Default - Qualified.

Channel - use the one that was created in step 10.

Port - No Port

Validation - Do not select anything.

Then click the OK button. Now, the WSDL would be created and will be stored

in a folder accessible for the JDeveloper.


Make sure that the channel is stopped. It should not be up and running. Then

Close the Application Explorer.

If OC4J is not up and running, then start the OC4J. If it is already running, then

recycle the OC4J. This is required for the OC4J to read the adapter repository to

understand the new target and channel.


BPEL Process creation in JDeveloper

Before you design a BPEL process using the WSDL you generated in Application

Explorer, you must configure a new Application Server and Integration Server

connection in Oracle JDeveloper. For more information, see Chapter 4 of the

PeopleSoft adapter user guide, "Integration with Oracle BPEL Process

Manager" for “Create a New Application Server Connection” and “Create a New Integration Server Connection”.

Start JDeveloper. Select the application tab and create a new project. The New

Gallery dialog box is displayed.

From the New Gallery window, select the BPEL Process project and then click

OK.

PeopleSoft adapter created WSDL can be

consumed by a BPEL / ESB process.


In the BPEL Project Creation Wizard, enter the following details and then click

the Finish button.

Name - PeopleSoft_workforce_Sync_inbound.

Namespace - Leave it to the default.

Template - Empty BPEL Process.

From the Services pane on the right, drag and drop a PartnerLink to the visual

editor.


Create partner link window shows up. Leave the value for the Name field as

default. Click the Service Explorer button.

The Service Explorer dialog box is displayed. Expand your new connection, and

then expand adapters, and then applications. The WSDL tree displays the

WSDL files you created using Application Explorer.


Select WORKFORCE_SYNC.VERSION_1_receive.wsdl and click OK. The

Create Partner Link dialog box is displayed. The WSDL File field displays the

name and location of the selected WSDL file. The Partner Link Type field

specifies the PartnerLink defined in the WSDL file.

Perform the following steps:

From the My Role list, select the default value

WORKFORCE_SYNC.VERSION_1Role.

Leave the Partner Role field unspecified. Click Apply, and then OK.

Workspace looks as like given below:


From the Process Activities pane on the right, drag a Receive activity to the

visual editor and place it in the designated placeholder labeled Drop Activity

Here.

Connect the Receive activity to the PartnerLink.


The Edit Receive dialog box is displayed.


Specify a name for the Receive Activity, for example, Receive_1.

Click the first icon to the right of the Variable field, and then click OK in the

Create Variable dialog box that is displayed. Verify that the Create Instance check

box is selected.

Click Apply. The Receive dialog box should no longer display any warnings or

errors.

Click OK.

The BPEL process looks as like given below:


Select Save from the File menu.

Deploying the BPEL Process for the Inbound Service

Right-click your project in the Applications Navigator tab. Select Deploy, then

Your BPEL PM Server connection, and then Deploy to default domain.

The deployment process starts automatically.

Deployment results can be checked in the bottom window of the JDeveloper.


PeopleSoft Configuration

Installing the TCP/IP Handler for PeopleTools Release 8.1

The TCP/IP target connector for PeopleTools release 8.1 is installed with

OracleAS Adapter for PeopleSoft. The default location on Microsoft Windows is

OracleAS_home\adapters\application\etc\peoplesoft\iwpsevent81.jar. Use the

corresponding location on non-Windows systems.

To install the TCP/IP Handler for PeopleTools release 8.1:

Port iwpsevent81.jar to the platform on which the PeopleSoft gateway Web server

is located.

Place iwpsevent81.jar in the servletclasses directory under the PeopleSoft Web

server.

Extract the embedded class files. Following are the class files that will be extracted

into the folder \psft\pt8\tcphandler under the web server folder.

The above completes the installation of the TCP/IP handler installation.

Configuring the TCP/IP Handler for PeopleSoft 8.1

The following procedure assumes that your Application Messaging environment is

properly configured and tested. To configure the TCP/IP Handler for PeopleSoft

8.1 to send messages to Oracle Application Server:

In a Web browser, launch the PeopleSoft 8.1 Gateway Configuration servlet

interface. For example, type the following URL in the browser:

http://psdemo817.oracle.com:18000/servlets/gateway.administration

Oracle AS PeopleSoft adapter extends

Application messaging by providing a TCP

handler to publish message through TCP

protocol.


If the Simple File Handler is currently loaded, unload and delete it before

proceeding. You must see an empty Handler directory.

Then Click the button Add handler.


Enter the full path of TCPIPHandler81 (case-sensitive):

psft.pt8.tcphandler.TCPIPHandler81

Click Save button.

The handler is added to the Gateway as shown below:


Click Load. The TCP Handler is loaded successfully.

Click Configure. The TCPIP81 Handler Directory window is displayed.

Click Add a TCPIP81 node. Enter the requested values based on the

information given below.

Field Value Example Description

Node Name EXTERNAL The name of the

TCP/IP node.

Host Name bpelclient The machine on

which your PeopleSoft

XML listener is

listening for incoming

messages.


Port 1971 The port on which

your PeopleSoft XML

listener is listening for

incoming messages.

Trace Directory /tmp The directory where a

trace file is created

when errors occur in

message delivery.

The system does not validate your entries.

Click Save. The TCPIP81 Handler Directory window is displayed.

The TCPIP handler is now configured in the PeopleSoft Gateway.

For your changes to take effect, click Back to Handler Directory to return to the

PeopleSoft 8.1 Handler Directory window.

Click Unload and re-Load TCPIPHandler81.


Configuring Application Messaging in PeopleTools Release 8.17

Creating and Configuring a New Message Node

Open PeopleTools –> Application Designer.

Select New from the File menu and click Message Node. A Message Node window

is displayed.

Right-click anywhere inside the white space and select Insert Location. The

Location URL box is displayed.

Enter the URL for the PeopleSoft Application Gateway (handler directory):

hostname:port/servlets/psft.pt8.gateway.GatewayServlet

Where hostname is the host name of your PeopleSoft Web server and port is the

socket on which the server is listening. The characters you enter after hostname are

case-sensitive.

Then Click OK.

PeopleTools 8.1 series uses Application

Messaging to publish a message to an

external application.


Select Menu File -> Save AS and enter the value as ‘EXTERNAL’.

To save the Message Node, click OK. You have finished creating and configuring

the message node.

Configuring and activating the Message

Open PeopleTools -> Application Designer.

On the File menu, point to Open, click Message, and open the

WORKFORCE_SYNC message.

To view the fields that are included in the message, highlight EMPLOYMENT.

Right-click EMPLOYMENT and select Properties. You will see the following

screen.


Select the menu File -> Object Properties. You will see the Message Properties

window.


Select the Use tab.

Ensure the Status check box is selected, which indicates that the message is active.

From the Message Channel list, select PERSON_DATA.

From the Default Version list, select VERSION_1 (messages can have multiple

versions).

Click OK. And save the message.


Configuring and activating the Message Channel

Open PeopleTools -> Application Designer.

From the menu, Select File, choose Open and click Message Channel.

To open the PERSON_DATA Message Channel, select PERSON_DATA.

Following window shows up:

Select from the menu, File -> Object Properties. The Message Channel Properties

dialog box is displayed.



Select the Use tab.

Ensure that the Message Channel status is set to Run.

Click OK.

From the Message Channel window, select the Routing Rules tab.

Right-click the pane and select Insert Message Node. The Insert Message Node

dialog box is displayed.



Select the message node that you created. For example, EXTERNAL.

Click Insert.

Click Cancel.

Information appears on the Routing Rules tab.

Now, Routing Direction should be assigned for the channel.


Right-click the message node and point to Routing Direction.

From the Routing Direction menus, select Publish To.

Save the Message Channel, and if you require it, place it in your project.

Configuring the Message Channel has been completed now.


Triggering the event

Logon to PeopleSoft. You will see the following screen.

Select the menu, Administer Workforce > Administer Workforce

(GBL) > Use > Job Data. You will see the following screen. Enter the value for

the EmplID or some other fields to select the desired employee record and click

the Search button. Make sure that you have selected the check box Correct

History.


Following screen shows up. Select the tab Job information tab.

Following screen shows up. Change the value of the Officer Code to Director

and the click the Save button at the very bottom of the page.

This completes the updating of the Employee record. This would have triggered

the event for the message workforce_sync.


Verification of the Results

Verification in Application Message Monitor

Navigate to Main Menu -> PeopleTools -> Application Message Monitor -> Use -

> Application Message Monitor. Here you can see the results of the events at the

channel level.

Select the number link (8) under the column Done, with the channel name

PERSON_DATA under the Overview tab.

That will take you to the “Pub Contracts” page. There you can see a new record

for the event for the Employee that we just updated. Click the Details link in the

below page.


That opens a new Browser window with the Details. You can note that the status

of the transaction is DONE on both the Message Instance Information and the

Publication Contracts.

Verification of result in BPEL Console

Login to the BPEL Console and navigate to the Instances Tab. There you can see

a new record for the event. Click the link below the Instance column.

It will take you to the Flow of the transaction and it will show the Visual flow of

the transaction. Click the link for “Receive_1”.


That will open the Dialog Box for the Receive_1. Click the link for the “View xml

document” in the Dialog page.

That will show the xml document for the updated employee

record(OFFICER_CD field has the value ‘D’).

CONCLUSION

Receiving PeopleSoft events through OracleAS PeopleSoft adapter is simple and

elegant way of doing in the BPEL process. Adapter provides a tightly coupled way

of integrating PeopleSoft events with BPEL and ESB.

REFERENCES

Oracle® Application Server Adapter for PeopleSoft User's Guide 10g Release 3

(10.1.3.1.0).

Enterprise PeopleTools – Application Messaging.

Receiving PeopleSoft Message(PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter

September 2008

Authors

Siva Krishnajee,

Product Manager,

iWay Software.

Vikas Anand,

Principal Product Manager,

Oracle Corporation.

Oracle Corporation

World Headquarters

500 Oracle Parkway

Redwood Shores, CA 94065

U.S.A.

Worldwide Inquiries:

Phone: +1.650.506.7000

Fax: +1.650.506.7200

oracle.com

Copyright © 2008, Oracle and/or its affiliates. All rights reserved.

This document is provided for information purposes only and the

contents hereof are subject to change without notice.

This document is not warranted to be error-free, nor subject to any

other warranties or conditions, whether expressed orally or implied

in law, including implied warranties and conditions of merchantability

or fitness for a particular purpose. We specifically disclaim any

liability with respect to this document and no contractual obligations

are formed either directly or indirectly by this document. This document

may not be reproduced or transmitted in any form or by any means,

electronic or mechanical, for any purpose, without our prior written permission.

Oracle is a registered trademark of Oracle Corporation and/or its affiliates.

Other names may be trademarks of their respective owners.

Documents

Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle