Third Party Integration using the Integration Broker

Contains:
√ √ √ √ √ √ Prepared by:

T H I R D P A R T Y I N T E G R AT I O N U S I N G T H E I N T E G R AT I O N BROKER 4/10/2009

Comments on this document can be submitted to redpaper@peoplesoft.com. We encourage you provide feedback on this Red Paper and will ensure that it is updated based on feedback received. When you send information to PeopleSoft, you grant PeopleSoft a non-exclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you.

4/10/2009 This material has not been submitted to any formal PeopleSoft test and is published AS IS. It has not been the subject of rigorous review. PeopleSoft assumes no responsibility for its accuracy or completeness. The use of this information or the implementation of any of these techniques is a customer responsibility and depends upon the customer's ability to evaluate and integrate them into the customers operational environment.

3

Table of Contents

TABLE OF CONTENTS....................................................................................................................... ......................4 CHAPTER 1 - INTRODUCTION......................................................................................................................... ........6

Structure of this Red Paper.........................................................................................................6 Related Materials .........................................................................................................................6
CHAPTER 2 - SYSTEM OVERVIEW .................................................................................................. .....................7

Integration Broker Architecture...................................................................................................7 Message Flow Through the Broker; Incoming request............................................................8
Step 1 – Request is received by the Listening Connector............................................................................................................8 Step 2 – Request is processed by the PeopleSoftTarget Connector.............................................................................................9 Step 3 – Request is received by the Application Server..............................................................................................................9 Step 4 – Response is returned by the Application Server..........................................................................................................10 Step 5 – Response is received by the PeopleSoftTargetConnector............................................................................................10 Step 6 – Response is received by the ListeningConnector........................................................................................................10

Message Flow Through the Broker; Outgoing request..........................................................10
Step 1 – Application Server generates request..........................................................................................................................11 Step 2 – Request is received by the PeopleSoftListeningConnector.........................................................................................11 Step 3 – Request is received by the Target Connector...............................................................................................................11 Step 4 – Response is received by the TargetConnector.............................................................................................................12 Step 5 – Response is received by the PeopleSoftListeningConnector.......................................................................................12 Step 6 – Response is received by the Application Server..........................................................................................................12

Requirements for Incoming Messages ....................................................................................12
Credentials.................................................................................................................................................................................12 Message Body.............................................................................................................................................................................13 PeopleSoft Requirements for Messages Bodies.........................................................................................................................13

Integration Broker Internal Format for Request Messages....................................................14
MIME.........................................................................................................................................................................................14 IBInfo XML................................................................................................................................................................................15 Content Section..........................................................................................................................................................................18

Integration Broker Internal Format for Response Messages.................................................18
MIME.........................................................................................................................................................................................18 IBInfo XML................................................................................................................................................................................19 Content Section..........................................................................................................................................................................20 Error Codes and Message Catalog Entries................................................................................................................................20

Manipulating Content Sections via Transforms......................................................................21 Character Encoding Considerations........................................................................................22
CHAPTER 3 –INTEGRATION EXAMPLES USING THE CONNECTORS.............................................. ................23

4

4/10/2009

Basic Setup for the Examples...................................................................................................23
Add a Message Channel............................................................................................................................................................23 Add a Request Message.............................................................................................................................................................23 Add a Response Message...........................................................................................................................................................24 Add the Source Node.................................................................................................................................................................24 Add the Target Node..................................................................................................................................................................24 Add the Source Transaction.......................................................................................................................................................25 Add the Target Transaction........................................................................................................................................................26 Add the Relationship and Transaction Modifier.......................................................................................................................26

Integrating using HTTP..............................................................................................................28
HTTP Message Credentials........................................................................................................................................................28 Sending HTTP requests to the Integration Broker....................................................................................................................29 HTTP requests from the Integration Broker to external systems..............................................................................................32 HTTP Cookies............................................................................................................................................................................35 SSL Considerations....................................................................................................................................................................35

Integrating using SOAP..............................................................................................................36
Sending SOAP requests to the Integration Broker....................................................................................................................36 SOAP requests out of the Integration Broker............................................................................................................................40

Integrating using FTP.................................................................................................................42
FTP requests from the Integration Broker to external systems.................................................................................................42

Integrating using JMS................................................................................................................45
Receiving Published JMS Messages .........................................................................................................................................45 Publishing JMS Messages ........................................................................................................................................................50

Integrating using SMTP..............................................................................................................54
Sending email from the Integration Broker to external systems...............................................................................................54

Integrating using POP3..............................................................................................................58
APPENDIX A – SPECIAL NOTICES....................................................................................................... .................69 APPENDIX B – VALIDATION AND FEEDBACK...................................................................................................... 70

Customer Validation...................................................................................................................70 Field Validation............................................................................................................................ 70
APPENDIX C – JMS MQ INTEGRATION......................................................................................... .......................71 APPENDIX D – REVISION HISTORY.................................................................................................... ..................78 Authors.......................................................................................................................................................................................78 Reviewers ..................................................................................................................................................................................78 Revision History.........................................................................................................................................................................78

5

4/10/2009

Chapter 1 - Introduction

This Red Paper is a practical guide for technical users, installers, system administrators, and programmers who implement, maintain, or develop applications for your PeopleSoft system. In this Red Paper, we discuss guidelines on how to use the Integration Broker and the Connectors on the Gateway in order to integrate the broker with third party systems.

STRUCTURE OF THIS RED PAPER
The first part of this paper presents a discussion of how the Integration Broker processes incoming and outgoing messages. While this information is fairly low level, a general understanding of how things are done is very useful for providing a context for the rest of the paper. The remainder of this paper presents detailed examples of how to use the gateway connectors in various configurations. There are many ways that the connectors can be used, and it is not the purpose of this document to exhaustively list all such potential configurations. Users should attempt to try the examples exactly as presented. The examples have been created so that they should be relatively easy to set up. Once this is done, users can try the examples and see how the system actually works. Keep in mind that PeopleSoft updates this document as needed so that it reflects the most current feedback we receive from the field. Therefore, the structure, headings, content, and length of this document is likely to vary with each posted version. To see if the document has been updated since you last downloaded it, compare the date of your version to the date of the version posted on Customer Connection.

RELATED MATERIALS
This document is not intended to replace the documentation delivered with the PeopleTools 8 or 8.14 PeopleBooks. We recommend that before you read this document, you read the Integration Broker related information in the PeopleTools PeopleBooks to ensure that you have a well-rounded understanding of our technology. Note: Much of the information in this document eventually gets incorporated into subsequent versions of the PeopleBooks. Many of the fundamental concepts related to the Integration Broker are discussed in the following PeopleSoft PeopleBooks: • Application Designer • Application Messaging • PeopleCode • Integration Broker

© Copyright PeopleSoft Corporation 2001. All rights reserved.

6

4/10/2009

Chapter 2 - System Overview

INTEGRATION BROKER ARCHITECTURE
The integration broker consists of two major components: the integration gateway and the application server. The application server is the core of the system. It processes incoming messages, executes any necessary PeopleCode, and is responsible for interfacing with the database to store information. The integration gateway is a collection of Java servlets and classes running on a web server. The main responsibility of the gateway is to provide an interface between the application server and external systems. The gateway isolates the application server from the various communication protocols that can be used to access it. The gateway also normalizes all incoming requests so that by the time they reach the applications server, they are in a standard format. Similarly, it also converts requests being sent out of the application server from the standard to a format suitable for the outgoing protocol being used. Although the gateway is comprised of many different classes, two broad types are of interest here: Listening Connectors and Target Connectors. Listening Connectors are used to “listen” for incoming requests from external systems. These connectors provide the point of entry for external systems into the integration broker, and such systems directly access these connectors in order to send requests. Each connector is responsible for normalizing the incoming protocol dependant request before it is sent on to the application server. Listening Connectors are protocol specific. The following listening connectors are currently available: • • • HTTPListeningConnector – handles incoming HTTP requests, including Simple Object Access Protocol (SOAP) requests made over HTTP JMSListeningConnector – handles Java Messaging Service (JMS) requests PeopleSoftListeningConnector – handles incoming requests from other integration brokers.

Target Connectors complement the Listening Connectors. Target Connectors provide the mechanism for the application server to send requests to external systems. Requests from the application server are sent to the gateway in normalized format. Once the request reaches the gateway it is then passed to the appropriate target connector, which will then convert it to a format appropriate for the outgoing protocol. The message is then sent out to the external system. Target Connectors are also protocol specific. The following target connectors are currently available: • • • • • • HTTPTargetConnector – handles outgoing HTTP and SOAP requests FTPTargetConnector – allows the retrieval of files from a File Transfer Protocol (FTP) server JMSTargetConnector – handles outgoing Java Messaging Service requests SMTPTargetConnector – allows email to be sent to a Simple Mail Transfer Protocol (SMTP) server POP3TargetConnector – allows email to be retrieved from a Post Office Protocol (POP3) account. PeopleSoftTargetConnector – handles requests being sent to other integration brokers.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

7

4/10/2009 Since the PeopleSoft listening and target connectors are not commonly used for integrations with third parties, they will not be covered in this document. For further information, please refer to the Integration Broker document.

MESSAGE FLOW THROUGH THE BROKER; INCOMING REQUEST
This section will examine in detail the flow of a typical request message through the integration broker. After the incoming request has been received by the gateway, the flow through the broker is the same, regardless of the Listening Connector that was initially invoked. With this in mind, no specific Listening Connector will be discussed here. Please refer to the following chapter to see specific examples of integration to the various listening connectors.

Integration Gateway Request External System Response Listening Connector JOLT Request Application Server JOLT Response

PeopleSoft Target Connector

The scenario is simple: a request is sent into the gateway, which then passes it on to the app server. The app server processes the request, and returns a response.

Step 1 – Request is received by the Listening Connector
When a request is received by a Listening Connector, the first thing that the connector does is write the request to the gateway log file1. The request is written exactly as it is received. This is very useful in that it presents exactly what was seen on the wire, before the connector normalizes the message for use by the app server. The connector then attempts to populate an internal request message class with the particulars from the received message. A term often used in conjunction with Listening Connectors is “credentials”. Incoming requests are thought to have two logical parts: the credentials and the message body. The credentials can be thought of as the information required by the integration broker to process and deliver the payload of the message, which is found in the message body. Since the credentials are separate from the body, the gateway does not need to parse or otherwise examine the message body for information on how to route the message. A message without credentials cannot be processed. If the gateway receives such a message an error will occur and an error message will be returned to the requestor. Credentials are discussed in more detail in the section “Credentials” on page 12.

1

The gateway’s integration properties file is used to set the logging level, which controls what is actually written to the log. If messages are not being seen in the log file, check to ensure that the log level is set correctly.
© Copyright PeopleSoft Corporation 2001. All rights reserved.

8

4/10/2009

Step 2 – Request is processed by the PeopleSoftTarget Connector
In order for a message to be sent from the gateway to the application server, it must pass through the PeopleSoftTargetConnector. This connector has two major responsibilities: it serializes the message to a string, and sends that string via a JOLT connection to the app server. All communication between the gateway and the app server is done via the use of Multipurpose Internet Mail Extensions (MIME) messages. When the message is received by the connector, it builds a MIME message. Typically the MIME message will only have two sections. In the first, the message credentials are stored in an XML document in a specific format. The second section stores the message body. At this point the message is in a standard format understood by both the gateway and the application server. All messages must eventually resolve to this format before they can be sent to the app server for processing. This format effectively isolates the app server from the protocols supported by the gateway; there is no information present about what listening connector was initially invoked by the external request.2 Once the MIME message has been built, it is written to the gateway log. Finally, the connector looks up the JOLT connection properties from the integration properties file and attempts to send the MIME to the application server. If these properties are not set up correctly, the gateway will be unable to send requests. This is a common source of error, so care should be taken when configuring this file. An important point to keep in mind is that even though the MIME request to the appserver may appear in the gateway log file, the actual request may not have made it to the app server, since the log entry is written before the message is sent. If a communication error occurs, the entry will still be present in the log file. However, if this situation occurs an exception will be thrown and an error log entry will also be created.

Step 3 – Request is received by the Application Server
When the MIME request is received by the application server, the message is parsed and is used to build a request object. The MIME structure is not propagated into the server. Assuming the message parses without error, the application server must pre-process the message before the request can actually be handled. Pre-processing involves: • • authenticating the message, depending on the authentication scheme configured. If the request fails authentication, an error is returned. determining if there is a transaction corresponding to the request in the Node Transaction table. Aside from Ping messages, all incoming messages must resolve to a single, unique entry in this table. If a suitable transaction cannot be found for a request, an error occurs. determining the message handler to invoke. Currently, there are three message types supported by the integration broker: Ping, Synchronous, and Asynchronous. The message type determines the handler code to invoke. Synchronous messages are passed to sync-specific code, and async messages are passed to the publish/subscribe subsytem.

Once messages have been passed to their respective handlers, further processing is dictated by the data and PeopleCode specific to a particular system. Async requests will be published, and subscription PeopleCode will be

2

This is not entirely true. One credential element that may be present is the one for “Cookies”. Obviously if this is set, the app server would be right in assuming that the request came through the HTTP ListeningConnector. Similarly, SOAP requests are passed into the app server in SOAP format. However, as a general rule the app server is isolated from the details of the protocol and the general broker code on the server does not care what listening connector was used for a given request.
© Copyright PeopleSoft Corporation 2001. All rights reserved.

9

4/10/2009 executed. Synchronous messages may invoke PeopleCode, or in the case of Hub configurations the request may immediately be routed to another external system.

Step 4 – Response is returned by the Application Server
Regardless of how the request is processed, a response message must be returned by the app server to the gateway in the same thread of execution. The connection between the gateway and the app server is essentially synchronous, independent of the type of the message being exchanged. When the gateway sends a request to the app server, it expects and must get a response. In the case of synchronous messages, the generation of the response is blocked by the processing of the request. A response cannot be generated until the message runs to completion. There may be a noticable delay in receiving the response, depending if PeopleCode is being run or if the request message is being sent out of the broker to an external system for additional processing. Asynchronous requests behave differently. Unlike sync requests, there is no blocking. A response is generated for an asynchronous request as soon as the request is written to the publication queue. Because of this, a response generated for an asynchronous request is not a response in the strictest sense of the term. Such responses should really be considered acknowledgments that the pub/sub system has received the message. Receipt of such a response is not a guarantee that any applicable subscription PeopleCode has been successfully run. Response messages are converted to the MIME standard by the app server, and are returned to the gateway.

Step 5 – Response is received by the PeopleSoftTargetConnector
As soon as the MIME response is received by the PeopleSoftTargetConnector, it is written to the gateway log file. The MIME response is then parsed back into a gateway request object, and is then returned to the ListeningConnector.

Step 6 – Response is received by the ListeningConnector
The reponse object is returned to the ListeningConnector, upon which the response is mapped to a response suitable for the given protocol. It should be emphasized that, from the viewpoint of the ListeningConnector, the processing of request messages is done synchronously. A request is received by a ListeningConnector which then coverts it to a suitable format, makes a blocking call to the gateway to handle the message, and ultimately gets a response back all in the same thread of execution.

MESSAGE FLOW THROUGH THE BROKER; OUTGOING REQUEST
There are several scenarios that might result in a request message being sent out of the broker. Messages can be sent in PeopleCode by using the Publish or SendSync methods of the message class. If the broker is operated in a Hub configuration, incoming synchronous messages may be set up to be routed out to other systems. Regardless of how the message is created, the mechanism for sending the message out of the broker is the same. Additionally, this flow is also the same regardless of the specific outgoing Target Connector being invoked.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

10

4/10/2009

Integration Gateway HTTP Request Application Server HTTP Response Request Target Connector Response External System

PeopleSoft Listening Connector

