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 Oracle AS PeopleSoft adapter supports File and TCP protocols for receiving events in the PeopleTools 8.1 series. 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 Lifecycle (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 3 rd 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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 2
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. 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. 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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 3
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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 4
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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 5
Configuration of the Channel Channel establishes the connection between PeopleSoft and BPEL at run time. 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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 6
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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 7
Host Listener port Hostname where the SOAsuite and the adapters are up and running. You cannot assign any remote host name. 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 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. 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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 8
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: Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 9
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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 10
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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 11
PeopleSoft adapter created WSDL can be consumed by a BPEL / ESB process. 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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 12
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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 13
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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 14
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: Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 15
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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 16
The Edit Receive dialog box is displayed. Perform the following steps: 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: Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 17
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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 18
PeopleSoft Configuration Oracle AS PeopleSoft adapter extends Application messaging by providing a TCP handler to publish message through TCP protocol. 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 Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 19
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. Perform the following steps: 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: Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 20
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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 21
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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 22
PeopleTools 8.1 series uses Application Messaging to publish a message to an external application. 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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 23
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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 24
Select the menu File -> Object Properties. You will see the Message Properties window. Perform the following steps: 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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 25
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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 26
Perform the following steps: 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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 27
Perform the following steps: 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. Perform the following steps: 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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 28
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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 29
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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 30
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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 31
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. Receiving PeopleSoft Message (PeopleTools 8.17) through the Oracle AS PeopleSoft Adapter Page 32
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 Page 33
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.