PeopleSoft-to-webMethods Communications

Overview

This chapter provides instructions for creating PeopleSoft-to-webMethods (outbound) transaction services. To create PeopleSoft-to-webMethods transactions, you must set up your PeopleSoft Web server for outbound transactions, and you must set up your Integration Server to handle the messages as they arrive from PeopleSoft. This chapter provides detailed instructions for those steps. Additionally, this chapter provides information about how to configure your PeopleSoft system to communicate to the Integration Server using SSL, and describes how to monitor your outbound PeopleSoft request messages at run time.

For a detailed description of PeopleSoft-to-webMethods communications, see PeopleSoft-to-webMethods Communications.

Note: For PeopleSoft-to-webMethods communications, the Adapter for PeopleSoft supports only the PeopleTools versions specified in the IBM webMethods Adapters System Requirements.

Setting Up the PeopleSoft Web Server for Outbound Transactions

To set up the PeopleSoft Web server to enable outbound communications to webMethods, perform the following steps:

Step	See
1	Creating Messages for Use with the Adapter for PeopleSoft
2	Configuring the Integration Gateway
3	Configuring a Node
4	Writing a PeopleCode Program for use with PeopleSoft Events

Note: Before setting up the PeopleSoft Web server, check the PeopleSoft server status and make sure the PUBSUB group is running. For details, see the PeopleBooks PeopleSoft Server Tools Administration document.

Creating Messages for Use with the Adapter for PeopleSoft

For PeopleSoft-to-webMethods communications, you must have a request message for outbound asynchronous transactions and you must have a request message and a reply message for outbound synchronous transactions.

You can use existing messages or you can create new messages. Use the PeopleSoft Application Designer to create the messages and their properties. See the PeopleBooks documentation for information about creating messages.

Configuring the Integration Gateway

About this task

To configure the Integration Gateway to communicate with webMethods

Procedure

Sign on to PeopleSoft by launching your browser and going to the following URL:

http://App_Server_Hostname:Port_Number/ps/signon.html

where App_Server_Hostname refers to WebLogic or WebSphere, as appropriate, and Port_Number refers to the port number of the application server.

Example: http://parts.west.smithco.com:8080/ps/signon.html
From the PeopleSoft menu, click the PeopleTools link.
Click Integration Broker, and then click Gateways.
You can select an existing Integration Gateway ID or add a new Integration Gateway.
- To select an existing Integration Gateway ID, click the Find an Existing Value tab, enter a search parameter to identify the Gateway ID, and then select the Gateway ID you want to use.
- To add a new Integration Gateway:
  1. Click the Add a New Value tab, type a name for the new Gateway, and then click Add.
  2. Enable the Local Gateway option. This Gateway must be the local Gateway.
  3. In Gateway URL, go to the URL for the selected Gateway's listening connector, as follows:
    http://App_Server_Hostname:Port_Number/PSIGW/PeopleSoftListeningConnector
    
    where App_Server_Hostname refers to WebLogic or WebSphere, as appropriate, and Port_Number refers to the port number of the application server.
    
    Example: http://parts.west.smithco.com:8080/PSIGW/PeopleSoftListeningConnector
  4. Click Load to load all available target connectors and verify that HTTPTARGET is in the list of connector IDs for the Gateway.
  5. Click Save.

Configuring a Node

About this task

To configure a PeopleSoft node, perform the following basic steps:

Define a Node
Define a Connector
Test the Node
Define a Transaction or Define a Service Operation

Important: If you are using PeopleTools versions 8.41, 8.42, 8.43, 8.44, 8.45, 8.46, or 8.47, you define a transaction. If you are using PeopleTools version 8.48 or 8.49, you define a service operation.

Define a Node

About this task

You can define a node by using an existing node or adding a new one.

Use an Existing Node

About this task

To define a node by using an existing node

Procedure

Launch your browser and sign on to PeopleSoft.
From the PeopleSoft menu, click PeopleTools > Integration Broker > Node Definitions.
Select an existing node as follows:
1. Click the Find an Existing Value tab and search for the node you want to use.
2. Select the node.
Proceed with defining a connector. For instructions on how to define a connector, see Define a Connector.

Use a New Node

About this task

To define a node by adding a new node

Procedure

Launch your browser and sign on to PeopleSoft.
From the PeopleSoft menu, click PeopleTools > Integration Broker > Node Definitions.

Add a new node as follows:

Click the Add a New Value tab.
Type the Node Name.
Click Add.