Step 1 – Application Server generates request
Once an outgoing request message has been generated, the app server must do some basic processing before it can be sent out. The app server looks at the request, and extracts the information about the node that it is to be sent to. The node name is then used to look up the name of the gateway to use, the Target Connector to use on that gateway, as well as any specific connector properties that need to be passed to the connector in order to handle the request. If this information is not found, an error will occur. The app server modifies the outgoing request with the appropriate connector information. The request is then converted to the MIME standard format, and is sent to the gateway over an HTTP connection. The request must be sent to the PeopleSoftListeningConnector on the gateway. The app server uses the value of the “Gateway URL” defined for the given gateway. If this URL is not valid or does not point to the PeopleSoftListeningConnector, the app server will be unable to send the request.

Step 2 – Request is received by the PeopleSoftListeningConnector
When the MIME request is received by the PeopleSoftListeningConnector, it is written to the gateway log file. The request is converted from MIME format to a gateway request object. The connector then examines the request to determine what TargetConnector the request is to be sent to; that TargetConnector is then invoked.

Step 3 – Request is received by the Target Connector
The TargetConnector validates the request. Each connector requires certain properties to be set, otherwise the request cannot be sent. For example, the HTTPTargetConnector requires that the “PrimaryURL” be set. If any mandatory connector properties are missing or are invalid, an error will be thrown. The TargetConnector then converts the request message into whatever format is required by the protocol. The modified request is then written to the gateway log, and the request is sent out.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

11

4/10/2009

Step 4 – Response is received by the TargetConnector
The response received by the Target Connector is written to the gateway log, and the response is used to build a gateway response object, which is then returned to the PeopleSoftListeningConnector.

Step 5 – Response is received by the PeopleSoftListeningConnector
The response object is then converted to the MIME standard format by the connector. The MIME’d response is then written to the gateway log file, and is then returned to the app server. Again, it should be emphasized that interactions with the gateway are always synchronous. If a request is sent to the gateway, a response should be expected. Step 2 is an HTTP POST request made of the gateway, and the response created here in Step 5 is returned in the response to that HTTP request. The HTTP connection is open for the duration of the processing for that request.

Step 6 – Response is received by the Application Server
A response object is built out of the MIME response, and is returned to the routine that created the request.

REQUIREMENTS FOR INCOMING MESSAGES
Incoming request messages are considered to have two logical parts. The first, the credentials, is the portion of the request that will be consumed by the integration broker, and consists of information required by the broker to authenticate and route the message. The second part is the message body, and this is the payload of the message. This is the portion of the message that the broker is trying to deliver. The integration broker infrastucture does not need to understand the contents of the body in order to process the message.

Credentials
Messages sent into the Integration Broker must contain specific information in order to be processed. Messages received without such info will be rejected and will result in errors being thrown. Two elements are always required for all incoming requests: 1. Requesting Node – this is the name of the node sending the request to the local Integration Broker 2. Message Name – the name of the message being sent. This can also be an “external message” name. Without these elements, the broker will be unable to lookup the associated transaction in the system for the request. When such messages are received explicit error messages will be returned. Other elements may be also necessary, depending on circumstance. For example, if password authentication is being done for a specific requesting node, then the requests must also include this information as well. All requests must be able to be resolved to a single transaction in the node transaction table – PSNODETRX. Although this is not a requirement, it is advantageous for incoming messages to also specify the transaction type and the message version. If this information is not included, the integration broker must go to the transaction table and attempt to find a transaction that matches the requesting node and message name given in the request
© Copyright PeopleSoft Corporation 2001. All rights reserved.

12

4/10/2009 message. Care must be taken when setting up transactions to ensure that the incoming request messages will resolve correctly to a single transaction. If the request message explicitly includes the requesting node, message name, transaction type and version it is relatively easy for an administrator to verify as to whether a matching transaction exists in the system.

Message Body
The requirements for the message body depend on how the request is being used. As far as the infrastructure of the integration broker is concerned, the only requirements on the message body be that is is composed of text. Binary cannot be directly handled by the system. However a way around this is to encode the binary in a BASE64 string. Since such a string is simply composed of ASCII text, the string can be transported like any other text. In fact, this is commonly done in the system for asynchronous messages that are sent between two different PeopleSoft nodes. Such messages can be quite large, and it is desireable to make the message as small as possible to reduce strain on the system. Before the outgoing request is built, the pub/sub system takes the XML and compresses it. The result of this is a binary ZIP stream. This stream is then BASE64 encoded, and is added to the outgoing request. The receiving PeopleSoft system reverses the procedure: upon receipt of the message the message body is BASE64 decoded, unzipped, and the resulting XML is then processed. The BASE64 message bodies can be seen being transported across gateways by looking at the appropriate gateway logs. In reality arbitrary data encoded in the message body is really only a possibility when the integration broker is being used as a hub between two third party systems. If the eventual target of the request is a PeopleSoft system, there are further requirements on the content of the body.

PeopleSoft Requirements for Messages Bodies
If the ultimate target of the message is a PeopleSoft system, the message body must be XML, and must conform to a specific standard. The following is an example of that standard:

<?xml version='1.0'?> <EXAMPLE_REQUEST_MESSAGE> <FieldTypes> <EXAMPLE_ITEM class="R"> <EX_MANUFACTURER type="CHAR"/> <EX_MODEL type="CHAR"/> <EX_SKU type="CHAR"/> <EX_COST type="CHAR"/> </EXAMPLE_ITEM> <PSCAMA class="R"> <LANGUAGE_CD type="CHAR"/> <AUDIT_ACTN type="CHAR"/> <BASE_LANGUAGE_CD type="CHAR"/> <MSG_SEQ_FLG type="CHAR"/> <PROCESS_INSTANCE type="NUMBER"/> <PUBLISH_RULE_ID type="CHAR"/> <MSGNODENAME type="CHAR"/> </PSCAMA> </FieldTypes> <MsgData> <Transaction> <EXAMPLE_ITEM class="R"> <EX_MANUFACTURER>Ford</EX_MANUFACTURER> <EX_MODEL>Mustang GT Cobra</EX_MODEL> <EX_SKU>FRD23397GC</EX_SKU> <EX_COST>26459.90</EX_COST> </EXAMPLE_ITEM> <PSCAMA class="R"> <LANGUAGE_CD></LANGUAGE_CD> <AUDIT_ACTN></AUDIT_ACTN>

© Copyright PeopleSoft Corporation 2001. All rights reserved.

13

4/10/2009
<BASE_LANGUAGE_CD>ENG</BASE_LANGUAGE_CD> <MSG_SEQ_FLG></MSG_SEQ_FLG> <PROCESS_INSTANCE>0</PROCESS_INSTANCE> <PUBLISH_RULE_ID></PUBLISH_RULE_ID> <MSGNODENAME></MSGNODENAME> </PSCAMA> </Transaction> </MsgData> </EXAMPLE_REQUEST_MESSAGE>

The root node of the document is the name of the corresponding message in the message table, in this case the EXAMPLE_REQUEST_MESSAGE. Under the “FieldTypes” node, the next element is the name of the child record for this particular version of the message: EXAMPLE_ITEM. Under EXAMPLE_ITEM is a list of nodes that describe each field in the record. Under the “MsgData” and “Transaction” nodes is the actual data in the request. The next node is the name of the child record of the message, followed by the list of all the field names with concrete values for each. For further information about this standard, please refer to the Integration Broker PeopleBook.

INTEGRATION BROKER INTERNAL FORMAT FOR REQUEST MESSAGES
This section deals with the format used to exchange request messages between the gateway and the app server. Although this format is not directly useable by third party systems3, it is important to understand it for two reasons: 1) all incoming requests must eventually be able to be mapped into this format before they can be processed by the app server. 2) messages using the internal format will show up in the gateway log file. Since the log file is a valuable tool for debugging, anyone reading the file will need to understand how the messages are structured.

MIME
The Multipurpose Internet Mail Extension standard (MIME) is used as the basic structure for internal messaging. MIME has several advantages in that the standard is well known and supported, and because it is text based it is human readable and easily serializable. The following is an example of a request message in this internal format:

3

Unless they decide to integrate directly to the PeopleSoft Listening or Target Connectors. 14

© Copyright PeopleSoft Corporation 2001. All rights reserved.

4/10/2009

Message-ID: <5722340.1008266844175.JavaMail.MNowosel@MNOWOSEL071900> Date: Thu, 13 Dec 2001 10:07:24 -0800 (PST) Mime-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_5_7190308.1008266838787" Content-ID: PeopleSoft-Integration-Broker-Internal-Mime-Message ------=_Part_5_7190308.1008266838787 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Content-Disposition: inline Content-ID: IBInfo <?xml version="1.0"?><IBInfo><MessageName><![CDATA[EXAMPLE_REQUEST_MESSAGE]]></MessageName><MessageType>sync</MessageType> <From><RequestingNode><![CDATA[SOURCENODE]]></RequestingNode><OrigTimeStamp>2001-11-13T10:07:18.8170800</OrigTimeStamp></From><PathInfo><![CDATA[/PSIGW/PeopleSoftListeningConnector]]></PathInfo><ContentSections><ContentSection><I D>ContentSection0</ID><NonRepudiation>N</NonRepudiation></ContentSection></ContentSections></IBInfo> ------=_Part_5_7190308.1008266838787 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Content-Disposition: inline Content-ID: ContentSection0 <?xml version="1.0"?> <TestXml>This is a sample request message.</TestXml> ------=_Part_5_7190308.1008266838787—

Three distinct sections are visible in this message. The first part of the message contains the MIME headers, which describe the attributes of the whole message. Next is the IBInfo – or “Integration Broker Information” – section. The IBInfo contains the credentials of the request as well as all other information required by the broker to process the message. The IBInfo for a request has a specific XML structure which is used for all request messages in the system, regardless if the message is being sent to the app server or to the gateway. The final section contains the message body of the original request. This is the payload and is what ultimately will be delivered to the message’s final destination. This is the “Content Section”.

IBInfo XML
The following is an example of the IBInfo for a request message that was sent from the app server to the gateway (formatted for easier reading):

© Copyright PeopleSoft Corporation 2001. All rights reserved.

15

4/10/2009

