Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 2 Preparing PeopleSoft : Preparing PeopleSoft Application Messages

Preparing PeopleSoft Application Messages
TIBCO ActiveMatrix Adapter for PeopleSoft uses PeopleSoft application messages as schemas for formatting and processing data between a PeopleSoft application and the TIBCO environment. PeopleSoft application messages must be prepared so the design-time adapter can download them to the adapter’s configuration tool, TIBCO Designer.
Eliminate any unnecessary records and fields from the message. The simpler the message, the easier it is to set up and test the adapter.
The preparation steps given in this chapter assume you know PeopleSoft procedures. For complete information about creating messages and making them available, go to the PeopleSoft website and follow the Peoplebook-PeopleTools link to “Integration Tools: PeopleSoft Integration Broker.”
Before configuring the adapter, you must set up the Integration Broker based on the services you will configure in the TIBCO environment.
The following steps are involved in setting up the Integration Broker for PeopleTools 8.49:
1.
2.
3.
4.
5.
6.
7.
8.
Loading Gateway Connectors
For all PeopleSoft versions, follow these steps:
1.
2.
Navigate to PeopleTools > Integration Broker > Configuration > Gateways on the Menu navigation frame. The Gateways pane appears on the right.
Figure 4 The Gateways Pane
3.
Click the Add a New Value tab on the Gateways pane. In the Integration Gateway ID field, enter TIB_LOCAL, and then click the Add button. The information for TIB_LOCAL Gateway needs to be filled in, as shown in Figure 5.
Figure 5 Gateway Information
4.
Click the Ping Gateway button to make sure that PeopleSoft Listening Connector is active. In the URL field, enter the specified URL from where Gateway Connectors will be loaded, and then click the Load Gateway Connectors button. All loaded Gateway Connectors are shown in the Connectors area, as shown in Figure 6.
Figure 6 Gateway Connectors
 