On the Node Info tab, specify the following parameters for the node. If a field or option is not listed in the table, you do not need to enter a value for the field or enable the option. For detailed field definitions, see the PeopleSoft documentation.

Field	Action/Description
Description	Type descriptive information about the node. Optional.
Company ID	Type your company ID.
Node Type	Select PIA.
Active Node	Enable this option.
Routing Type	Select Implicit.
Authentication Option	Select None if you do not require Authentication for this node, or select Certificate if you plan to use SSL with this node.

Click Save.

Proceed with defining a connector. For instructions on how to define a connector, see Define a Connector.

Define a Connector

About this task

To define a connector

Procedure

Launch your browser and sign on to PeopleSoft.
From the PeopleSoft menu, click PeopleTools > Integration Broker > Node Definitions > Connectors.
Verify the Node Name.
Select the Gateway ID for the gateway that you configured in Configuring the Integration Gateway.
Select HTTPTARGET as the Connector ID.

Type the following values in the Properties panel. For detailed field descriptions, see the PeopleSoft documentation.

Field	Action/Description
HEADER	Property Name: sendUncompressed Required: Enable this option. Value: Y Data Type: STRING Description: A descriptive text entry is optional.
HTTPPROPERTY	Property Name: Method Required: Enable this option. Value: POST Data Type: STRING Description: A descriptive text entry is optional.
PRIMARYURL	Property Name: URL Required: Enable this option. Value: The URL that points to the Integration Server, as follows: `http<s>://IntegrationServer_Host:Port/invoke/ wm.adapter.peoplesoft.outbound. sample:receiveXML` For example: `http://localhost:5555/invoke/wm.adapter. peoplesoft.outbound.sample:receiveXML` Data Type: STRING Description: A descriptive text entry is optional.
HEADER	Property Name: Authorization Required: Enable this option. Value: The user name and password used as Authorization to start the Integration Server. Use the following format, along with the encoding flow service listed below, to encode the user name and password: "Basic" (+ Base64Encode service using username + ":" + password) To encode the username and password, use the following utility flow service: wm.adapter.peoplesoft.outbound.utils.encoding where the input for the encoding service is a string constructed from the username and password, as follows: "`username`"+":"+"`password`" For example, if the username is "name" and the password is "pwd", the input for the encoding service would be "name:pwd". The result of encoding flow service for these values would be "bmFtZTpwd2Q". Thus, the value of the Authorization field would be "Basic bmFtZTpwd2Q". Data Type: Leave this field blank. Description: A descriptive text entry is optional.

Click Save.
You can test the node to check if the connection is getting through the gateway. For instructions on how to test the node, see Test the Node.
Proceed with defining a transaction or a service operation. For instructions, see Define a Transaction and Define a Service Operation.

Test the Node

About this task

To test whether the node's connection is getting through the gateway, ping the node.

To ping the node

Procedure

From the PeopleSoft menu, click Integration Broker > Monitor Messages.
Select the Node Status tab.
In the Message Node Name field, specify the node name and then click Ping Node.

Define a Transaction

About this task

If you are using PeopleTools versions 8.41, 8.42, 8.43, 8.44, 8.45, 8.46, or 8.47, define a transaction using the following procedure.

To define the node’s transaction

Procedure

Launch your browser and sign on to PeopleSoft.
From the PeopleSoft menu, click PeopleTools > Integration Broker > Node Definitions > Transactions.

Choose an existing transaction or add a new transaction.

To add a new transaction:

ClickAdd Transaction.

From the Add a New Value tab, provide values for the following fields. For detailed field descriptions, see your PeopleSoft documentation.

Field	Action/Description
Node Name	Select the name of the node you defined earlier.
Effective Date	Type the date the transaction should go into effect.
Transaction Type	Select Outbound Synchronous. For more information about Outbound Synchronous transactions, see the PeopleSoft documentation.
Request Message	Select the name of the request message.
Request Message Version	Select the message version.

Click Add.

On the Transaction Detail tab, provide values for the following fields. For detailed field descriptions, see your PeopleSoft documentation.

Field	Action/Description
Node Name	Verify the name of the node you defined earlier.
Effective Date	Verify the date the transaction should go into effect.
Status	Select Active.
Transaction Type	Verify that the transaction type is OutSync.
Request Message	Verify the name of the request message.
Request Message Version	Verify the message version.
Routing Type	Select Implicit.
Override Connector	Disable this option.
Comments	Optional descriptive text entry.