<?xml version="1.0"?> <IBInfo> <MessageName><![CDATA[EXAMPLE_REQUEST_MESSAGE]]></MessageName> <MessageType>sync</MessageType> <TransactionID><![CDATA[]]></TransactionID> <From> <RequestingNode><![CDATA[QE_LOCAL]]></RequestingNode> <Password><![CDATA[]]></Password> <DN><![CDATA[]]></DN> <OrigUser><![CDATA[]]></OrigUser> <OrigNode><![CDATA[]]></OrigNode> <OrigProcess><![CDATA[]]></OrigProcess> <OrigTimeStamp>2001-11-13T11:06:22.142-0800</OrigTimeStamp> </From> <To> <DestinationNode><![CDATA[TARGETNODE]]></DestinationNode> <FinalDestinationNode><![CDATA[]]></FinalDestinationNode> </To> <QStrArgs/> <Cookies><![CDATA[]]></Cookies> <PathInfo><![CDATA[/PSIGW/PeopleSoftListeningConnector]]></PathInfo> <ContentSections> <ContentSection> <ID>ContentSection0</ID> <NonRepudiation>N</NonRepudiation> <Headers> <version><![CDATA[VERSION_1]]></version> </Headers> </ContentSection> </ContentSections> <InternalInfo> <AppMsg> <PublishingNode><![CDATA[]]></PublishingNode> <Channel><![CDATA[]]></Channel> <SubChannel><![CDATA[]]></SubChannel> <DefaultDataVersion>VERSION_1</DefaultDataVersion> <VisitedNodes><![CDATA[|QE_LOCAL|]]></VisitedNodes> <PublicationID></PublicationID> </AppMsg> </InternalInfo> <Connector> <ConnectorName><![CDATA[HTTPTARGET]]></ConnectorName> <ConnectorClassName><![CDATA[HttpTargetConnector]]></ConnectorClassName> <RemoteFrameworkURL><![CDATA[]]></RemoteFrameworkURL> <ConnectorParameters> <ConnectorParam> <Name><![CDATA[Method]]></Name> <Value><![CDATA[POST]]></Value> </ConnectorParam> <ConnectorParam> <Name><![CDATA[URL]]></Name> <Value><![CDATA[http://www.externalsystem.com/serlvet]]></Value> </ConnectorParam> </ConnectorParameters> <ConnectorHeaders> <Header> <Name><![CDATA[sendUncompressed]]></Name> <Value><![CDATA[Y]]></Value> </Header> </ConnectorHeaders> </Connector> </IBInfo>

While the basic structure is the same for all requests, not all elements are always required. An example of this is the “Connector” section. The Connector XML is used to tell the gateway to route this message to the named target connector. It also lists configuration parameters for the outbound request. This XML would only be seen in requests sent from the app server to the gateway. For requests going in the other direction, the section would be empty.
© Copyright PeopleSoft Corporation 2001. All rights reserved.

16

4/10/2009 The only elements that are always required is “MessageName” and “RequestingNode.” The following is a list of the most important elements that may appear in the IBInfo:

Element IBInfo / MessageName IBInfo / MessageType IBInfo / TransactionID IBInfo / From / RequestingNode IBInfo / From / Password IBInfo / From / DN

Description The name of the request message. This is a mandatory field. This is the type of the message. Currently, there are three types: async, sinc, and ping. The transaction id is used to uniquely identify a request. The requesting node is the node that sent the request to the current system. This is a mandatory field. This is the password for the requesting node. For incoming requests, the DN gives the Distinguished Name extracted from the certificate authentication process. For requests that cross multiple nodes, the OrigNode is used to identify the node that initiated the request. This timestamp corresponds to the time that the request was created. For requests that cross nodes, this is the time that the first request was created. This is the node that this request is to be delivered to. In cases where the message will be passed across several nodes, this value specifies the ultimate target of the message. Specific to incoming HTTP requests. These are the query string parameters found when the request was received by the HTTPListeningConnector. Specific to incoming HTTP requests. This is cookie string found when the request was received by the HTTPListeningConnector. Specific to incoming HTTP requests. This is the pathinfo extracted from the request. This node provides metadata about the text present in the ContentSection. The index number of the content section. Indicates as to whether NR should be performed. Provides additional information about the data. The node that published the message. The channel that the message was published to. 17

IBInfo / From / OrigNode IBInfo / From / OrigTimeStamp

IBInfo / To / DestinationNode IBInfo / To / FinalDestinationNode

IBInfo / QStrArgs

IBInfo / Cookies

IBInfo / PathInfo IBInfo / ContentSections / ContentSection IBInfo / ContentSections / ContentSection / ID IBInfo / ContentSections / ContentSection / NonRepudiation IBInfo / ContentSections / ContentSection / Headers IBInfo / InternalInfo / AppMsg / PublishingNode IBInfo / InternalInfo / AppMsg / Channel

© Copyright PeopleSoft Corporation 2001. All rights reserved.

4/10/2009 Element Description

IBInfo / InternalInfo / AppMsg / SubChannel IBInfo / InternalInfo / AppMsg / DefaultDataVersion IBInfo / InternalInfo / AppMsg / VisitedNodes

The subchannel that the message was published to. The default data version for this message on the node sending the message. The list of nodes that have already received this message. This is useful when a message is being propagated across multiple nodes. The publication id for this message. Connector information instructs the gateway as to how to process the request. This is the proper name of the target connector to invoke to send the message. This is the class name of the target connector to invoke. Connector parameters are processing instructions for the Target Connector to be invoked. Connector headers provide further metadata about the contents of the message to be sent.

IBInfo / InternalInfo / AppMsg / PublicationID IBInfo / Connector IBInfo / Connector / ConnectorName IBInfo / Connector / ConnectorClassName IBInfo / Connector / ConnectorParameters IBInfo / Connector / ConnectorHeaders

For a complete listing of the contents of the IBInfo, please refer to the Integration Broker PeopleBook.

Content Section
The content section for a request is text, subject to the limitations as discussed in section on messages bodies for incoming request messages.

INTEGRATION BROKER INTERNAL FORMAT FOR RESPONSE MESSAGES
The internal format for response messages parallels that for request messages.

MIME
Internal response messages have the same basic MIME structure as request messages. An example of a response message:

© Copyright PeopleSoft Corporation 2001. All rights reserved.

18

4/10/2009

Message-ID: <2351889.1008355101212.JavaMail.MNowosel@MNOWOSEL071900> Date: Fri, 14 Dec 2001 10:38:21 -0800 (PST) Mime-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_4_7210339.1008355101202" Content-ID: PeopleSoft-Integration-Broker-Internal-Mime-Message ------=_Part_4_7210339.1008355101202 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Content-Disposition: inline Content-ID: IBInfo <?xml version="1.0"?><IBInfo><Status><StatusCode>0</StatusCode><MsgSet>158</MsgSet><MsgID>10000</MsgID><DefaultTitle>Integration Broker Response Message</DefaultTitle></Status><ContentSections><ContentSection><ID>ContentSection0</ID><NonRepudiation>N</NonRepudiation></ContentS ection></ContentSections></IBInfo> ------=_Part_4_7210339.1008355101202 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Content-Disposition: inline Content-ID: ContentSection0 <?xml version="1.0"?> <TestXml>This is a sample response message.</TestXml> ------=_Part_4_7210339.1008355101202--

There are two logical components to a MIME response message: the IBInfo and the Content Section.

IBInfo XML
The format for the XML for the IBInfo for a response message is different than that for the request message. The following is a sample:

<?xml version="1.0"?> <IBInfo> <Status> <StatusCode>0</StatusCode> <MsgSet>158</MsgSet> <MsgID>10000</MsgID> <DefaultMsg>OK</DefaultMsg> <DefaultTitle>Integration Broker Response Message</DefaultTitle> </Status> <ContentSections> <ContentSection> <ID>ContentSection0</ID> <NonRepudiation>N</NonRepudiation> </ContentSection> </ContentSections> </IBInfo>

The following is the list of all the elements that may be present in the IBInfo for a response:

Element IBInfo / Status / StatusCode

Description Describes the result of the request. The status codes are:

© Copyright PeopleSoft Corporation 2001. All rights reserved.

19

4/10/2009 Element Description 0 – Request successfully processed. 10 – Temporary error occurred. Request can be resent. 20 – Fatal error occurred. Do not resend request. 30 – Request message is a duplicate of a message previously received. IBInfo / Status / MsgSet The MessageSetNumber for this message in the Message Catalog. 158 is the message set number assigned to the Integration Broker. The Message Number for this message in the Message Catalog. If no errors occurred during the processing of the request, the MsgID will be set to the value ‘10000’. Used if the message catalog is unavailable. This value corresponds to the “Message Text” for a given entry in the message catalog. Used if the message catalog is unavailable. This value corresponds to the “Explanation” for a given entry in the message catalog. Parameters may be used to provide additional information for error responses. A description of the content section returned with the response. Note: not all response messages will have a content section. The structure of the content section and all child elements is the same as was seen in the request IBInfo. Please refer to that section for more details.

IBInfo / Status / MsgID

IBInfo / Status / DefaultTitle

IBInfo / Status / DefaultMsg

IBInfo / Status / Parameters IBInfo / ContentSection

For further information, please refer to the Integration Broker PeopleBook.

Content Section
The content section for a request is text, subject to the limitations as discussed in section on message bodies for incoming request messages.

Error Codes and Message Catalog Entries
Response messages may contain data corresponding to processing of the request message received, or they may contain error information if there was a problem in fulfilling the request. The status code describes the nature of the response message. If anything other than “0” is present, an error has occurred. All integration broker error messages are stored in the message catalog. A short and long description for every error can be found there. Catalog entries are given a number, and this number is used in the response messages. Here is a sample error message: 20

© Copyright PeopleSoft Corporation 2001. All rights reserved.

4/10/2009

Message-ID: <4328049.1008270392287.JavaMail.MNowosel@MNOWOSEL071900> Date: Thu, 13 Dec 2001 11:06:32 -0800 (PST) Mime-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_25_2235074.1008270392277" Content-ID: PeopleSoft-Integration-Broker-Internal-Mime-Message ------=_Part_25_2235074.1008270392277 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Content-Disposition: inline Content-ID: IBInfo <?xml version="1.0"?><IBInfo><Status><StatusCode>10</StatusCode><MsgSet>158</MsgSet><MsgID>10721</MsgID><Parameters count="1"><Parm>404</Parm></Parameters><DefaultTitle>Integration Gateway Error</DefaultTitle></Status></IBInfo> ------=_Part_25_2235074.1008270392277--

All Integration Broker errors use message set 158. The actual error seen here is 10721. Going to the message catalog, the description for message set 158, error 10721 is:

Message Text: Integration Gateway - External System Contact Error Explanation: Integration Gateway was not able to contact the external system. The network location specified may be incorrect, or the site is permanently or temporarily down.

Therefore this error was created by the gateway when it tried to send a request message out to an external system.

MANIPULATING CONTENT SECTIONS VIA TRANSFORMS
The data in the content section of a message may not always be in an appropriate format for the task at hand. A message sent into the broker, intended for local processing, may not be in the format that PeopleSoft requires. A message being sent out of the broker may not match the format that the external system expects. A mechanism is provided to manipulate the data in content sections; these are called transforms. Transforms are implemented in the broker by means of the Extensible Stylesheet Language (XSL). A transform involves running an XSL stylesheet against the text in the content section, with the results of the transform replacing the original text. Because XSL is used, there is a restriction on the text in the content section to be transformed – it must be valid XML. If it is not, the transform will fail. XSL does allow for the creation of non XML documents however, so the output of the transform need not be XML. In order to use a transform, a relationship must be defined. Transforms are optional when creating a relationship, but relationships are the only way that transforms can be invoked. For a given relationship, one transform can be specified for the request message and a different transform for the response.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

21

4/10/2009 A separate RedPaper is available on the use of transforms in the integration broker. For further details, please refer to this document.

CHARACTER ENCODING CONSIDERATIONS
Several character encodings are used by the different components of the integration broker; however as far as third party integrations are concerned there really only is one scenario where encoding really may be a problem. Async and certain sync messages4 sent out of the broker will have the data in their content sections zipped and BASE64 encoded. This is done in order to reduce the overall size of such messages and reduce strain on the system. Zipping text reduces the overall size, but the output of the zipping is a binary stream. Since binary is sometimes difficult to transport, the stream is then BASE64 encoded. This results in a text stream that is larger in size than the binary stream, but is much smaller than the original text. However, because of this process, a character encoding issue arises. If the zipping and encoding were not done, and the data was just normal text inside of the message, encoding would not be an issue – it would be automatic. UCS2 is used within the app server, but when the message is sent to the gateway, the message would be converted to the particular flavour of UTF16 used by the Java Virtual Machine running on the gateway. If the request was being sent out via HTTP, the request might be converted to UTF8. In such cases, character encoding is handled at the boundaries of the various components automatically. However, when text is zipped and encoded this is no longer the case. Whatever encoding that the text was in when zipped, will be the encoding that the text will be in when it is unzipped. The application server will always encode text to be zipped in UTF8, so any consumers of the message must be able to handle this encoding. Conversely, if an external system is sending a request into the broker to be processed locally, and the message is zipped and BASE64 encoded, then the encoding of the characters must be UTF8, otherwise an error will occur. In certain situations, conversion to or from UTF8 may be a problem for third parties. There are ways around this. For messages being sent into the broker, simply do not zip and encode the message body. The broker is capable of handling messages either in “zipped and encoded” or “plain text” format. For messages being sent out of the broker, there exists a Gateway Connector configuration parameter called “sendUncompressed”. If this parameter is activated, the gateway will automatically decode and inflate all messages sent to a particular node. The external party will then receive normal, uncompressed text.

4

Sync messages whose total size is greater than a configurable value set on the application server. 22

© Copyright PeopleSoft Corporation 2001. All rights reserved.

4/10/2009

Chapter 3 –Integration Examples Using The Connectors
In this chapter, concrete examples will be given for using the various connectors present on the gateway. All the examples assume that the integration broker and gateway have been installed correctly. This includes that the appropriate application servers have been configured and are running. For information on how to install the basic components, refer to the Integration Broker PeopleBook.

BASIC SETUP FOR THE EXAMPLES
The following setup must be done before any of the examples are attempted. This only needs to be done once. The setup involves defining two nodes. The SOURCENODE is considered to be the system sending messages into the broker. The broker sends outgoing messages to the TARGETNODE. Only one request message is defined for the examples: EXAMPLE_REQUEST_MESSAGE. This is an unstructured message. The response to the request is EXAMPLE_RESPONSE_MESSAGE. These messages will be used both for incoming and outgoing requests and responses. For the examples all requests are made synchronously, and the transactions set up reflect this. This is done for simplicity and to ensure consistency. The only thing to be aware of is that the final step sets up a relationship between the SOURCENODE and TARGETNODES. For examples where OnRequest PeopleCode is run, this relationship should be inactive. For examples where the broker is used as a hub, the relationship should be active. If examples are not working correctly, the status of this relationship is one of the first things that should be checked.

Add a Message Channel
Invoke the Application Designer. • • • select “File”->”New” a message box titled “New Definition” will appear. Choose “Message Channel” and click “Ok”. select “File”->”Save As..” Enter “EXAMPLE_CHANNEL” in the message box and click “Ok”.

Add a Request Message
From within the Application Designer: • • • select “File”->”New” a message box titled “New Definition” will appear. Choose “Message” and click “Ok.” select “File”->”Definition Properties”. A message box titled “Message Properties” will appear. • click on the “Use” tab.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

23

4/10/2009 • • on the “Message Channel” drop down, select EXAMPLE_CHANNEL and click “Ok.

select “File”->”Save as…”. Enter EXAMPLE_REQUEST_MESSAGE in the message box and click “Ok.”

Add a Response Message
From within the Application Designer: • • • select “File”->”New” a message box titled “New Definition” will appear. Choose “Message” and click “Ok.” select “File”->”Definition Properties”. A message box titled “Message Properties” will appear. • • • click on the “Use” tab. on the “Message Channel” drop down, select EXAMPLE_CHANNEL and click “Ok.

select “File”->”Save as…”. Enter EXAMPLE_RESPONSE_MESSAGE in the message box and click “Ok.”

Add the Source Node
From PIA : • • • Click on “Integration Broker” Click on “Node Definitions” Click the tab “Add a new value” • • • Type in “SourceNode” in the “Node Name” field Click the “Add” button

A page should appear displaying the “Node Info” • • • Type “The source node” in the “Description” field Ensure that the “Authentication Option” is set to “None” Click the “Save” button

Add the Target Node
From PIA: • Click on “Integration Broker” 24

© Copyright PeopleSoft Corporation 2001. All rights reserved.

4/10/2009 • • Click on “Node Definitions” Click the tab “Add a new value” • • • Type in “TargetNode” in the “Node Name” field Click the “Add” button

A page should appear displaying the “Node Info” • • Type “The target node” in the “Description” field Click the “Save” button

Add the Source Transaction
From PIA: • • • • • • Click on “Integration Broker”. Click on “Node Definition”. In the right frame, click on “Search”. A list of the available nodes will appear. Click on “SOURCENODE”. The “Node Info” page will appear. Click on the “Transactions” tab. All the existing transactions for the node will be displayed. Click on the “Add Transaction” button. • • • • • • On the resulting page, the node and the effective date will be filled out. There is no need to change these values. Select “Inbound Synchronous” as the “Transaction Type”. Type in “EXAMPLE_REQUEST_MESSAGE” in the “Request Message” field. Type in “VERSION_1” in the “Version” field. Click the “Add” button.

The “Transaction Detail” page will appear. Ensure that the “Status” is set to “Active”. Click on the “Messages” tab. • In the “Response Message” section: • • • Type “EXAMPLE_RESPONSE_MESSAGE” in the “Name” field. Type “VERSION_1” in the “Version” field.

Click on the “Save” button.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

25

4/10/2009

Add the Target Transaction
From PIA: • • • • • • Click on “Integration Broker”. Click on “Node Definition”. In the right frame, click on “Search”. A list of the available nodes will appear. Click on “TARGETNODE”. The “Node Info” page will appear. Click on the “Transactions” tab. All the existing transactions for the node will be displayed. Click on the “Add Transaction” button. • • • • • • On the resulting page, the node and the effective date will be filled out. There is no need to change these values. Select “Outbound Synchronous” as the “Transaction Type”. Type in “EXAMPLE_REQUEST_MESSAGE” in the “Request Message” field. Type in “VERSION_1” in the “Version” field. Click the “Add” button.

The “Transaction Detail” page will appear. Ensure that the “Status” is set to “Active”. Click on the “Messages” tab. • In the “Response Message” section: • • Type “EXAMPLE_RESPONSE_MESSAGE” in the “Name” field. Type “VERSION_1” in the “Version” field.

Click on the “Save” button.

Add the Relationship and Transaction Modifier
From PIA: • • • • • Click on “Integration Broker”. Click on “Relationships”. The “Relationships” page will appear in the right frame of the browser. In the right frame, click on the “Add a new value” tab. Type in “EXAMPLE_RELATIONSHIP” in the “Relationship ID” field. Click on the “Add” button. • On the resulting page: 26

© Copyright PeopleSoft Corporation 2001. All rights reserved.

4/10/2009 • • • • • • • Type in “An example relationship” in the “Description” field. Set the “Relationship Status” to “Active”. In the first “Node Name” field, type in “SOURCENODE”. In the second “Node Name” field, type in “TARGETNODE”. Click on the “Save” button.

Click on the “Trans Modifier” tab. A list of all the Transaction Modifiers for this relationship will be displayed. At this point, there shouldn’t be any. Click on the “Add Transaction Modifier” button. • The “Relationship Transactions” page will appear. • • • • • • • • • The “Relationship ID” and the “Effective date” fields will be filled out. These values shouldn’t be changed. Type “SOURCENODE” in the “Initial Node” field. Type “IS” in the “Transaction Type” field. Type “EXAMPLE_REQUEST_MESSAGE” in the “Request Message Name” field. Type “VERSION_1” in the “Source Request Message Version” field. Type “TARGETNODE” in the “Result Node” field. Type “EXAMPLE_REQUEST_MESSAGE” in the “Request Message Name” field. Type “VERSION_1” in the “Target Request Message Version” field. Click on the “Save” button.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

27

4/10/2009

INTEGRATING USING HTTP
The HyperText Transport Protocol (HTTP) is the basis of most communication on the internet. The integration broker has two connectors to handle HTTP. The HTTPListeningConnector is used to receive HTTP requests, and the HTTPTargetConnector is used to send them.

HTTP Message Credentials
“Message credentials” is the term used to group the information present in an HTTP request message that is used by the gateway to process the message. The list of HTTP message credentials is:

Name: From Password MessageName MessageType MessageVersion To FinalDestination OrigUser OrigNode OrigTimeStamp NonRepudiation

Description: The name of the node making the request. The requesting node’s password. The name of the message. The message type. Can be one of Sync, Async, Ping. The message version. The node that the request is being sent to. The ultimate final destination for the request. The user that originated the request. The node that originated the request. A timestamp corresponding to when the message was first created. Indicates as to whether NR should be run for this request. Acceptable values are “Y” or “N”

Two elements must be in every request: the Requesting Node and the Message name. These correspond to the HTTP message credential elements “From” and “MessageName”. Other elements may be required depending on circumstance. In the examples in this section, only a subset of these credentials will be used in order to make the examples more concise.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

28

4/10/2009

Sending HTTP requests to the Integration Broker
HTTP requests sent into the gateway are processed by the HttpListeningConnector servlet. There are three ways of sending HTTP requests into the listening connector. They are differentiated by the mechanisms used to pass the credentials to the gateway. 1. message credentials in the HTTP query string 2. message credentials in the HTTP headers 3. message credentials in the body of the posted request As far as the gateway is concerned, these are all functionally equivalent. The one to use is determined by the specific details of the integration being done – use whatever provides the best fit for the problem at hand. No special setup needs to be done to enable any of these three methods. The HttpListeningConnector is able to handle request messages using any of these mechanisms at any time.

Message Credentials in the H T TP query string
Credentials can be sent to the gateway as name-value pairs as part of the query string for the URL. For example: http://<your_hostname>/PSIGW/HttpListeningConnector?From=sourceNode&Password=thePassword&MessageN ame=ExampleRequestMessage&MessageType=sync&MessageVersion=VERSION_1 The request message itself is sent in the body of the POST. There is no requirement that the name-value pairs be presented in any specific order; as long as all the necessary credentials are present, the request will be processed.

Message Credentials in the H T TP headers
In this scenario, the credentials are being set as name-value pairs on the headers on the HTTP request. The text in the body of the POST is the message to be processed. The URL to post to is http://<your_hostname>/PSIGW/HttpListeningConnector A mechanism must be available to put the credentials in the HTTP headers. Probably the most common way to do this is programmatically, via an API. Code can be written to build the request, set the headers, and then make the HTTP request to the gateway. PeopleSoft’s SendMaster utility can also be used to test this functionality. SendMaster allows header values to be set via the “Header” section in the Project Definitions as a name-value pair.

Message Credentials in the body of the H T TP POS T
Credentials can also be sent in the body of the HTTP POST. Unlike the other two methods, this requires that the contents of the POST be XML in a specific format.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

29

4/10/2009 The format is:

<?xml version=”1.0”?> <IBRequest> <MessageName/> <MessageType/> <From> <RequestingNode/> <Password/> <OrigUser/> <OrigNode/> <OrigProcess/> <OrigTimeStamp/> </From> <To> <FinalDestination/> <DestinationNode/> </To> <ContentSections> <ContentSection> <NonRepudiation/> <Data><![CDATA[]]></Data> </ContentSection> </ContentSections> </IBRequest> The elements in the XML correspond to the credentials previously discussed. One item to note is that the message is part of the ContentSection/Data element, and that the message text must be enclosed in a CDATA section. This allows a complete XML document – or simple text that may contain XML reserved characters – to be included without invalidating the IBRequest XML.

Response to the H T TP Request
Regardless of the mechanism used to make the HTTP request, the response is always the same. It will be formatted according to the broker internal format for responses.

Example
In this example, a synchronous request message will be sent into the broker. This request will invoke PeopleCode, which will generate and return a simple response. Message credentials will be sent in the body of the HTTP POST. This example assumes that the application server and the gateway have both been configured correctly and are running. Example Specific Setup 1) Start up the Application Designer. 2) Choose “File”->”Open”->”Message” and select the EXAMPLE_REQUEST_MESSAGE. 3) Right-click on the VERSION_1 version of the message, and select “View PeopleCode”. 4) Select the “OnRequest” event, and put the following code into the window:
© Copyright PeopleSoft Corporation 2001. All rights reserved.