5.
a.
Connector ID: TIBCOTARGET
b.
Connector Class Name: TibcoTargetConnector
6.
Click the Properties link for TIBCOTARGET Connector to open the Connector Properties pane and add the properties listed in Table 2 for the connector.
JMS_Server:port_no
For example 127.0.0.1:7222
Defining Messages
Message definitions provide the physical description of the data that is being sent, including fields, field types, and field lengths. Refer to PeopleTools PeopleBook for more information.
Follow these steps to define a message:
1.
2.
Navigate to PeopleTools >Integration Broker > Integration Setup > Messages on the Menu navigation frame. The Message Builder pane appears on the right.
3.
Click the Find an Existing Value tab on the Message Builder pane. For example, if you want to find a message whose name begins with COUNTRY, enter COUNTRY in the Message Name: begins with field, as shown in Figure 7. If you can not find the desired message, create a new message in the Adding a New Value tab. Refer to PeopleTools PeopleBook for more information.
Figure 7 The Message Builder Pane
Defining Message Queues
A Message Queue isolates different groups of service operations from each other. It needs to be created exclusively to handle messages meant for the adapter. You can also choose an existing Message Queue. If a message does not exist for a record from which data is to be exported, it needs to be created. Modifications to the existing Messages might be required.
Defining Services
PeopleSoft Integration Broker enables you to take an existing component interface and create a service which can be used to invoke the component interface.
To define a service, follow these steps:
1.
2.
Navigate to PeopleTools > Integration Broker > Integration Setup > Services on the Menu navigation frame. The Services page appears on the right.
3.
Click the Add a New Value tab on the Services page. Enter the Service name, and then click the Add button. The service information needs to be filled in, as shown in Figure 8.
Figure 8 Service Information
4.
5.
Click the Save button to save the changes. The specified service is created.
Defining Service Operations
A service operation definition consists of general information about an operation, such as its name, description, and so on. It also specifies an operation type, which determines how the operation is to be processed, synchronously or asynchronously. In addition, it contains routings which determine the direction, inbound or outbound, of the service operation. A service operation has one or more handlers, which contain and run the programming logic for sending or receiving the message, manipulating message content, and other functions.
After defining a service, you need to define service operations for the service.
To define a service operation for the service, follow these steps:
1.
2.
Navigate to PeopleTools > Integration Broker > Integration Setup > Service Operations on the Menu navigation frame.
3.
Click the Add Service Operation tab on the right page. Enter the Service name and the Service Operation name in the corresponding fields. Next, select an operation type from the Operation Type drop-down list, and then click the ADD button. The information for the service operation needs to be filled in on the next page. Refer to PeopleTools PeopleBook for more information..
Defining Nodes
Nodes represent any organization, application or system that will play a part in integrations. 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. Each PeopleSoft installation must have one, and only one, default local node.
To define a node, follow these steps:
1.
2.
Navigate to PeopleTools > Integration Broker > Integration Setup > Nodes on the Menu navigation frame.
3.
Click the Add a New Value tab on the right page. Enter the Node Name, and then click the Add button to open the next page.
4.
Click the Node Definitions tab to define the node, as shown in Figure 9. Refer to PeopleTools PeopleBook for more information.
Figure 9 Node Definitions
5.
Click the Connectors tab and define the connectors.
a.
b.
The steps to define a connector are the same for all adapter services. However, the Connector ID will change depending on the adapter service selected. Refer to Configuration Procedure for Adapter Services for detailed information.
Based on the adapter service selected, choose the appropriate Target Connector. The Integration Broker allows you to customize target connectors. TIBCOTARGET Connector is a connector defined by TIBCO that is installed on the Integration Gateway. TIBCOTARGET Connector facilitates the exchange of JMS messages between PeopleSoft and the adapter.
While installing the adapter, you need to use an unzip utility, such as Winzip or WinRAR, to extract the TIBCOTARGETConnector.jar file, and then copy the extracted *.class files from the directory Adapter_HOME\data\TibcoTargetConnector\com\peoplesoft\pt\integrationgateway\targetconnector to the following location in the Web Server:
PS_HOME\webserv\peoplesoft\applications\peoplesoft\PSIGW\WEB-INF\classes\com\peoplesoft\pt\integrationgateway\targetconnector.
Copy tibjms.jar from the TIBCO_HOME\ems\clients\java directory to
PS_HOME\webserv\peoplesoft\applications\peoplesoft
The JRE version used by the tibjms.jar file must be equal or lower than the JRE version used by PeopleSoft, otherwise, PeopleSoft application cannot send to or receive messages from TIBCO EMS QUEUE or TOPIC.
Defining Routings
Routing definitions determine the sender and receiver of an integration. Routing definitions allow you to specify inbound and outbound transformations that enable you to transform data structures into those that the sending or receiving systems can understand.
Follow these steps to configure a routing.
1.
2.
Navigate to PeopleTools > Integration Broker > Integration Setup > Routings on the Menu navigation frame.
3.
Click the Add a New Value tab on the right page. Enter the Routing Name, and then click the Add button to open the next page.
4.
Click the Routing Definitions tab and define the routing, as shown in Figure 10. Refer to PeopleTools PeopleBook for more information.
Figure 10 Routing Definitions
 
5.
Click the Save button to save the definition.
Check Configurations
After performing the above operations, you need to check your configurations.
1.
Navigate to PeopleTools > Integration Broker > Configuration > Quick Configuration on the Menu navigation frame. The Integration Broker Quick Configuration pane appears on the right.
a.
b.
2.
Navigate to PeopleTools > Integration Broker > Configuration > Service Configuration on the Menu navigation frame and then make sure that the value in the Target Location field is valid.
Configuration Procedure for Adapter Services
The basic steps listed in Preparing PeopleSoft Application Messages is the same for all adapter services, but the values assigned to certain parameters will differ based on the adapter services configured. Detailed information for each adapter service will be introduced in this section.
You may select one of the following transport types for each adapter service.
Message Publication Service
If you have selected a subscriber transport type while configuring the adapter, you may perform the following procedure:
1.
2.
a.
If you have selected HTTP transport type in the adapter, you may use the default gateway LOCAL, and then add a connector entry HTTPTARGET into it. Click the Properties link for HTTPTATRGET Connector to open the Connector Properties pane and add the properties listed in Table 3 for the connector.
HTTP_Server:port_no
For example, http://127.0.0.1:2002
b.
If you have selected JMS transport type, you may use the default gateway LOCAL and then add a connector entry TIBCOTARGET into it. Click Properties of TIBCOTATRGET Connector to open the Connector Properties pane and add the properties listed in Table 2 for the connector.
3.
To define a message, refer to Defining Messages. For example, if you have defined a message named COUNTRY_SYNC for the service, you can click on it to see its definition, as shown in Figure 11. Or, you can just use the pre-defined message.
Figure 11 COUNTRY_SYNC Message
 