Click Transactions > Save.

On the Messages tab, provide values for the following fields. For detailed field descriptions, see the PeopleSoft documentation.

Field	Action/Description
Node Name	Verify the name of the node you defined earlier.
Effective Date	Verify the date the transaction should go into effect.
Status	Verify that the message status is active.
Log Message Detail	Enable this option if you want to see the transaction's full message details logged in the PeopleSoft Integration Broker Monitor.
Request Message:
Name	Verify the name of the request message.
Version	Verify the request message version.
External Name	Optional entry.
Response Message:
Name	Select the name of the response message.
Version	Select the response message version.
External Name	Optional entry.

Click Save.

Results

After you complete these steps, you should have a node defined with connectors and transactions similar to the following example:

Name	Value
Node	WEBM_NODE
GatewayID	LOCAL
ConnectorID	HTTPTARGET
Transactions	OutSync
Request Message	REP_SYNC, version_1
Response Message	WEBM_REPLY, version_1

Define a Service Operation

About this task

If you are using PeopleTools version 8.48 or 8.49, define a service operation using the following procedure.

To define the node’s service operation

Procedure

Launch your browser and sign on to PeopleSoft.
From the PeopleSoft menu, click PeopleTools > Integration Broker > Service Operations.

Select an existing service operation or add a new service operation.

To add a new service operation:

Click the Add Service Operationtab.

Provide values for the following fields. For detailed field descriptions, see your PeopleSoft documentation.

Field	Action/Description
Service	Select the name of the service you defined earlier.
Service Operation	Enter the name of the service operation. For example, WEBM_SO.
Operation Type	Select Synchronous. For more information about Synchronous transactions, see the PeopleSoft documentation.

Click Add.

On the General tab, provide values for the following fields. For detailed field descriptions, see your PeopleSoft documentation.

Field	Action/Description
Operation Description	Enter the description of the operation.
Request Message Version	Select the message version.
Response Message Version	Select the message version.

Click Save.

On the Routing tab, enter the Routing Name. For example, WEBM_ROUTING.
Click Add.

On the Routing Definitions tab, provide values for the following fields. For detailed field descriptions, see the PeopleSoft documentation.

Field	Action/Description
Sender Node	Should be the default local node. For example, PSFT_CR.
Receiver Node	Verify the name of the node you defined earlier. For example, WEBM_NODE. WEBM_NODE is the node representing the Integration Server.
Status	Verify that the message status is active.
Log Detail	Select an option.

Click Save.

Results

After you complete these steps, you should have a node defined with connectors and service operations similar to the following example:

Name	Value
Node	WEBM_NODE
GatewayID	LOCAL
ConnectorID	HTTPTARGET
Service Operation	WEBM_SO
Routing Name	WEBM_ROUTING

Writing a PeopleCode Program for use with PeopleSoft Events

About this task

For the Adapter for PeopleSoft's outbound transactions, you use the PeopleCode Editor to create a PeopleCode program for use with the component's SavePreChange or SavePostChange event. PeopleSoft calls SavePreChange events before any database updates and calls SavePostChange events after any database updates.

For an overview of how the Adapter for PeopleSoft uses PeopleCode programs, see PeopleSoft-to-webMethods Communications. For more details on PeopleCode events, see your PeopleSoft documentation.

To create a PeopleCode Program that sends a message to the node

Procedure

Start the PeopleSoft Application Designer. You must use the PeopleSoft Application Designer to view, edit, or create PeopleCode.
Open the component that has the request message attached to the SavePreChange or Save PostChange event.
View the PeopleCode for the selected component. See your PeopleSoft documentation if you need instructions on using the PeopleCode Editor.
If you are using PeopleTools versions 8.41, 8.42, 8.43, 8.44, 8.45, 8.46, or 8.47, select the event (for example, SavePostChange), and type the following code in the PeopleCode Editor:
```
Local Message &request, &response;  
Local Rowset &rep;  
&rep = GetLevel0();  
&request = CreateMessage(Message.REP_SYNC);  
&request.CopyRowsetDelta(&rep);  
&response = &request.SyncRequest(Node.WEBM_NODE);
```
where REP_SYNC is the name of the request message and WEBM_NODE is the node representing the Integration Server.
If you are using PeopleTools version 8.48 or 8.49, select the event (for example, SavePostChange), and type the following code in the PeopleCode Editor:
```
Local Message &request, &response;  
Local Rowset &rep;  
&rep = GetLevel0();  
&request = CreateMessage(Operation.WEBM_SO);  
&request.CopyRowsetDelta(&rep);  
&response = %IntBroker.SyncRequest(&request, Node.WEBM_NODE);
```
where WEBM_SO is the name of the service operation and WEBM_NODE is the node representing the Integration Server.
Click the Save.