30

4/10/2009

Local Message &request, &response; &request = GetMessage(); REM – Now we could manipulate the request message. However in this case; REM – we’ll skip that and just generate a simple response and return it.; &response = CreateMessage(Message.EXAMPLE_RESPONSE_MESSAGE); ReturnToServer(&response);

5) Save the changed message. 6) Start up a web browser and access the PIA page for the Integration Broker. 7) Select “Relationships” 8) Choose the EXAMPLE_RELATIONSHIP, and click on the “TRANS MODIFIERS” tab. 9) Click the “Edit” button for the transaction modifer. 10) On the resulting page, set the Status of the modifier to “Inactive”, and click “Save”. 11) Clear the message and error log files on the gateway. Running the example 1) Start up SendMaster. • • Create a new project. Enter the appropriate Server URL for your gateway. For a system where the gateway is running on the same computer as SendMaster, the URL may look like: http://127.0.0.1/PSIGW/HttpListeningConnector • • Set the Project Type to “Input File” Put the following text into the text area in the Input Information section. <?xml version=”1.0”?> <IBRequest> <MessageName>EXAMPLE_REQUEST_MESSAGE</MessageName> <MessageType>sync</MessageType> <From> <RequestingNode>SOURCENODE</RequestingNode> </From> <To> <DestinationNode>putYourLocalNodeNameHere</DestinationNode> </To> <ContentSections> <ContentSection> <NonRepudiation/> <Data><![CDATA[This is the body of the request.]]></Data> </ContentSection>

© Copyright PeopleSoft Corporation 2001. All rights reserved.

31

4/10/2009 </ContentSections> </IBRequest>

• •

Click the POST button to send the request to the broker. After a brief delay, a response looking like the following will be returned to SendMaster:

NEED CAPTURED RESPONSE HERE !

2) Check the gateway message log to see the messages exchanged between the gateway and the application server.

HTTP requests from the Integration Broker to external systems
HTTP Requests can be sent out of the broker using the HttpTargetConnector on the gateway. Unlike HTTP Requests coming into the broker, there are no requirements on the format of requests being sent out. There is no fixed structure to follow, and there is no need to propagate message credentials out of the system.5

Configuring Outgoing Requests
While the HttpTargetConnector does not require the HTTP to be made in any specific manner, the system that the request is to be sent to may. The particulars of the HTTP request are controlled by the Connector properties set up for the target node. Some of the properties must be set in order to make an outgoing request. They are:

Property HTTPPROPERTY;Method PRIMARYURL; URL

Description This is the type of HTTP request being made. Values are GET or POST. This is the target for the request. Example: http://www.someserver.com Note: An IP address can be used in place of the fully qualified domain name.

5

Message credentials in the outgoing HTTP request would only theorectically be needed if the message was being sent to an HTTP Listening connector on a gateway belonging to another integration broker. However, this configuration is not recommended. If you want to send messages between two brokers, use the PeopleSoftListening and PeopleSoftTarget connectors instead.
© Copyright PeopleSoft Corporation 2001. All rights reserved.

32

4/10/2009 Property Description http://127.0.0.1 HEADER; sendUncompressed In some cases, the contents of the POST will be compressed and encoded via BASE64. If the contents of the POST should not be sent out compressed or encoded, set the value of this parameter to “N”.

Additionally, the HttpTargetConnector allows for standard HTTP header name-value pairs to be set. Headers such as “User-Agent” and “Content-Type” can be set to fixed values for a given node. The complete list of allowable headers is quite extensive. Please refer to the Integration Broker PeopleBook for details.

Contents of the Outgoing Request
In the case of HTTP POSTs, the data that will be posted is the text in the content section of the MIME message sent to the gateway. Unless instructed to uncompress any compressed data in the section, the gateway will simply take the text and will send it out with no modifications.

Response to the H T TP Request
Assuming that the HTTP Request was successfully received and handled by the target destination, a response will be returned to the HttpListeningConnector. The connector will then build an IB internal response message and will add the text returned to the content section of this message. The message will be returned back to the application server. However, if the HTTP Request was not successfully processed by the target – and the HTTP status code returned is other than 200 – the connector will build an IB internal error response message, and will return this back to the application server. Any text returned in conjunction with an error will not be included in this response message, but will be visible in the message log. If the connector is unable to send the request to the target destination due to a bad URL or the target server being down, an IB internal error message will be created with the appropriate error code and this will be propagated back to the application server.

Example
This example builds on the scenario used for the listening connector. Instead of the target of the message being PeopleCode on the application server, the incoming sync message will be routed out of the app server back to the gateway, where it will be posted to a third party web server. In addition, the post to the external server will be done in a way so as to cause a processing error to occur on the third party system. This will show how error messages are created and propagated back through the broker. Example Specific Setup 1) Start up a web browser and log into PIA. Select the Integration Broker menu item. 2) Select the “Node Definitions” menu item. Type in “TargetNode” in the search box and click the “Search” button. 3) Select the “Connectors” tab. • Ensure that the gateway ID for the node is set to the name of gateway you wish to use.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

33

4/10/2009 • • • • Select “HTTPTARGET” as the connector ID for this node. Hit the “Save” button. The HTTPPROPERTY;Method should be set to “POST”. Enter http://www.yahoo.com for PRIMARYURL;URL. Hit the “Save” button.

4) Clear the message and error log files on the gateway.

Running the example 1) Start up SendMaster. • • Create a new project. Enter the appropriate Server URL for your gateway. For a system where the gateway is running on the same computer as SendMaster, the URL may look like: http://127.0.0.1/PSIGW/HttpListeningConnector • • Set the Project Type to “Input File” Put the following text into the text area in the Input Information section. <?xml version=”1.0”?> <IBRequest> <MessageName>EXAMPLE_REQUEST_MESSAGE</MessageName> <MessageType>sync</MessageType> <From> <RequestingNode>SOURCENODE</RequestingNode> </From> <To> <DestinationNode>putYourLocalNodeNameHere</DestinationNode> </To> <ContentSections> <ContentSection> <NonRepudiation/> <Data><![CDATA[This is the body of the request.]]></Data> </ContentSection> </ContentSections> </IBRequest>

Click the POST button to send the request to the broker. The request will be sent to the gateway, which will forward it on to the application server, who will then forward it back out to the gateway. The gateway will attempt to POST the data ( which in this case is the string “This is the body of the request” ) to the server specified by the URL. Since this POST is meaningless to Yahoo’s server, it will return an error back to the gateway, which will then propagate back through the system. After a brief delay, a response looking like the following will be returned to SendMaster: <?xml version="1.0"?> <IBResponse type="error"> <DefaultTitle>Integration Broker Response</DefaultTitle>

© Copyright PeopleSoft Corporation 2001. All rights reserved.

34

4/10/2009 <StatusCode>10</StatusCode> <MessageID>10722</MessageID> <DefaultMessage>OK</DefaultMessage> <MessageParameters> <Parameter>501</Parameter> </MessageParameters> </IBResponse>

From this message we can see that the status code is 10, and this shows that an error occurred. A message id of 10722 was also returned. According to the integration broker message set, 10722 is: Integration Gateway - External System Contact Error Integration Gateway experienced an error while contacting the external system. HTTP Status Code: %1

2) Check the gateway message log to see the messages exchanged between the gateway, application server, and the external system. Take note of the message sent out by the HttpTargetConnector and the response it receives back.

HTTP Cookies
If a cookie is present in an incoming HTTP request received by the HttpListeningConnector, the cookie string will be captured and stored in the message sent to the application server. Once at the server, the cookie can be accessed in PeopleCode by using the Cookies function of the Message class. Cookies can also be set in PeopleCode. Please refer to the PeopleCode PeopleBook for more details. If any cookie information is present on a message that is to be sent out by the HttpTargetConnector, the cookie string will be set on the outgoing HTTP request. Please note that while cookie information could be set in PeopleCode on a message that will ultimately use a target connector other than HTTP, the cookie information would be discarded by the connector. Setting and getting cookies are only valid for HTTP requests.

SSL Considerations
In cases where sensitive information is sent over HTTP, it may be necessary to enable SSL encryption. The gateway fully supports HTTPS. In order to use SSL, digital certificates will have to be installed on the web server running the gateway. Once this is done, the gateway will be able to send and receive HTTPS requests. Receiving HTTPS requests is pretty much automatic. When the web server gets such a request, it will be forwarded on to the gateway for processing. Enabling outgoing HTTPS is not much more complex. Simply define the value for PRIMARYURL;URL to start with https:// instead of http://. The HttpTargetConnector will then make the necessary SSL connection at runtime.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

35

4/10/2009

INTEGRATING USING SOAP
Simple Object Access Protocol (SOAP) is an XML based protocol intended for the exchange of structured information in a distributed environment. SOAP is protocol independent, however the integration broker only supports SOAP over HTTP. There are no specific gateway connectors for SOAP. Instead, the HTTP listening and target connectors are used to receive and send SOAP messages.

Sending SOAP requests to the Integration Broker
SOAP requests are handled by the HTTPListeningConnector. No special configuration of the connector is required to receive such messages.

Requirements on SOAP Requests
All incoming SOAP requests must have a SOAP action header following the format below: SOAPAction: #MessageName#RequestingNode#Password The entries are fairly self-evident. MessageName is the name of the incoming message. RequestingNode is the name of the requesting node, and password is the password for that node on the local application server. MessageName and RequestingNode are mandatory elements; they must always be present in the SOAP header. The password is optional. Addtionally, the XML in the body of the HTTP POST must also follow a specific format:

<?xml version="1.0"?> <SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlSOAP.org/soap/encoding/" xmlns:SOAPENV="http://schemas.xmlSOAP.org/soap/envelope/"> <SOAP-ENV:Body> …include XML request here… </SOAP-ENV:Body> </SOAP-ENV:Envelope>

If the SOAPAction header is missing, then the broker will attempt to process the body of the message as a normal HTTP XML request. This will result in an error being thrown. The resulting error will not be a SOAP specific error. This should be emphasized: if the broker is unable to recognize the request as a SOAP request and an error occurs, a standard HTTP error response will be generated – not a SOAP specific one! If the SOAPAction header is present, but there is a problem with the formatting of the XML in the body of the POST, an error will be thrown. This error will be formatted for SOAP.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

36

4/10/2009

SOAP Response Structure
The integration broker returns SOAP response messages in a fixed format:

<?xml version="1.0"?> <SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> ...response XML will be included here... </SOAP-ENV:Body> </SOAP-ENV:Envelope>

The actual response to the request will be contained in the <SOAP-ENV:Body> element.

SOAP Error Response Structure
The format for SOAP error responses differs slightly from normal SOAP responses:

<?xml version='1.0' ?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode></faultcode> <faultstring></faultstring> <detail> </detail> </SOAP-ENV:Fault> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Note the presence of the <SOAP-ENV:Fault> element. This contains a fault code and a short description of the error. The “detail” element will contain the XML particular to the error.

Example Of Use
In this example, a SOAP request will be sent into the integration broker, where it will be processed by PeopleCode. The PeopleCode will build a SOAP response message, and this will be returned to the requestor. Example Specific Setup

1) Start up a web browser and access the PIA page for the Integration Broker. • Select “Relationships”.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

37

4/10/2009 • • • Choose the EXAMPLE_RELATIONSHIP, and click on the “TRANS MODIFIERS” tab. Click the “Edit” button for the transaction modifer. On the resulting page, set the Status of the modifier to “Inactive”, and click “Save”.

2) Open the Application Designer. • • • • • Select File->Open from the menu. In the pop up window, select “Messages” and click “Open” Select the “EXAMPLE_REQUEST_MESSAGE” Right click on VERSION_1 of the message, and select “View PeopleCode” Select the “OnRequest” event, and paste the following code into the window:

Local XmlDoc &request, &response; Local string &strXml; Local SOAPDoc &soapRequest, &soapResponse; &soapRequest = CreateSOAPDoc(); &request = GetMessageXmlDoc(); &soapRequest.XmlDoc = &request; &ok = &soapRequest.ValidateSOAPDoc(); &parmN = &soapRequest.GetParmName(1); &parmV = &soapRequest.GetParmValue(1); &soapResponse = CreateSOAPDoc(); If (&parmV = "PSFT") Then &soapResponse.AddMethod("StockQuoteResponse", 1); &soapResponse.AddParm("symbol", "PSFT"); &soapResponse.AddParm("price", "278.37"); Else &soapResponse.AddFault("100", "Can not find stock price"); End-If; &ok = &soapResponse.ValidateSOAPDoc(); &response = &soapResponse.XmlDoc; ReturnToServer(&response);