4.
To define services, refer to Defining Services. If you have defined the COUNTRY_SYNC message from step 3, then you can defined a service based on it, as shown in Figure 12. Or, you can just use the pre-defined message and the related service that PeopleSoft delivered, such as COUNTRY_SYNC service.
Figure 12 COUNTRY_SYNC Service
5.
To define service operations, refer to Defining Service Operations. If you have defined COUNTRY_SYNC service in step 4, enter a service operation name, such as COUNTRY_SYNC, in the Service Operation name and select Asynchronous - One Way from the Operation Type drop-down list. Click the ADD button to create the new service operation, as shown in Figure 13.
Figure 13 Service Operation for Message Publication Service
6.
a.
PRIMARYURL: Specify the URL for the HTTP Listening Connector of the adapter. For example, http://127.0.0.1:2002
b.
JMSQueue: Use this property only if you have selected Queue to be the Connection Factory Type in the SubscriberOptions tab of the adapter in TIBCO Designer.
JMSTopic: Use this property only if you have selected Topic to be the Connection Factory Type in the SubscriberOptions tab of the adapter. The value of JMSTopic in PIA should match the subscriber subject under the SubscriberOptions tab in TIBCO designer.
JMSUrl: Enter the URL for the TIBCO Enterprise Message Server (EMS). For example, 127.0.0.1:7222
serviceType: Publisher
7.
To configure routings, you need to correctly set the sender node and the receiver node. For example, the sender node can be PSFT_HR in PeopleTools 8.49 and the receiver node can be TIB_NODE defined in the previous step.
Operations on PeopleSoft Application Designer
After performing the configuration for the adapter in PeopleSoft Application, you need to follow these steps in PeopleSoft Application Designer.
1.
2.
Select File > Open to open the Open Definition dialog, and then select Component from the Definition drop-down list. Type the component name, such as COUNTRY_TABLE in the Name field and then click the Open button to open the component definition pane.
3.
4.
When the PeopleCode Editor appears, leave the component name as is in the left hand side drop-down list and select the SavePostChange event from the right hand side drop-down list.
5.
In the PeopleCode Editor, paste the PeopleCode given below. If there are any existing lines of PeopleCode, you should comment them first and then append the code given below.
Replace the %message_name% with the corresponding message name without any quotes. (This PeopleCode will go into the SavePostChange event for the required Component)
Local Message &msg;
Local Message &msg1;
Local Rowset &rowSet;
Local XmlDoc &xmlDoc;
Local string &xmlString;
Local XmlNode &rootNode;
Local XmlNode &actionNode;
&rowSet = GetLevel0();
&msg = CreateMessage(Message.%message_name%);
&msg1 = CreateMessage(Message.%message_name%);
&msg.CopyRowset(&rowSet);
&xmlString = &msg.GenXMLString();
&xmlDoc = CreateXmlDoc(&xmlString);
&rootNode = &xmlDoc.DocumentElement;
&actionNode = &rootNode.FindNode("MsgData/Transaction/PSCAMA/AUDIT_ACTN");
&actionNode.NodeValue = %Mode;
&xmlString = &xmlDoc.GenXmlString();
&msg1.LoadXMLString(&xmlString);
&msg1.Publish();
6.
Message Subscription Service
If you have selected a transport while configuring the adapter, you may perform the following procedure:
1.
2.
a.
If you have selected HTTP as the subscriber transport type in TIBCO Designer, you may use the default gateway LOCAL, and then add a connector entry HTTPTARGET into it. Click the Properties link for HTTPTATRGET Connector to open the Connector Properties pane and add the properties listed in Table 4 for the connector.
HTTP_Server:port_no
For example, http://127.0.0.1:2002
b.
If you have selected JMS as the subscriber transport type in TIBCO Designer, you may use the default gateway LOCAL, and then add a connector entry JMSTARGET into it. Click Properties of TIBCOTARGET Connector to open the Connector Properties pane and configure the properties listed in Table 5 for the connector. The JMSQueue name IBSUB.QUEUE should differ with the queue name of the Message Subscription Service in TIBCO designer.
Note: Ensure that you have created a queue IBSUB.QUEUE in your adapter.
For example 127.0.0.1:7222
3.
To define a message, refer to Defining Messages. For example, if you have defined a message named CURRENCY_SYNC for the service, you can click on it to see its definition, as shown in Figure 14.
Figure 14 CURRENCY_SYNC Message
4.
To define services, refer to Defining Services. If you have defined a message named CURRENCY_SYNC in step 3, now define a service named CURRENCY_SYNC, as shown in Figure 15.
Figure 15 CURRENCY_SYNC Service
5.
Define service operations. If you have defined CURRENCY_SYNC service in step 4, enter a service operation name, such as CURRENCY_SYNC, in the Service Operation name and select Asynchronous - One Way from the Operation Type drop-down list. Click the ADD button to create the new service operation, as shown in Figure 16.
Your service operation name has to be the same as your message name. For example, if your message name is CURRENCY_SYNC, your service operation name must also be CURRENCY_SYNC.
Figure 16 Service Operation for Message Subscription Service
6.
To define a node, for example TIB_NODE, enter the following Connection Properties. You can also refer to Defining Nodes.
a.
If you have selected HTTPTARGET in the previous step, modify the following properties:
PrimaryURL: Specify the URL for the HTTP Listening Connector of the adapter. For example, http://127.0.0.1:2002
b.
If you have selected JMSTarget in the previous step, modify the following properties:
JMSFactory: QueueConnectionFactory or TopicConnectionFactory depending on the Connection Factory Type that you selected in the SubscriberOptions Tab of the message subscription service in TIBCO Designer.
JMSProvider: TIBCO
JMSUrl: Enter the URL of the TIBCO Enterprise Message Server (EMS). For example, tcp://EMS_Server:7222
7.
To configure routings, you need to correctly set the sender node and the receiver node. For example, the sender node can be TIB_NODE as defined in the previous step and the receiver node, which must be a LOCAL node, can be PSFT_HR.
Operations on PeopleSoft Application Designer
After performing the configuration for the adapter in PeopleSoft Application, you need to follow these steps in PeopleSoft Application Designer:
1.
2.
Select File > Open to open Open Definition dialog, and then select Message from the Definition drop-down list. Type the message name, such as CURRENCY_SYNC in the Name field and then click the Open button to open the message definition pane.
3.
4.
When the PeopleCode Editor appears, leave the message name as is in the left hand side drop-down list and select the Subscription event from the right hand side drop-down list.
5.
In the PeopleCode Editor, paste the PeopleCode given below. If there are any existing lines of PeopleCode, you should comment them first and then append the code given below. (This PeopleCode will go into the Subscription event of the PeopleCode for the required Component.)
Local Message &MSG;
Local Rowset &LEVEL0;
Local Record &rLocation, &REC;
&MSG = GetMessage();
&rLocation = CreateRecord(Record.CURRENCY_CD_TBL);
&LEVEL0 = &MSG.GetRowset();
/* Multiple level 0 rows may exist in AE batch programs,
but not with online panel processing... */
&REC = &LEVEL0(1).CURRENCY_CD_TBL;
&MSG.ExecuteEdits();
If &MSG.IsEditError Then
/*Specific error will be visible in App Msg Monitor */
Exit (1);
Else
&AUDIT_ACTN = &MSG.GetRowset()(1).PSCAMA.AUDIT_ACTN.Value;
Evaluate &AUDIT_ACTN
When = "C"
/* Data from publishing node was changed */
&REC.CopyFieldsTo(&rLocation);
&RES = &rLocation.Update();
/* If update failed, it is probably because the data in
the two databases hasn't been synchronized.
Try insert action as a last resort. */
If &RES = False Then
&rLocation.Insert();
End-If;
Break;
When = "A"
/* New high order key inserted in publishing node */
&REC.CopyFieldsTo(&rLocation);
&rLocation.Insert();
Break;
When = "D"
/* High order key was deleted in publishing node */
&REC.CopyFieldsTo(&rLocation);
&rLocation.Delete();
Break;
End-Evaluate;
End-If;
6.
Modifying Files for PeopleSoft Web Server
After performing the configuration for the adapter in PeopleSoft Application, you need to modify the content of some files to ensure the adapter works.
1.
Modify the integrationGateway.Properties file located in PS_HOME\webserv\peoplesoft\applications\peoplesoft\PSIGW\WEB-INF.
a.
In the file, replace the %user_name%, %password% %PeopleSoft_server_name:port_number%, and %EMS_server_name:port_number% with the corresponding value without any quotes.
b.
## JOLT connect string setting for optional Default Application Server. Do NOT specify a NODENAME.
c.
ig.isc.serverURL=%PeopleSoft_server_name:port_number%. For example, //10.97.97.222:9000.
ig.isc.userid=%user_name%
#Use the supplied "Password Encryption Utility" to generate an encrypted password for the next entry.
ig.isc.password=%password%
ig.isc.toolsRel=8.49
d.
# Enter the number of Queue listners to instantiate
ig.jms.Queues=1
# For each queue specify the following properties
# Name
# Provider
# JMSFactory name (which is binded to the JNDI)
# MessageSelector (optional Message Filter)
# JNDI System File URL
# JMS User
# JMS Password
ig.jms.Queue1=TEST_QUEUE_SUB
ig.jms.Queue1.Provider=Tibco
ig.jms.Queue1.JMSFactory=QueueConnectionFactory
ig.jms.Queue1.MessageSelector=
ig.jms.Queue1.Url=%EMS_server_name:port_number%. For example, tcp://127.0.0.1:7222.
ig.jms.Queue1.User=admin
# Use the supplied encryption utility to provide an encrypted password for the entry below
ig.jms.Queue1.Password=%password%
e.
# Enter the number of Topic Subscribers to instantiate
ig.jms.Topics=1
# For each Topic specify the following properties
# Name
# Provider
# JMSFactory name (which is binded to the JNDI)
# MessageSelector (optional Message Filter)
# JNDI System File URL
# JMS User
# JMS Password
ig.jms.Topic1=TEST_QUEUE_SUB
ig.jms.Topic1.Provider=Tibco
ig.jms.Topic1.JMSFactory=QueueConnectionFactory
ig.jms.Topic1.MessageSelector=
ig.jms.Topic1.Url=%EMS_server_name:port_number%. For example, tcp://127.0.0.1:7222.
ig.jms.Topic1.User=admin
# Use the supplied encryption utility to provide an encrypted password for the entry below
ig.jms.Topic1.Password=%password%
ig.jms.Queue1.URL has the same value as the URL specified in the JNDI URL field in the SubscriberOptions tab in the adapter.
The subject name contained in ig.jms.Queue1 is the same as the name entered in the IB Subscriber Subject field in the adapter.
To generate the password, run the utility program PSCipher located in PS_HOME\webserv\peoplesoft.
2.
Modify the web.xml file located in PS_HOME\webserv\peoplesoft\applications\peoplesoft\PSIGW
\WEB-INF.
<servlet>
<servlet-name>JMSListeningConnectorAdministrator</servlet-name>
<servlet-class>com.peoplesoft.pt.integrationgateway.listeningconnector.JMSListeningConnectorAdministrator </servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>JMSListeningConnectorAdministrator</servlet-name>
<url-pattern>/JMSListeningConnectorAdministrator/*</url-pattern>
</servlet-mapping>
3.
4.
http://ip_address/PSIGW/JMSListeningConnectorAdministrator?Activity=STOP
http://ip_address/PSIGW/JMSListeningConnectorAdministrator?Activity=START
Request-Response Invocation Service
If you have selected a transport while configuring the adapter, you may perform the following procedure:
1.
2.
a.
If you selected HTTP as the subscriber transport type, use the default gateway LOCAL, and then add a connector entry HTTPTARGET into it. Click the Properties link for HTTPTATRGET Connector to open the Connector Properties pane and add the properties listed in Table 3 for the connector.
b.
If you selected JMS as the subscriber transport type, use the default gateway LOCAL and then add a connector entry TIBCOTARGET to it. Click the Properties link for TIBCOTATRGET Connector to open the Connector Properties pane and add the properties listed in Table 2 to the connector.
3.
To define message, refer to Defining Messages. For example, you have defined a message named COUNTRY_SYNC for the service, click on it to see it’s definition, as shown in Figure 11.
 
4.
To define services, refer to Defining Services. If you defined the COUNTRY_SYNC message from step 3, then you can now define a service, such as COUNTRY_SYNC_RPCC service defined here, as shown in Figure 17.
Figure 17 COUNTRY_SYNC_RPCC Service
5.
a.
If you defined a service, such as the COUNTRY_SYNC_RPCC service in step 4, in the General tab, enter a service operation name, such as COUNTRY_RPCC, in the Service Operation name and select Synchronous from the Operation Type drop-down list. Click the ADD button to create the new service operation, as shown in Figure 18.
Figure 18 Service Operation for Request-Response Invocation Service
b.
6.
a.
PrimaryURL: Specify the URL of the HTTP Listening Connector. For example, http://127.0.0.1:2002.
b.
JMSQueue: Use this property only if you have selected Queue to be the Connection Factory Type in the SubscriberOptions tab of the adapter. Enter the Subscriber Subject in SubscriberOptions that corresponds to the value of the JMSQueue defined in TIBCOTARGET Connector Properties, refer to Table 2.
JMSTopic: Use this property only if you have selected Topic to be the Connection Factory Type in the SubscriberOptions tab of the adapter.
JMSUrl: Enter the URL of the TIBCO Enterprise Message Server (EMS). For example, 127.0.0.1:7222
serviceType: RPCCLIENT
7.
To configure routings, you need to correctly set the sender node and the receiver node. For example, the sender node can be PSFT_HR that must be a LOCAL node, and the receiver node can be TIB_NODE defined in the previous step.
Operations on PeopleSoft Application Designer
After performing the configuration for the adapter in PeopleSoft Application, you need to follow these steps in PeopleSoft Application Designer:
1.
2.
Select File > Open to open the Open Definition dialog and then select Component from the Definition drop-down list. Type the component name, such as COUNTRY_TABLE, in the Name field and then click the Open button to open the component definition pane.
3.
4.
When the PeopleCode Editor appears, leave the component name as is in the left hand side drop-down list and select the SavePostChange event from the right hand side drop-down list.
5.
In the PeopleCode Editor, paste the PeopleCode given below. If there are any existing lines of PeopleCode, you should comment them first and then append the code given below.
Replace the %service_operation_name% with the corresponding message name without any quotes. (This PeopleCode will go into the SavePostChange event of the PeopleCode for the required Component.)
Local Message &msg;
Local Message &msg1;
Local Rowset &rowSet;
Local XmlDoc &xmlDoc;
Local string &xmlString;
Local XmlNode &rootNode;
Local XmlNode &actionNode;
 
&rowSet = GetLevel0();
&msg = CreateMessage(Operation.%service_operation_name%);
&msg1 = CreateMessage(Operation.%service_operation_name%);
&msg.CopyRowset(&rowSet);
&xmlString = &msg.GenXMLString();
&xmlDoc = CreateXmlDoc(&xmlString);
&rootNode = &xmlDoc.DocumentElement;
&actionNode = &rootNode.FindNode("MsgData/Transaction/PSCAMA/AUDIT_ACTN");
&actionNode.NodeValue = %Mode;
&xmlString = &xmlDoc.GenXmlString();
&msg1.LoadXMLString(&xmlString);
&response = %IntBroker.SyncRequest(&msg1);
 
If (&response.ResponseStatus = 0) Then
&XML_STRING = &response.GenXMLString();
&SUCCESS_FILE = GetFile("c:\temp\sync0.txt", "w", "a", %FilePath_Absolute);
&SUCCESS_FILE.WriteLine(&XML_STRING);
&SUCCESS_FILE.Close();
MessageBox(0, "", 2, 0, "success");
Else
MessageBox(0, "", 2, 0, "error");
End-If
If Request-Response Invocation Service succeeds, the text file will be generated and the response message appears in the file under the following directory specified in the above PeopleCode: c:\temp\sync0.txt.
6.

Copyright © TIBCO Software Inc. All Rights Reserved