Using the Adapter for PeopleSoft's Sample and Utility Services

After you set up your PeopleSoft Web server to send messages to the Integration Server, you must handle those messages (for example, accept the XML documents and then send reply messages to PeopleSoft, if required) as they are received by the Integration Server.

You can create your own services in the Integration Server to handle the messages, or you can use the sample flow service wm.adapter.peoplesoft.outbound.sample:receiveXML, which is provided in the WmPeopleSoftAdapter package, to handle the messages.

The wm.adapter.peoplesoft.outbound.sample:receiveXML flow service consists of the following services:

Service Name	Description
wm.adapter.peoplesoft.outbound.sample:getXML	Sample Java service that receives XML messages (for example, a REP_SYNC message) into a String.
wm.adapter.peoplesoft.outbound.sample:getDBTableName wm.adapter.peoplesoft.outbound.sample:mergeData	Sample Java services that extract fields from received XML messages.
wm.adapter.peoplesoft.outbound.sample:createReplyXML	Sample Java service that creates a response message (for example, WEBM_REPLY), in the XML format required by PeopleSoft.
pub.web:stringToDocument pub.web:documentToRecord	Built-in services that convert a string to a record.
pub.flow:setResponse	A built-in service that sends a response document back.

The adapter also provides the following utility services in the WmPeopleSoftAdapter package:

Service Name	Description
wm.adapter.peoplesoft.outbound.utils:testSetResponse	Tests the response XML.
wm.adapter.peoplesoft.outbound.utils:encoding	Encodes the username and password.

To use the sample services, you must modify the services for your specific outbound transactions. The samples contain comments that illustrate where you need to update them. For more information about outbound transactions, see PeopleSoft-to-webMethods Communications.

Using SSL to Communicate with the Integration Server

About this task

The following configuration needs to be done on your PeopleSoft system. For detailed instructions on how to implement SSL encryption in PeopleSoft, see the PeopleBooks PeopleSoft Integration Broker document.

Before you set up your PeopleSoft system to use SSL to communicate with the Integration Server, you must first configure the Integration Server to enable an HTTPS port. If you need instructions for setting up an HTTPS port, see the IBM webMethods Integration Server Administrator’s Guide for your release.

To use SSL to communicate with the Integration Server running on an HTTPS port

Procedure

Copy the CA Certificate used to set up an HTTPS port on the Integration Server to a temporary folder.
Copy the pskey file from the application server to the temporary folder. You can find the pskey in one of the following locations:
- For WebSphere:
  WebSphere_directory\Appserver\installedApps\peoplesoft\keystore
- For WebLogic:
  WebLogic_directory/config/peoplesoft/keystore
Make a backup copy of the pskey file.
Use the following command to add your CA Certificate to the key store:
```
JDK_1.3_Home_directory  /bin/keytool  -import  -trustcacerts  -alias  YourCompany  -file YOUR_CACERT.CER  -keystore pskey  -storepass password
```
where YourCompany is the name with which you will identify your CA Certificate, pskey is the file name of the keystore, and password is the password protecting the keystore. Initially its value is "password". If the default password value has changed, you can get it from the integrationgateway.properties file.
Restart your WebLogic or WebSphere application server.
You can now send your messages to the HTTPS URL that points to your Integration Server. For URL syntax and instructions, see Configuring a Node.

Monitoring PeopleSoft Request Messages

About this task

To monitor messages sent from PeopleSoft to webMethods

Procedure

Launch your browser and go to the following URL (if you have not already done so):

http://App_Server_Hostname:Port_Number/ps/signon.html

where App_Server_Hostname refers to WebLogic or WebSphere, as appropriate, and Port_Number refers to the port number of the application server.

Example: http://parts.west.smithco.com:8080/ps/signon.html
Click the PeopleTools link.
From the PeopleSoft menu, select Integration Broker and click Monitor Messages.

The Overview tab shows the list of messages. When an outbound transaction completes, the request message (for example, REP_SYNC) will be displayed on this tab with its corresponding status.
See the PeopleBooks PeopleSoft Integration Broker document for more information about administering messages.