Save the code. This code will take parse the incoming message, looking for “PSFT” in the XML in the body of the SOAP request. If this is found, a SOAP response is returned with a stock quote. If not found, an error message is returned. 3) Clear the message and error log files on the gateway.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

38

4/10/2009 Running the Example 1) Start up SendMaster. • • Create a new project. Enter the appropriate Server URL for your gateway. For a system where the gateway is running on the same computer as SendMaster, the URL may look like: http://127.0.0.1/PSIGW/HttpListeningConnector • • Set the Project Type to “Input File” Put the following in the Headers section: SOAPAction: #EXAMPLE_REQUEST_MESSAGE#SOURCENODE • Put the following text into the text area in the Input Information section:

<?xml version="1.0"?> <SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlSOAP.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlSOAP.org/soap/envelope/"> <SOAP-ENV:Body> <GetQuote> <Symbol>PSFT</Symbol> </GetQuote> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

• •

Click the POST button to send the request to the broker. The request will be sent to the gateway, which will forward it on to the application server, where the PeopleCode will be run. Once the PeopleCode has run successfully, a response will be returned. The response will look like:

<?xml version="1.0"?> <SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAPENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <StockQuoteResponse> <symbol>PSFT</symbol> <price>278.37</price> </StockQuoteResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

2) Check the gateway message log to see the messages exchanged between the gateway and the application server. To see an example of a SOAP error message, change the value for “Symbol” in the input XML to a value other than “PSFT”. The PeopleCode will build and return an error message when the request is received.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

39

4/10/2009

SOAP requests out of the Integration Broker
SOAP Connector Properties
There are no SOAP specific connector properties. Outgoing SOAP requests use the HTTPTargetConnector.

Example of Use
In this example, an incoming SOAP request is sent into the integration broker. The broker is configured to relay the SOAP request out to an external site. However, the external site does not understand the SOAP request, and an error response is returned. Example Specific Setup 1) Start up a web browser and log into PIA. Select the Integration Broker menu item. 2) Select the “Node Definitions” menu item. Type in “TargetNode” in the search box and click the “Search” button. 3) Select the “Connectors” tab. • • • • • Ensure that the gateway ID for the node is set to the name of gateway you wish to use. Select “HTTPTARGET” as the connector ID for this node. Hit the “Save” button. The HTTPPROPERTY;Method should be set to “POST”. Enter http://www.yahoo.com for PRIMARYURL;URL. Hit the “Save” button.

4) Clear the message and error log files on the gateway. Running the example 1) Start up SendMaster. • • Create a new project. Enter the appropriate Server URL for your gateway. For a system where the gateway is running on the same computer as SendMaster, the URL may look like: http://127.0.0.1/PSIGW/HttpListeningConnector • • Set the Project Type to “Input File” Put the following in the Headers section: SOAPAction: #EXAMPLE_REQUEST_MESSAGE#SOURCENODE • Put the following text into the text area in the Input Information section:

<?xml version="1.0"?>
© Copyright PeopleSoft Corporation 2001. All rights reserved.

40

4/10/2009 <SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlSOAP.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlSOAP.org/soap/envelope/"> <SOAP-ENV:Body> <GetQuote> <Symbol>PSFT</Symbol> </GetQuote> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Click the POST button to send the request to the broker. The request will be sent to the gateway, which will forward it on to the application server. The application server will then send the SOAP request on to the external party specified. However, the external party does not understand the request, and an error message is eventually returned to SendMaster:

<?xml version='1.0' ?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode>SOAP-ENV:Server</faultcode> <faultstring>Server Error</faultstring> <detail> <IBResponse type="error"> <DefaultTitle>Integration Broker Response</DefaultTitle> <StatusCode>10</StatusCode> <MessageID>10721</MessageID> <DefaultMessage>OK</DefaultMessage> <MessageParameters> <Parameter>501</Parameter> </MessageParameters> </IBResponse> </detail> </SOAP-ENV:Fault> </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

If www.yahoo.com had understood the request, their response would have been returned to SendMaster. 3) Check the gateway message log to see the messages exchanged between the gateway, the application server, and the target server.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

41

4/10/2009

INTEGRATING USING FTP
File Transfer Protocol (FTP) is a protocol that was designed to allow the transfer of files between remote systems. A single connector is provided for use with FTP. The FTPTargetConnector allows requests to be made out of the Integration Broker to external FTP servers. Messages are transferred to the servers via an FTP PUT; this allows data to be sent to the destination server. The connector does not support FTP GETs, and therefore does not allow files to be downloaded from remote FTP servers to the gateway. The FTP connector cannot be used to transfer arbitrary files. The text in the content section of the message is what will be sent to the target FTP server. There is no FTPListeningConnector. External systems cannot initiate FTP requests to the gateway.

FTP requests from the Integration Broker to external systems
F TP Connector Properties
There are several connector properties used for outgoing FTP requests:

Property Name HOSTNAME

Description The name of the external FTP to connect to. The format of this can either be the fully qualified domain name (eg ftpserver.company.com) or the IP address (eg 207.123.132.43). This is a mandatory property. This is the username for the account on the remote FTP server. This is a mandatory property. This is the password for the account on the remote FTP server. This is a mandatory property. This is the filename that the message is to be saved as on the FTP server. This is optional. If no name is specified, a system generated name will be used. The format of the system generated filename is: the the the the Originating Node + "_" + Originating User + "_" + Message Name + "_" + Originating Timestamp + ".ftp"

USERNAME PASSWORD FILENAME

DIRECTORY

This is the directory name on the FTP server that the message is to be saved in. This is an optional property. If nothing is specified, then the server’s default directory will be used. Y/N – determines if the message is to be uncompressed before being sent out. ( see section xxx for more details ) This is an optional property.

sendUncompressed

© Copyright PeopleSoft Corporation 2001. All rights reserved.

42

4/10/2009

There is no way to specify the FTP port number. The FTPTargetConnector will only connect to FTP servers using the default FTP control port number (21). A username and password must always be specified. Some FTP servers allow anonymous access; for such servers use “anonymous” for the USERNAME and an email address as the PASSWORD.

Response to the F TP Request
If the file is successfully transferred to the FTP server, a response message will be returned by the gateway. The message will only contain IBInfo header information; there will not be a content section in the message. If an error occurs, an error response message will be returned.

Example
SendMaster will be used to send a sync message into the broker. The broker will be configured so that the incoming message will be routed to the FTPTargetConnector, which will then attempt to send the body of the message to an FTP server. Note: a user account on a running FTP server will be needed for this example. Example Specific Setup 1) Start up a web browser and log into PIA. Select the Integration Broker menu item. 2) Select the “Node Definitions” menu item. Type in “TargetNode” in the search box and click the “Search” button. 3) Select the “Connectors” tab. • • • • • • Ensure that the gateway ID for the node is set to the name of gateway you wish to use. Select “FTPTARGET” as the connector ID for this node. Hit the “Save” button. Set FTPTARGET; HOSTNAME to the address of the FTP server Set FTPTARGET;USERNAME to a valid userid on that server Set FTPTARGET; PASSWORD to the password corresponding to the userid Hit the “Save” button.

4) Clear the message and error log files on the gateway. Running the example 2) Start up SendMaster. • • Create a new project. Enter the appropriate Server URL for your gateway. For a system where the gateway is running on the same computer as SendMaster, the URL may look like: http://127.0.0.1/PSIGW/HttpListeningConnector • Set the Project Type to “Input File”

© Copyright PeopleSoft Corporation 2001. All rights reserved.

43

4/10/2009 • Put the following text into the text area in the Input Information section. <?xml version=”1.0”?> <IBRequest> <MessageName>EXAMPLE_REQUEST_MESSAGE</MessageName> <MessageType>sync</MessageType> <From> <RequestingNode>SOURCENODE</RequestingNode> </From> <To> <DestinationNode>putYourLocalNodeNameHere</DestinationNode> </To> <ContentSections> <ContentSection> <NonRepudiation/> <Data><![CDATA[This is the body of the request.]]></Data> </ContentSection> </ContentSections> </IBRequest>

Click the POST button to send the request to the broker. The request will be sent to the gateway, which will forward it on to the application server, who will then forward it back out to the gateway. The gateway will attempt to PUT the data ( which in this case is the string “This is the body of the request” ) on the FTP server. Once the transfer has occurred, a response message will be generated and sent back to SendMaster. Since there is no information in the body of the message, the output information area will not have any text in it.

3) Check the gateway message log to see the messages exchanged between the gateway, application server, and the FTP server. Specific log entries will be seen for the FTP connector showing that the data was sent successfully. 4) Check the FTP server for the presence of the file. The contents of the file should read “This is the body of the request.”

© Copyright PeopleSoft Corporation 2001. All rights reserved.

44

4/10/2009

INTEGRATING USING JMS
The Java Message Service is part of the Java 2 Enterprise Edition specification. It provides a Java API for asynchronous enterprise messaging. The Integration Broker has two connectors for use with JMS. The JMSTargetConnector provides the ability for the broker to publish messages to JMS topics and queues, whereas the JMSListeningConnector provides the ability to read published messages. While JMS defines an interface, an actual runtime implementation is required in order to use it. The integration broker can be used with three JMS providers: BEA’s Weblogic, IBM’s MQSeries, and IPlanet’s Message Queue for Java. The JMS runtime chosen must be installed and configured before the JMS connector can be used. The JMS connectors differ from the others in the integration broker in that while most connectors provide access to the broker via a communication protocol, in order to test the interaction with the JMS connectors actual Java code must be written. Please refer to your JMS provider’s documentation for examples of how to do this.

Receiving Published JMS Messages
The JMSListeningConnector starts a thread for each queue or topic specified in the integration properties file. These threads will listen for newly published messages. When a message is published to a queue of interest, the connector will retrieve the message and will send it to the application server. This also occurs when messages are published to topics that the connector is interested in.

Configuring the Listening Connector
The gateway must be configured in order to be able to listen to specific topics and queues. This is done by adding entries to the integration properties file. In order to know how many queues and topics that are to be monitored, the following two values must be set: ig.jms.Queues ig.jms.Topics If no queue or topics are to be monitored, both should be set to 0. If the gateway is going to be setup to monitor two queues and three topics, these entries would be set to: ig.jms.Queues=2 ig.jms.Topics=3 Each topic or queue being monitored will require individual property entries. The properties required are:

Property Name ig.jms.XXX ig.jms.XXX.Provider

Description The name of the topic or queue. Mandatory. The name of the JMS Provider. Mandatory.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

45

4/10/2009 Property Name ig.jms.XXX.JMSFactory Description The name of the connection factory. Mandatory. “TopicConnectionFactory” for topics “QueueConnectionFactory” for queues ig.jms.XXX.MessageSelector This can be used to filter the messages retrieved. Optional. If no value is specified, all messages will be returned. JNDI URL to file system. The user name requried to access the JMS provider. Mandatory. The password required to access the JMS provider. Mandatory.

ig.jms.XXX.Url ig.jms.XXX.User ig.jms.XXX.Password

The XXX in the property names above refer to a specific naming convention that must be followed. For queues, this would be QueueX, where X is the number of the queue. So if there were two queues to be configured, there would be two sets of queue properties. The first set would use the name Queue1, and the second Queue2. Topics follow the same format. If three topics were being configured, there would be property entries for Topic1, Topic2, and Topic3. MessageSelectors are a JMS standard way of filtering messages. Selectors allow messages to be chosen based on a combination of the message’s header and property field values. Messages that match the selector are retrieved, while those that don’t are not. MessageSelector syntax is based on a subset of SQL, and is quite powerful. For a complete description of how to use MessageSelectors, please refer to Sun’s Java API documentation for the Java Message Service. The JNDIFactory class name must be set up for the JMS provider being used. In the configuration file there are the following entries: #The JNDIFactory Classnames for Weblogic, IPlanet, MQSeries. # ig.jms.JMSProvider.JNDIFactory.Weblogic=weblogic.jndi.WLInitialContextFactory # ig.jms.JMSProvider.JNDIFactory.IPlanet=com.sun.jndi.fscontext.RefFSContextFactory # ig.jms.JMSProvider.JNDIFactory.MQSeries=com.sun.jndi.fscontext.RefFSContextFactory Simply uncomment the line corresponding to the JMS provider being used. Finally, the ErrorTopic and ShutdownTopic must be configured. These topics have similar properties to normal topics. Each has a specific entry in the integration gateway properties file. Uncomment and set the properties for each. These topics should not be counted when setting the value for ig.jms.Topics. Java is case sensitive, so if there are problems in getting JMS to work, check to ensure that the case of all property file entries is correct.

Incoming Message Format
In order to be processed by the connector, the published message must contain the following properties in the JMS Message header:

© Copyright PeopleSoft Corporation 2001. All rights reserved.

46

4/10/2009 Property Name MessageName RequestingNode Password FinalDestinationNode Description The name of the incoming message. (Required property) The name of the requesting node. (Required property) The user’s password. The node that the message is to ultimately be delivered to. If no final destination, set this to “NULL”. This is a list of all the nodes that the message has been routed through, separated by commas. This can be set to the empty string. True/False. True if the sender wants a reply generated to the message, False otherwise.

DestinationNodes

ReplyTo

Additionally, the message type of the message must be “TextMessage”. If any of the properties are missing or are invalid, an exception will be logged. No notifications will be returned to the sender of the message. If the message is formatted correctly, the JMS listening connector will build a request message which will be sent to the application server for processing. All Error messages are published back to the ErrorTopic. So it is necessary to set up ErrorTopic.

Response to Incoming Messages
Because of the nature of JMS, synchronous replies are not possible. However if the received message requests a reply, one will be created and will be returned on the “Temporary” topic or queue. The actual configuration for temporary topics and queues is dependant upon the specific JMS provider being used. Please check your provider’s documentation for specific instructions on how to set these up. The contents of the response will be the contents of the body of the message received by the connector.

Example Of Use
The following example assumes that the JMS provider being used has been configured correctly. Since each provider has specific configuration requirements – that may vary between product releases - it is impossible to present a generic sequence of steps to accomplish this here. Please refer to your provider’s documentation for details. Configuration of a JMS provider may not be a trivial exercise, so care must be taken in order to ensure that the provider is working correctly. Before attempting the example here, check to make sure that messages can be published and retrieved from named topics and queues. Many providers come with sample programs that can be run to verify this. This example will assume that the JMS Provider being used is BEA’s Weblogic. Additionally, a means to publish messages to a topic must be available for this to work. The sample programs for your JMS provider should provide examples of how to accomplish this.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

47

4/10/2009 In this example, the gateway will be configured to receive messages from a specific topic. This message will be sent to the app server, where PeopleCode will be invoked to write the contents of the message to the file system. Example Specific Setup 1) Modify the Integration Properties file Note: values for Url, User, and Password in the following will be dependant upon the specific configuration of the JMSProvider. • Set the number of topics to be created: # Enter the number of Topic Subscribers to instantiate ig.jms.Topics=1 • Configure the topic: ig.jms.Topic1=SampleTopic ig.jms.Topic1.Provider=Weblogic ig.jms.Topic1.JMSFactory=TopicConnectionFactory ig.jms.Topic1.MessageSelector= ig.jms.Topic1.Url=t3://localhost:80 ig.jms.Topic1.User=system ig.jms.Topic1.Password=password • Choose the JNDI class name to use. In this instance the line for BEA is uncommented: #The JNDIFactory Classnames for Weblogic, IPlanet, MQSeries. ig.jms.JMSProvider.JNDIFactory.Weblogic=weblogic.jndi.WLInitialContextFactory #ig.jms.JMSProvider.JNDIFactory.IPlanet=com.sun.jndi.fscontext.RefFSContextFact ory #ig.jms.JMSProvider.JNDIFactory.MQSeries=com.sun.jndi.fscontext.RefFSContextFac tory • Configure the Error Topic: ig.jms.ErrorTopic=ErrorTopic ig.jms.ErrorTopic-Provider=Weblogic ig.jms.ErrorTopic-User=system ig.jms.ErrorTopic-Password=password ig.jms.ErrorTopic-JMSFactory=TopicConnectionFactory ig.jms.ErrorTopic-Url=t3://localhost:80 • Configure the Shutdown Topic: ig.jms.shutdown.Provider=Weblogic ig.jms.shutdown.JMSFactory=TopicConnectionFactory ig.jms.shutdown.Url=t3://localhost:80 ig.jms.shutdown.User=system ig.jms.shutdown.Password=password • Save and close the integration properties file.

2) Restart the gateway. 3) Before the gateway can process JMS messages, the JMS connector must be initialized. To do this, open a web browser and open the URL: http://<your gateway server name>/PSIGW/JMSListeningConnectorAdministrator?Activity=Start

© Copyright PeopleSoft Corporation 2001. All rights reserved.

48

4/10/2009 4) Start up a web browser and access the PIA page for the Integration Broker. • • • • Select “Relationships”. Choose the EXAMPLE_RELATIONSHIP, and click on the “TRANS MODIFIERS” tab. Click the “Edit” button for the transaction modifer. On the resulting page, set the Status of the modifier to “Inactive”, and click “Save”.

5) Open the Application Designer. • • • • • Select File->Open from the menu. In the pop up window, select “Messages” and click “Open” Select the “EXAMPLE_REQUEST_MESSAGE” Right click on VERSION_1 of the message, and select “View PeopleCode” Select the “OnRequest” event, and paste the following code into the window:
Local XmlDoc &request, &response; &request = GetMessageXmlDoc(); &string = &request.GenXmlString(); &theFile = GetFile("test.xml", "A"); &theFile.WriteLine(&string); &theFile.Close(); &response = CreateMessage(Message.EXAMPLE_RESPONSE_MESSAGE); ReturnToServer(&response);

This code will take the incoming JMS message and will write to the file names “test.xml”. This file will be located in the “files” directory of the application server. 6) Clear the message and error log files on the gateway.

Running the example 1) Publish a JMS message with the following characteristics to the SampleTopic topic: • • • MessageName = EXAMPLE_REQUEST_MESSAGE RequestingNode = SOURCENODE and set the text of the message to “This is a test message”

2) Check the “test.xml” file. The following should be seen: <?xml version="1.0"?> <Request><data PsNonXml="Yes"><![CDATA[This is a test message]]></data></Request>

© Copyright PeopleSoft Corporation 2001. All rights reserved.

49

4/10/2009

3) Check the gateway message log to see the messages exchanged between the gateway and the app server.

Publishing JMS Messages
The JMSTargetConnector is responsible for publishing JMS messages to topics and queues.

Configuring the Target Connector
Configuration of the target connector differs from the listening connector in that there is less to configure in the properties file, but connector information must be set up on the application server. All that needs to be set in the properties file is the selection of the JNDIFactory and configuration of the Error and Shutdown topics. Please see the section on configuring the listening connector to see how to do this. There are quite a few JMS connector properties. They are:

Property Name JMSAcknowledgement

Description Identifies the Acknowledgement type : Values are   Auto_Acknowledge Client_Acknowledge

JMSDeliveryMode

Identifies Durable or Non-Durable delivery. Values are   Persistent Non-Persistent

JMSFactory JMSMessageTimeToLive

Identifies the Queue/Topic Connection Factory name. Identifies the message priority for delivery. Values range from 0 to 9, with 9 indicating the highest priority. The default is 0.

JMSMessageType

Identifies type of message. Vales are Text,Map,Object Message

JMSUserName JMSPassword JMSPriority JMSProvider

JMS User name JMS Provider Password Identifies the priority of JMS Message Identifies JMS Provider name. Values are :

© Copyright PeopleSoft Corporation 2001. All rights reserved.

50

4/10/2009 Property Name Description Mqseries, Weblogic, iPlanet. JMSReplyTo True – If it is Request/Reply. False – Not a Request/Reply. JMSTopic JMSQueue JMSMessageTypeClass Name of the Topic to Publish the message Name of the Queue to put the message. Identifies the implementation of ProcessJMSMessage. You must set this property when the JMSMessage type is anything other that Text. JNID URL to file system.

JMSUrl

Example Of Use
The following example assumes that the JMS provider being used has been configured correctly. Since each provider has specific configuration requirements – that may vary between product releases - it is impossible to present a generic sequence of steps to accomplish this here. Please refer to your provider’s documentation for details. Configuration of a JMS provider may not be a trivial exercise, so care must be taken in order to ensure that the provider is working correctly. Before attempting the example here, check to make sure that messages can be published and retrieved from named topics and queues. Many providers come with sample programs that can be run to verify this. This example will assume that the JMS Provider being used is BEA’s Weblogic. Additionally, a means to publish messages to a topic must be available for this to work. The sample programs for your JMS provider should provide examples of how to accomplish this. This example will mimic a hub configuration. An incoming HTTP sync message received by the gateway, sent to the application server and will be converted into a JMS message that will be published to a specific topic. Example Specific Setup 1) Start up a web browser and log into PIA. Select the Integration Broker menu item. 2) Select the “Node Definitions” menu item. Type in “TargetNode” in the search box and click the “Search” button. 3) Select the “Connectors” tab. • • • • • • Ensure that the gateway ID for the node is set to the name of gateway you wish to use. Select “JMSTARGET” as the connector ID for this node. Hit the “Save” button. Set JMSTARGET;JMSFactory to “TopicConnectionFactory” Set JMSTARGET;JMSProvider to “Weblogic” Set JMSTARGET;USERNAME to the JMS userid for the server Set JMSTARGET;PASSWORD to the JMS userid password server 51

© Copyright PeopleSoft Corporation 2001. All rights reserved.

4/10/2009 • • • Set JMSTARGET;Url to the URL of the server Set JMSTARGET;JMSTopic to “SampleTopic” Hit the “Save” button.

4) Modify the Integration Properties file Note: values for Url, User, and Password in the following will be dependant upon the specific configuration of the JMSProvider. • Choose the JNDI class name to use. In this instance the line for BEA is uncommented: #The JNDIFactory Classnames for Weblogic, IPlanet, MQSeries. ig.jms.JMSProvider.JNDIFactory.Weblogic=weblogic.jndi.WLInitialContextFactory #ig.jms.JMSProvider.JNDIFactory.IPlanet=com.sun.jndi.fscontext.RefFSContextFact ory #ig.jms.JMSProvider.JNDIFactory.MQSeries=com.sun.jndi.fscontext.RefFSContextFac tory • Configure the Error Topic: ig.jms.ErrorTopic=ErrorTopic ig.jms.ErrorTopic-Provider=Weblogic ig.jms.ErrorTopic-User=system ig.jms.ErrorTopic-Password=password ig.jms.ErrorTopic-JMSFactory=TopicConnectionFactory ig.jms.ErrorTopic-Url=t3://localhost:80 • Configure the Sample Topic: ig.jms.shutdown.Provider=Weblogic ig.jms.shutdown.JMSFactory=TopicConnectionFactory ig.jms.shutdown.Url=t3://localhost:80 ig.jms.shutdown.User=system ig.jms.shutdown.Password=password • Save and close the integration properties file.

7) Restart the gateway. 8) Clear the message and error log files on the gateway. Running the example 1) Start the program that will receive the JMS messages. The program should be configured to listen for the “SampleTopic” topic. 2) Start up SendMaster. • • Create a new project. Enter the appropriate Server URL for your gateway. For a system where the gateway is running on the same computer as SendMaster, the URL may look like: http://127.0.0.1/PSIGW/HttpListeningConnector • Set the Project Type to “Input File” 52

© Copyright PeopleSoft Corporation 2001. All rights reserved.

4/10/2009 • Put the following text into the text area in the Input Information section. <?xml version=”1.0”?> <IBRequest> <MessageName>EXAMPLE_REQUEST_MESSAGE</MessageName> <MessageType>sync</MessageType> <From> <RequestingNode>SOURCENODE</RequestingNode> </From> <To> <DestinationNode>putYourLocalNodeNameHere</DestinationNode> </To> <ContentSections> <ContentSection> <NonRepudiation/> <Data><![CDATA[This is the body of the request.]]></Data> </ContentSection> </ContentSections> </IBRequest>

Click the POST button to send the request to the broker. The request will be sent to the gateway, which will forward it on to the application server, who will then forward it back out to the gateway. The gateway will take the message and will publish it to JMS using the connector settings specified for the node. Once the transfer has occurred, a response message will be generated and sent back to SendMaster. Since there is no information in the body of the message, the output information area will not have any text in it.

9) The program monitoring the topic should receive the message sent by the gateway. The body of the message should be “This is the body of the request.” 10) Check the gateway message log to see the messages exchanged between the gateway, application server, and the JMS provider.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

53

4/10/2009

INTEGRATING USING SMTP
Simple Mail Transfer Protocol (SMTP ) is the standard for transferring email between servers. A single connector is provided for use with SMTP. The SMTPTargetConnector allows integration broker requests to be sent as emails to SMTP servers. The body of the request is used for the body of the email message. The SMTPTargetConnector only allows emails to be sent out of the gateway. In order to retrieve email from a mail server, use the POP3TargetConnector instead.

Sending email from the Integration Broker to external systems
SM TP Connector Properties
Property Name DEST_EMAIL SOURCE_EMAIL CC BCC CONTENT_TYPE sendUncompressed Description The email address to send the message to. Multiple addresses are not supported. This is a mandatory property. This is the email address that will be identified as the sender of the email. This is can be any valid email address. This is a mandatory property. The email address listed here will receive a “carbon copy” of the email. Multiple addresses are not supported. This is an optional parameter. The email address listed here will receive a “blind carbon copy” of the email. Multiple addresses are not supported. This is an optional parameter. This is used to set the content type of the email. This is an optional parameter. If nothing is specified, the default is “text/plain”. Y/N – determines if the message is to be uncompressed before being sent out. (see section xxx for more details) This is an optional property.

Outside of the connector properties, in order to use a given SMTP server the value of ig.connector.smtptargetconnector.host must be set in the gateway’s integration properties file. This property specifies the forwarding SMTP server that the SMTPTargetConnector will send messages to. If this parameter is not set, or incorrectly set, the connector will be unable to send email.

Format of the Outgoing Email Message
This is an example of an email message generated by the SMTPTargetConnector: Date: Sun, 13 Jan 2002 12:15:20 -0800 (PST) From: integrationBroker@PeopleSoft.com To: thirdParty@external.org
© Copyright PeopleSoft Corporation 2001. All rights reserved.

54

4/10/2009 Subject: Message Name = EXAMPLE_REQUEST_MESSAGE / Transaction ID = null CC: otherParty@somewhereelse.com This is the body of the request.

The values in in the From, To, and CC fields are dependant on the property values entered for the connector. The value of the SOURCE_EMAIL can be any valid email address; it does not have to be an address associated with the gateway or with the forwarding SMTP server. This is advantageous in that if the receiving third party wishes to reply to the email address, the address can be setup so that their response can be routed to any valid email account. The reply does not have to go back to the integration broker. The subject line of the email is automatically generated by the connector. It is of fixed format and will always be: Message Name = <the_message_name> / Transaction ID = <the_transaction_id> There is no way to change the subject line.

Response to the SM TP Request
If the email message is sent out successfully, the connector will return an internal response message with the status set to OK. Outgoing email is one way communication, and therefore nothing will be returned in the content section of the response. If the connector is unable to send the email, an error response message will be generated and returned. Note: a successful response message means that the email was successfully transferred to the forwarding email server. It does not necessarily mean that the email was delivered to the final destination! Since an email may travel between multiple servers, there is a chance that an error could occur during transport. If such an error does occur the gateway and application server will not be aware of it. The forwarding SMTP server’s error log shold be periodically checked to catch such cases.

Example of Use
SendMaster will be used to send a sync message into the broker. The broker will be configured so that the incoming message will be routed to the SMTPTargetConnector, which will then attempt to send the body of the message to the specified SMTP server. Note: an active SMTP server will be needed for this example. Example Specific Setup 1) Ensure that the integration properties file has a valid entry for ig.connector.smtptargetconnector.host This should be the name of an active SMTP server. 2) Start up a web browser and log into PIA. Select the Integration Broker menu item. 3) Select the “Node Definitions” menu item. Type in “TargetNode” in the search box and click the “Search” button. 4) Select the “Connectors” tab. • • • Ensure that the gateway ID for the node is set to the name of gateway you wish to use. Select “SMTPTARGET” as the connector ID for this node. Hit the “Save” button. Set SMTPTARGET;SourceEmailAddress to the address that the message should appear to come from. 55

© Copyright PeopleSoft Corporation 2001. All rights reserved.

4/10/2009 • • Set SMTPTARGET;DestEmailAddress to the address that is to receive the email. Hit the “Save” button.

5) Clear the message and error log files on the gateway. Running the example 11) Start up SendMaster. • • Create a new project. Enter the appropriate Server URL for your gateway. For a system where the gateway is running on the same computer as SendMaster, the URL may look like: http://127.0.0.1/PSIGW/HttpListeningConnector • • Set the Project Type to “Input File” Put the following text into the text area in the Input Information section. <?xml version=”1.0”?> <IBRequest> <MessageName>EXAMPLE_REQUEST_MESSAGE</MessageName> <MessageType>sync</MessageType> <From> <RequestingNode>SOURCENODE</RequestingNode> </From> <To> <DestinationNode>putYourLocalNodeNameHere</DestinationNode> </To> <ContentSections> <ContentSection> <NonRepudiation/> <Data><![CDATA[This is the body of the request.]]></Data> </ContentSection> </ContentSections> </IBRequest>

Click the POST button to send the request to the broker. The request will be sent to the gateway, which will forward it on to the application server, who will then forward it back out to the gateway. The SMTPTargetConnector will build an email message out of the request, and will send it off to the specified SMTP server. Once the email has been sent, a response message will be generated and sent back to SendMaster. Since there is no information in the body of the message, the output information area will not have any text in it.

12) Check the gateway message log to see the messages exchanged between the gateway, the application server, and the SMTP server. Specific log entries will be seen for the SMTP connector showing that the email was sent successfully. 13) Check the target email account for the message. Note that depending on the load on the forwarding SMTP server and the traffic between it and the target’s SMTP server, it may take several seconds ( or minutes! ) for the email to be delivered.
© Copyright PeopleSoft Corporation 2001. All rights reserved.

56

4/10/2009

© Copyright PeopleSoft Corporation 2001. All rights reserved.

57

4/10/2009

INTEGRATING USING POP3
The POP3TargetConnector gives the integration broker the ability to retrieve email messages from external systems. POP3, and therefore this connector, cannot be used to send email; use the SMTPTargetConnector for this. The POP3TargetConnector behaves a bit differently from the other connectors. Whereas many of the other connectors are essentially simply request/reply based – the HTTPTargetConnector sends out an HTTP request and gets an HTTP response in return – the POP3TargetConnector has much more interaction with a target server. A POP3 server provides a mailbox for a user. All mail received for that user is placed in this mailbox by the server. Typically, users access their mailbox via client email programs such as Eudora or Outlook. The programs interact with the email server by issuing sequences of POP3 commands and presenting the results to the user in a friendly manner. The POP3TargetConnector directly accesses mailboxes via POP3 commands. Each POP3 command matches a single request sent from the connector to the server. POP3 commands are fairly low level and atomic. Several messages may be required in a single session in order to list, read, and delete any email present on the server. Because of this complexity, the POP3TargetConnector differs from the other target connectors in that the configuration and control of the connector can be done in one of two ways: either through the connector properties, or via the contents of the request message body itself. Additionally, there is a level of support for POP3 through PeopleCode not seen for the other connectors. Since POP3 connections tend to be interactive and conversational, programmatic access to the protocol to control the connection is very useful. There are several messages defined in the integration broker soley for use with the connector. These messages, and how to use them, will be discussed later in this document.

POP3 Connector Properties
There are several properties present when defining a POP3 connection for a given node. They are:

Property Name Server User Password Port Method Name Count

Description The name of the POP3 mail server. This is a mandatory field. The userid for the email account on the server. This is a mandatory field. The password for the email account on the server. This is a mandatory field. This is the port number to connect to on the server. This is a mandatory field. This field defaults to port 110. This is the desired POP3 action to take. This is a mandatory field. The list of names is in the following table. The number of messages that the method specified should operate on. This is a mandatory field, but it is not used by all the methods. This field defaults to 0. 58

© Copyright PeopleSoft Corporation 2001. All rights reserved.

4/10/2009

Keep in mind that while a field must be present in the connector properties for the target node when accessing the server via properties, this is not necessarily the case when accessing servers via message bodies. Please refer to that section of the document for further details. There are a number of predefined actions that can be invoked via the connector properties. They are:

Method Name MessageCount ReadAll ReadAndDelete ReadMessage DeleteMessage ReadHeaders ReadHeadersWithAttach ReadMessageWithAttach

Description Returns the number of messages available in the account. Gets all the messages in the mailbox on the server. Gets all the messages in the mailbox on the server, and then deletes the messages from the mailbox. Reads a specified message from the mailbox. Deletes a specified message from the mailbox. Gets the headers for all the available messages in the mailbox. Gets the headers and attachment information for all the available messages in the mailbox. Reads a specified message that has attachments from the mailbox.

Predefined Messages for POP3
There are multiple messages defined in the integration broker for POP3. These messages are used when writing PeopleCode to exercise the connector, and are necessary in order to send the POP3 requests from the application server to the gateway. These messages are based on the Method Names described previously. There are two messages in the broker for each method: one to capture the request out of the gateway to the mail server, and one for the response. The current list of messages are:

Method Name Message Count ReadAll ReadAndDelete ReadMessage DeleteMessage ReadHeaders ReadHeadersWithAttach

Request Message Name EMAIL_REQ_MSGCOUNT EMAIL_REQ_READALL EMAIL_REQ_READDELALL EMAIL_REQ_READMSG EMAIL_REQ_DELMSG EMAIL_REQ_READHDR EMAIL_REQ_READHDRATT

Response Message Name EMAIL_RES_MSGCOUNT EMAIL_RES_READALL EMAIL_RES_READDELALL EMAIL_RES_READMSG EMAIL_RES_DELMSG EMAIL_RES_READHDR EMAIL_RES_READDHRATT

© Copyright PeopleSoft Corporation 2001. All rights reserved.

59

4/10/2009 Method Name ReadMessageWithAttach Request Message Name EMAIL_REQ_READMSGATT Response Message Name EMAIL_RES_READMSGATT

The request messages all share the same child record: EMAIL_REQ_WRK.

Field Name USER PASSWORD SERVER PORT METHODNAME NUMROWS UIDL

From looking at the field names, it becomes apparent that the fields in this record have a direct correspondance to the connector properties for the POP3TargetConnector. The only things that may not be obvious are the fields NUMROWS and UIDL. NUMROWS has the same function as the “Count” property. UIDL is used to specify a particular email message on the server to delete, and is necessary for the ReadMessage and DeleteMessage methods. The response messages also share a common child record: EMAIL_RES_WRK.

Field Name EMAIL_FROM EMAIL_SENDER UIDL WL_SUBJECT EMAIL_TEXTLONG DATE_FROM NUMROWS NOTIFY_TO NOTIFY_CC

Description The address that the email was sent from. The address that replies to the message should be sent to. The ID of the message on the server. The subject line of the message. The text of the message. The date that the email was received. The count of messages found. The list of addressess on the TO: list in the email. The list of addresses in the CC: list in the email.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

60

4/10/2009 The EMAIL_RES_READMSGATT has an additional child record used to capture attachment information: EMAIL_ATT_WRK.

Field Name EMAIL_TEXTLONG CONTENT_TYPE FILENAME FILE_DATA

Description The text of the attachment. The content-type of the attachment. The name of the file. This is used when the data is of type binary. The actual data will be in this field.

The P T_EM AIL_POP3 Node
PT_EMAIL_POP3 is a predefined node on the application server. This node is configured with all the request and response messages setup as outgoing synchronous transactions. These transactions are necessary in order to be able to use PeopleCode to control the POP3 connection. Since PT_EMAIL_POP3 has all these transactions already defined, this node can be used with little additional setup required. However, if it is desired to use another target node, then transactions must be created for that node for the POP3 messages. Use PT_EMAIL_POP3 as a reference when setting up these transactions.

PeopleCode Examples
As previously mentioned, there are two main ways to use the connector: by using the properties defined for the connector for the target node, or by specifying them in the body of the message. The connector properties for the target node are always available for POP3 requests. They provide default behaviour when property values cannot be found on an outgoing request. However, if the user explicitly provides said values when building the message, these default properties can be ignored. Connector Properties By using the connector properties defined for the node, less PeopleCode needs to be written. This sample code gets the current count of available messages on the mail server:
Local Message &request; Local Message &response; &request = CreateMessage(Message.EMAIL_REQ_MSGCOUNT); &request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.UIDL).Value = 1; &response = &request.SyncRequest(Node.PT_EMAIL_POP3); If (&response.ResponseStatus = 0) Then &str = &response.GetRowset().GetRow(1).GetRecord(Record.EMAIL_RES_WRK).GetField(Field.NUMROWS).Valu e; REM str now contains the the number of email messages for the account on the POP3 server;

© Copyright PeopleSoft Corporation 2001. All rights reserved.

61

4/10/2009
End-If; ReturnToServer(&response);

The type of message was explicitly stated: this is a EMAIL_REQ_MSGCOUNT. Since property values were not explicitly set on the message, they will be read from the connector properties for the transaction or node and added to the message. While UIDL is really only needed for a couple of the messages types, a value must be specified after messages creation for all POP3 messages, otherwise an error will occur when the application server attempts to send the message. In such cases where the UIDL is not needed by the message, the value set for the UIDL is not relevant; anything can be chosen. Message Body If the properties are set on the message, the PeopleCode changes to:

Local Message &request; Local Message &response; &request = CreateMessage(Message.EMAIL_REQ_MSGCOUNT); REM Set the connectors values explicitly on the request; &request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.UIDL).Value = 1; &request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.SERVER).Value = "the_POP3_server_name"; &request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.USER).Value = "the_email_account_username"; &request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.PASSWORD).Valu e = "the_email_account_password"; &request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.METHODNAME).Va lue = "MessageCount"; &request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.PORT).Value = 110; &response = &request.SyncRequest(Node.PT_EMAIL_POP3); If (&response.ResponseStatus = 0) Then &str = &response.GetRowset().GetRow(1).GetRecord(Record.EMAIL_RES_WRK).GetField(Field.NUMROWS).Valu e; REM str now contains the number of email messages in the account on the POP3 server; End-If; ReturnToServer(&response);

© Copyright PeopleSoft Corporation 2001. All rights reserved.

62

4/10/2009

Response to POP3 Request
When the POP3TargetConnector successfully sends a request to the email server, a response message is generated and is returned to the application server. The response will be a structured message, with the contents of the message reflecting the fields found in EMAIL_RES_WRK. PeopleCode programs can access this message structure to extract the necessary information. If an error occurs, an error response message will be returned. There will be no content section associated with the message.

POP3 Connector Properties – Order of Precedence
Connector properties for the POP3TargetConnector can be set in three different locations: 1) as part of the node definition 2) as an override on the transaction for the particular POP3 message being used 3) in PeopleCode, when a message is explicitly created. Valid connector properties could be set in all three for a given instance. However, there is a definite order of precedence. The connector data in the node definition can be considered the default, and will be used if the data cannot be found elsewhere. Connector data on the transaction will override node definition connector data. However, if the data is explicitly set on the message in PeopleCode, then both the node and transaction are ignored.

Example of Use – External Message Triggering Connector
SendMaster will be used to send a sync message into the broker. The broker will be configured so that the incoming message will be routed to the POP3TargetConnector, which will then attempt get a count of all of the email messages from the mail server. Note: an active POP3 server will be needed for this example, as well as a valid account on it. Example Specific Setup 1) Start up a web browser and log into PIA. Select the Integration Broker menu item. 2) Select the “Node Definitions” menu item. Type in “TargetNode” in the search box and click the “Search” button. 3) Select the “Connectors” tab. • • • • • • Ensure that the gateway ID for the node is set to the name of gateway you wish to use. Select “POP3TARGET” as the connector ID for this node. Hit the “Save” button. Set POP3TARGET;Server to the name of the POP3 server Set POP3TARGET;User to the userid coressponding to the account on the server Set POP3TARGET;Password to the password for the account on the server Set POP3TARGET;MethodName to “MessageCount”

© Copyright PeopleSoft Corporation 2001. All rights reserved.

63

4/10/2009 • Hit the “Save” button.

4) Clear the message and error log files on the gateway. Running the example 1) Start up SendMaster. • • Create a new project. Enter the appropriate Server URL for your gateway. For a system where the gateway is running on the same computer as SendMaster, the URL may look like: http://127.0.0.1/PSIGW/HttpListeningConnector • • Set the Project Type to “Input File” Put the following text into the text area in the Input Information section. <?xml version=”1.0”?> <IBRequest> <MessageName>EXAMPLE_REQUEST_MESSAGE</MessageName> <MessageType>sync</MessageType> <From> <RequestingNode>SOURCENODE</RequestingNode> </From> <To> <DestinationNode>putYourLocalNodeNameHere</DestinationNode> </To> <ContentSections> <ContentSection> <NonRepudiation/> <Data><![CDATA[This is the body of the request.]]></Data> </ContentSection> </ContentSections> </IBRequest>

Note: there is actually no data in this message that is specific to counting messages or even POP3. This message is simply used as a trigger to invoke the POP3 server. • Click the POST button to send the request to the broker. The request will be sent to the gateway, which will forward it on to the application server, who will then forward it back out to the gateway. The POP3TargetConnector will query the mail server and will get back a count of the available messages in the mailbox. Once the email has been sent, a response message will be generated and sent back to SendMaster. This is an example of what might be seen:
<?xml version='1.0'?> <EMAIL_RES_MSGCOUNT> <FieldTypes> <EMAIL_RES_WRK class="R"> <EMAIL_FROM type="CHAR"/> <NUMROWS type="NUMBER"/> </EMAIL_RES_WRK> <PSCAMA class="R"> <LANGUAGE_CD type="CHAR"/> <AUDIT_ACTN type="CHAR"/> © Copyright PeopleSoft Corporation 2001. All rights reserved.

64

4/10/2009
<BASE_LANGUAGE_CD type="CHAR"/> <MSG_SEQ_FLG type="CHAR"/> <PROCESS_INSTANCE type="NUMBER"/> <PUBLISH_RULE_ID type="CHAR"/> <MSGNODENAME type="CHAR"/> </PSCAMA> </FieldTypes> <MsgData> <Transaction> <EMAIL_RES_WRK class="R"> <EMAIL_FROM></EMAIL_FROM> <NUMROWS>32</NUMROWS> </EMAIL_RES_WRK> <PSCAMA class="R"> <LANGUAGE_CD></LANGUAGE_CD> <AUDIT_ACTN></AUDIT_ACTN> <BASE_LANGUAGE_CD></BASE_LANGUAGE_CD> <MSG_SEQ_FLG></MSG_SEQ_FLG> <PROCESS_INSTANCE>0</PROCESS_INSTANCE> <PUBLISH_RULE_ID></PUBLISH_RULE_ID> <MSGNODENAME></MSGNODENAME> </PSCAMA> </Transaction> </MsgData> </EMAIL_RES_MSGCOUNT>

The response to the request for a count of the messages is found in the NUMROWS field under EMAIL_RES_WRK. In this instance, there were 32 available messages found on the server.

2) Check the gateway message log to see the messages exchanged between the gateway, the application server, and the POP3 server. Specific log entries will be seen for the POP3 connector showing that the email was sent successfully.

Example of Use – Triggering POP3 Requests via PeopleCode
The previous example was somewhat contrived. It is unlikely that anyone would use the POP3 connector in such a fashion – after all a message could only trigger one type of POP3 request. It’s much more probable that users will write PeopleCode to invoke the POP3 connector This example will be similar to the ones past in that SendMaster will be used to send a message into the broker. OnRequest PeopleCode will be written against this message. This PeopleCode will attempt to get all the messages on the server. Additionally, the connector properties will be set explicitly in the message created, and will not be read from the transaction or node data. The example will not use the PT_EMAIL_POP3 node; transactions will be setup on TARGETNODE to support the POP3 message. An active POP3 server will be needed for this example, as well as a valid account on it. Example Specific Setup 1) Start up a web browser and log into PIA. Select the Integration Broker menu item. 2) Select the “Node Definitions” menu item. Type in “TargetNode” in the search box and click the “Search” button. 3) Select the “Connectors” tab. • Ensure that the gateway ID for the node is set to the name of gateway you wish to use.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

65

4/10/2009 • • Select “POP3TARGET” as the connector ID for this node. Hit the “Save” button. Clear the contents of the following fields: • • • • POP3TARGET;Server POP3TARGET;User POP3TARGET;Password POP3TARGET;MethodName

Clearing these fields isn’t necessary, but is done to show that the message can be created and sent without any connector values being specified on the node. • Hit the “Save” button.

4) Select the “Transactions” for the TargetNode • • • • • • • • • Click “Add Transaction” Set the Transaction Type as “Outbound Synchronous” Set the Request Message to “EMAIL_REQ_READALL “ Set the Version to “VERSION_1” Click the “Add” button On the resulting Transactions Page, click the “Messages” tab. For the Response Message Name, enter “EMAIL_RES_READALL” For the Response Message Version, enter “VERSION_1” Click the “Save” button

5) Open the Application Designer. • • • • • Select File->Open from the menu. In the pop up window, select “Messages” and click “Open” Select the “EXAMPLE_REQUEST_MESSAGE” Right click on VERSION_1 of the message, and select “View PeopleCode” Select the “OnRequest” event, and paste the following code into the window
Local Message &request; Local Message &response; &request = CreateMessage(Message.EMAIL_REQ_READALL); REM Set the connectors values explicitly on the request; &request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.UIDL).Va lue = 1; &request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.SERVER).
© Copyright PeopleSoft Corporation 2001. All rights reserved.

66

4/10/2009
Value = "the_POP3_server_name"; &request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.USER).Va lue = "the_email_account_username"; &request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.PASSWORD ).Value = "the_email_account_password"; &request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.METHODNA ME).Value = "ReadAll"; &request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.PORT).Va lue = 110; &response = &request.SyncRequest(Node.TARGETNODE); ReturnToServer(&response);

Note that SERVER, USER, and PASSWORD will have to be set to the appropriate values for the POP3 account being used.

6) Clear the message and error log files on the gateway. Running the example 1) Start up SendMaster. • • Create a new project. Enter the appropriate Server URL for your gateway. For a system where the gateway is running on the same computer as SendMaster, the URL may look like: http://127.0.0.1/PSIGW/HttpListeningConnector • • Set the Project Type to “Input File” Put the following text into the text area in the Input Information section. <?xml version=”1.0”?> <IBRequest> <MessageName>EXAMPLE_REQUEST_MESSAGE</MessageName> <MessageType>sync</MessageType> <From> <RequestingNode>SOURCENODE</RequestingNode> </From> <To> <DestinationNode>putYourLocalNodeNameHere</DestinationNode> </To> <ContentSections> <ContentSection> <NonRepudiation/> <Data><![CDATA[This is the body of the request.]]></Data> </ContentSection> </ContentSections> </IBRequest>

Note: there is actually no data in this message that is specific to counting messages or even POP3. This message is simply used as a trigger to invoke the POP3 server.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

67

4/10/2009 • Click the POST button to send the request to the broker. The request will be sent to the gateway, which will forward it on to the application server, who will then forward it back out to the gateway. The POP3TargetConnector will query the mail server and will get back a count of the available messages in the mailbox. Once the message has been sent, a response message will be generated and sent back to SendMaster. This is an example of what might be seen:
<?xml version='1.0'?> <EMAIL_RES_READALL> <FieldTypes> <EMAIL_RES_WRK class="R"> <EMAIL_FROM type="CHAR"/> <EMAIL_SENDER type="CHAR"/> <UIDL type="CHAR"/> <WL_SUBJECT type="CHAR"/> <EMAIL_TEXTLONG type="CHAR"/> <NOTIFY_TO type="CHAR"/> <NOTIFY_CC type="CHAR"/> </EMAIL_RES_WRK> <PSCAMA class="R"> <LANGUAGE_CD type="CHAR"/> <AUDIT_ACTN type="CHAR"/> <BASE_LANGUAGE_CD type="CHAR"/> <MSG_SEQ_FLG type="CHAR"/> <PROCESS_INSTANCE type="NUMBER"/> <PUBLISH_RULE_ID type="CHAR"/> <MSGNODENAME type="CHAR"/> </PSCAMA> </FieldTypes> <MsgData> <Transaction> <EMAIL_RES_WRK class="R"> <EMAIL_FROM>someone@peoplesoft.com</EMAIL_FROM> <EMAIL_SENDER>someone@peoplesoft.com</EMAIL_SENDER> <UIDL>&gt;&amp;[&quot;!nVl!!Q*+&quot;!6DZ!!</UIDL> <WL_SUBJECT>test message</WL_SUBJECT> <EMAIL_TEXTLONG>This is the body of a test email</EMAIL_TEXTLONG> <NOTIFY_TO>someoneElse@peoplesoft.com;</NOTIFY_TO> <NOTIFY_CC></NOTIFY_CC> </EMAIL_RES_WRK> <PSCAMA class="R"> <LANGUAGE_CD></LANGUAGE_CD> <AUDIT_ACTN></AUDIT_ACTN> <BASE_LANGUAGE_CD></BASE_LANGUAGE_CD> <MSG_SEQ_FLG></MSG_SEQ_FLG> <PROCESS_INSTANCE>0</PROCESS_INSTANCE> <PUBLISH_RULE_ID></PUBLISH_RULE_ID> <MSGNODENAME></MSGNODENAME> </PSCAMA> </Transaction> </MsgData> </EMAIL_RES_READALL>

2) Check the gateway message log to see the messages exchanged between the gateway, the application server, and the POP3 server. Specific log entries will be seen for the POP3 connector showing that the request was handled successfully.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

68

4/10/2009

Appendix A – Special Notices
All material contained in this documentation is proprietary and confidential to PeopleSoft, Inc., is protected by copyright laws, and subject to the nondisclosure provisions of the applicable PeopleSoft agreement. No part of this documentation may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, including, but not limited to, electronic, graphic, mechanical, photocopying, recording, or otherwise without the prior written permission of PeopleSoft, Inc. This documentation is subject to change without notice, and PeopleSoft, Inc. does not warrant that the material contained in this documentation is free of errors. Any errors found in this document should be reported to PeopleSoft, Inc. in writing. The copyrighted software that accompanies this documentation is licensed for use only in strict accordance with the applicable license agreement, which should be read carefully as it governs the terms of use of the software and this documentation, including the disclosure thereof. See Customer Connection or PeopleBooks for more information about what publications are considered to be product documentation. PeopleSoft, the PeopleSoft logo, PeopleTools, PS/nVision, PeopleCode, PeopleBooks, and Vantive are registered trademarks, and PeopleTalk and "People power the internet." are trademarks of PeopleSoft, Inc. All other company and product names may be trademarks of their respective owners. The information contained herein is subject to change without notice. Information in this book was developed in conjunction with use of the product specified, and is limited in application to those specific hardware and software products and levels. PeopleSoft may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. The information contained in this document has not been submitted to any formal PeopleSoft test and is distributed AS IS. The use of this information or the implementation of any of these techniques is a customer responsibility and depends on the customer's ability to evaluate and integrate them into the customer's operational environment. While each item may have been reviewed by PeopleSoft for accuracy in a specific situation, there is no guarantee that the same or similar results will be obtained elsewhere. Customers attempting to adapt these techniques to their own environments do so at their own risk. Any pointers in this publication to external Web sites are provided for convenience only and do not in any manner serve as an endorsement of these Web sites.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

69

4/10/2009

Appendix B – Validation and Feedback
This section documents that real-world validation that this Red Paper has received.

CUSTOMER VALIDATION
PeopleSoft is working with PeopleSoft customers to get feedback and validation on this document. Lessons learned from these customer experiences will be posted here.

FIELD VALIDATION
PeopleSoft Consulting has provided feedback and validation on this document. Additional lessons learned from field experience will be posted here.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

70

4/10/2009

Appendix C – JMS MQ Integration
Java Message Service makes it easy to write business application that asynchronously/synchronously send and receive critical business data and events. JMS supports both message queueing and publish-subscriber styles of messaging. A JMS application is composed of the following parts 1. A JMS Provider is a messaging system that implements the JMS Interfaces and provides administrative and control features. 2. JMS Clients are the programs or components, written in Java programming languge that produce and consume messages. 3. Messages are objects that communicate information between JMS Clients. 4. Administered objects are preconfigured JMS Objects created by administrator for the use of clients.

People Soft JMS Target Connector

© Copyright PeopleSoft Corporation 2001. All rights reserved.

71

4/10/2009 1. Use JMS Providers Administrative tool to Bind Connection factories, Topics and Queues. 2. Uncomment the following line in integrationgateway.properties file ig.jms.JMSProvider.JNDIFactory.MQSeries=com.sun.jndi.fscontext.RefFSContextFactory 3. Set up the connector properties at the node level/transaction level for JMS Target Connector. 4. JMS Target Connector uses connector properties and looks up JNDI name space for Connection factory or Topic or Queue. 5. Opens a connection to the JMS Provider. 6. Either publishes a message to Topic or inserts message in to the Queue. 7. Subscriber receives the message or Queue listener picks up the message from the Queue.

Synchronous/Point-To-Point A point to point application is built around the concept of message queues, senders and receivers. Each message is addressed to a specific Queue, and receiving clients extract messages from the queue. Queues retain all messages sent to them until the messages are consumed or until the messages expire.

1. Use JMS Providers Administrative tool to Bind Connection factories, Topics and Queues. 2. Uncomment the following line in the integrationgateway.properties file ig.jms.JMSProvider.JNDIFactory.MQSeries=com.sun.jndi.fscontext.RefFSContextFactory

3. Set up the connector properties at the node level/transaction level for JMS Target Connector. (Set up the ReplyTp property as True for receiving Reply and set up WaitForResponse for waiting time of response)
© Copyright PeopleSoft Corporation 2001. All rights reserved.

72

4/10/2009 4. JMS Target Connector uses connector properties and looks up JNDI name space for Connection factory or Topic or Queue. 5. Creates a connection to JMS Provider. 6. Creates a Temporary Queue, and sets it in the message object. 7. Sends the message to the JMS Provider, waits for response on Temporary Queue. 8. Once the response is received closes the connection with JMS Provider.

People Soft JMS Listening Connector

1. Use JMS Providers Administrative tool to Bind Connection factories, Topics and Queues. 2. Please uncomment the following line in the integrationgateway.properties file a. ig.jms.JMSProvider.JNDIFactory.MQSeries=com.sun.jndi.fscontext.RefFSContextFactory 3. Set up the following properties for Queue(if Topic need to setup Topic properties) in the integrationgateway.properties file ig.jms.Queues

© Copyright PeopleSoft Corporation 2001. All rights reserved.

73

4/10/2009        ig.jms.Queue1 ig.jms.Queue1.Provider ig.jms.Queue1.JMSFactory ig.jms.Queue1.MessageSelector ig.jms.Queue1.Url ig.jms.Queue1.User ig.jms.Queue1.Password

4. Set up the following Error Topic properties.       ig.jms.ErrorTopic=Error ig.jms.ErrorTopic-Provider ig.jms.ErrorTopic-User ig.jms.ErrorTopic-Password ig.jms.ErrorTopic-JMSFactory ig.jms.ErrorTopic-Url

5. JMS Target connector uses connector properties and look up JNDI name space for Connection factory or Topic or Queue. 6. Creates a connection to JMS Provider 7. Starts Queue Listeners and Topic Subscribers for different Queues and Topics. MQ-JMS Connector Configuration steps      INSTALL MQ Install MA – 88 Plug-In (For MQ5.2 and older versions download from www.ibm.com) Configure MQ & JMS Configure WebSphere (If application is running on WebSphere) Configure Integration Broker.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

74

4/10/2009 Configuring MQ  JMS Admin setup

Change the JMSADMIN.config using any editor and uncomment the following line INITIAL_CONTEXT_FACTORY = com.sun.jndi.ldap.RefFSContextFactory Comment the following line INITIAL_CONTEXT_FACTORY = com.sun.jndi.ldap.LdapCtxFactory Comment out PROVIDER_URL=ldap://polaris/o=ibm,c=us Uncomment PROVIDER_URL=file:/usr/WebhSphere/AppServer/jndi. (This is the directory where you JNDI exists)  Set up Connection factories, Queues and Topics using JMSAdmin utility.

You also can use IVTSetup file to setup different connection factories, Topics and Queues.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

75

4/10/2009  Run IVTSetup Run IVT setup and make sure Setup is fine. Configure WebSphere  Open the WebSphere admin console Expand Resources->JMS Providers  Add new JMS Provider Set the server class path Ex: :/usr/mqm/java/bin:/usr/mqm/java/lib:/usr/mqm/java/lib/com.ibm.mq.jar:/usr/mqm/java/lib/co m.ibm.mqbind.jar:/usr/mqm/java/lib/com.ibm.mqjms.jar:/usr/mqm/java/lib/connector.jar:/usr/ mqm/java/lib/fscontext.jar:/usr/mqm/java/lib/jms.jar:/usr/mqm/java/lib/jndi.jar:/usr/mqm/java/ lib/jta.jar:/usr/mqm/java/libldap.jar:/usr/mqm/java/lib/providerutil.jar (/usr/mqm is the directory where MQ is installed) Name: IBM MQSeries Descrition: IBM MQSeries JMS Provider EXTERNAL INITIAL CONTEXT FACTORY: com.sun.jndi.fscontext.RefFSContextFactory EXTERNAL PROVIDER URL: file:/user/WebSphere/AppServer/jndi   Set up destinations and connection factories Change web.xml file for JNDI Settings and ibm-web-bnd.xmi for resource bindings.

Configuring Integration Broker  Set up the following required properties at the connector level JMSFactory JMSPassword JMSUserName JMSUrl
© Copyright PeopleSoft Corporation 2001. All rights reserved.

76

4/10/2009 JMSReplyTo Add the property name JMSQueue FAQ’s on JMS Connectors

Question - Do we have to use JNDI with JMS in PeopleSoft? JMSitself can be used with or without JNDI. When used with JNDI it is more portable but you have to maintain additional directory service (e.g. LDAP).
Ans - Yes we do use JNDI in JMS Connectors. Right now we support only FileSystem context. Question - Let's start with simplest scenario. We have single MQSeries queue manager (named QM1) located on the same machine as PS WebServer. We have a single queue (named Q1_OUT) and we want to send PS messages into this queue. We have installed MQSeries JMS (MQSeries Java classes) in /opt/mqm/java.What configuration steps we have to perform to have this connection working Ans  Configure JNDI for MQ. (Set Queue & Queue Manager).  Set up JNDI in Websphere (This step is only for Websphere not necessary for Weblogic. For weblogic you need to specify the class path).  Set up connector properties using PIA.  In the integrationgateway.properties uncomment this line ig.jms.JMSProvider.JNDIFactory.MQSeries=com.sun.jndi.fscontext.RefFSContextFactory  Refresh teh gateway. Question -We have two input queues (Q1_IN, Q2_IN) how to configure Gateway and Application Server to distinguisly listen to them Ans #Define two queues in Properties file. ig.jms.Queues=2 ig.jms.Queue1=Q1_IN ig.jms.Queue1.Provider=MQSeries ig.jms.Queue1.JMSFactory=QueueConnectionFactory ig.jms.Queue1.Url=file:c:/MQSeries/JNDI ig.jms.Queue1.User=sam ig.jms.Queue1.Password=sam ig.jms.Queue2=Q2_IN ig.jms.Queue2.Provider=MQSeries ig.jms.Queue2.JMSFactory=QueueConnectionFactory ig.jms.Queue2.Url=file:c:/MQSeries/JNDI ig.jms.Queue2.User=sam ig.jms.Queue2.Password=sam Define error topic. Gateway starts two listeners for two Queues. This configuration is only at the gateway. Nothing is done at the Application server other than defining the transactions. Question - In request/response mode we need two queues (output and input). We will also need both TargetConnector and Listener. How to configure that staff? (For example single queue manager QM1 one output queue Q1_OUT and one input queue Q1_IN) Ans – 1.Define Q1_OUT using TargetConnector. 2. Define Q1_IN using Listening Connector.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

77

4/10/2009

Question - Is it possible to address bigger (dynamic) number of queues from PeopleCode (e.g. 100) without registering each of them? For example in PeopleCode I will explicitly name the queue. This could be useful if we would like to put each message type into different queue with queue name based on message type name (e.g. message "XYZ" in queue "PS.XYZ.OUT") Ans - This can be done, but this must be preconfigured at the transaction level. We can not do this using PeopleCode right now. Question - What is the relationship between (purpose of) contents of integrationGateway.properties and "Integration Broker/Monitor/Gateways" screen in PeopleSoft (screen contains a greed with entries like this "JMSTARGET | JMSAcknowledgment | [x] | AUTO_ACKNOWLEDGE | [x]". Is it so that properties file defines Listners and PS screen TargetConnectors? (Probably the answer for this question is in answers for questions 1..4). Ans - Integration Broker/Monitor/Gateway is the place where we can define the gateway, connector and Target connector properties. These connector properties can be overided at Transaction level too. All JMS Listening Conenctor properties are set using integrationgateway.properties. Question - What configuration files are important other than integrationgateway.properties? Do you have an example of this and any others we can look at? Ans - You dont require any thing other than integrationgateway.properties file for gateway. If you are using websphere you may need to change some files for JNDI setting(refer to Websphere JNDI setup document). Question - Does MQSeries have the ability to prioritize these messages? How does the PeopleSoft/MQSeries integration support this requirement? Ans - Yes MQ has ability to prioritize message, and we can prioritize the messages when they go out from PeopleSoft. Scenario - Multiple non-Psft apps sending non-XML messages into Psft via JMS. How is the IBInfo infomation sent/configured? With each message? In the JNDI? Ans - Every message coming in to Listening connector must have following information in the JMS Message header. 1. Message Name (Required) 2. Requesting Node (Required) 3. Password (Optional) 4. Final Destination Node (Optional) 5. Destionation Nodes. (Optional)

Appendix D – Revision History
Authors
<Name, Role/Title, and short bio>.

Reviewers
The following people reviewed this Red Paper: • <names>

Revision History
1. <Date>: Created document.
© Copyright PeopleSoft Corporation 2001. All rights reserved.

78

4/10/2009 2.

© Copyright PeopleSoft Corporation 2001. All rights reserved.

79

Sign up to vote on this title
UsefulNot useful