Sunteți pe pagina 1din 85

Third Party Integration using the

Integration Broker

Contains:

Prepared by:
T IT LE OF P AP E R
3 /8 /2 0 1 2

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.

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
3/8/2012
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 ............................................................... 11


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 ........................................................................................................................... 12
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 .............................................................................................................................................................................................................. 15
IBInfo XML .................................................................................................................................................................................................... 16
Content Section ............................................................................................................................................................................................. 19

Integration Broker Internal Format for Response Messages...................................................... 20


MIME .............................................................................................................................................................................................................. 20
IBInfo XML .................................................................................................................................................................................................... 21
Content Section ............................................................................................................................................................................................. 22
Error Codes and Message Catalog Entries ................................................................................................................................................ 22

Manipulating Content Sections via Transforms ............................................................................. 23

Character Encoding Considerations ................................................................................................ 24

4
3/8/2012

CHAPTER 3 INTEGRATION EXAMPLES USING THE CONNECTORS .............................................................. 25

Basic Setup for the Examples ............................................................................................................. 25


Add a Message Channel .............................................................................................................................................................................. 25
Add a Request Message .............................................................................................................................................................................. 25
Add a Response Message ........................................................................................................................................................................... 26
Add the Source Node ................................................................................................................................................................................... 26
Add the Target Node .................................................................................................................................................................................... 26
Add the Source Transaction........................................................................................................................................................................ 27
Add the Target Transaction ........................................................................................................................................................................ 27
Add the Relationship and Transaction Modifier...................................................................................................................................... 28

Integrating using HTTP ......................................................................................................................... 30


HTTP Message Credentials ......................................................................................................................................................................... 30
Sending HTTP requests to the Integration Broker................................................................................................................................... 31
HTTP requests from the Integration Broker to external systems ........................................................................................................... 34
HTTP Cookies ................................................................................................................................................................................................ 37
SSL Considerations ....................................................................................................................................................................................... 38

Integrating using SOAP ........................................................................................................................ 39


Sending SOAP requests to the Integration Broker .................................................................................................................................. 39
SOAP requests out of the Integration Broker ........................................................................................................................................... 43

Integrating using FTP ............................................................................................................................ 46


FTP requests from the Integration Broker to external systems .............................................................................................................. 46

Integrating using JMS ........................................................................................................................... 49


Receiving Published JMS Messages ......................................................................................................................................................... 49
Publishing JMS Messages.......................................................................................................................................................................... 54

Integrating using SMTP ........................................................................................................................ 59


Sending email from the Integration Broker to external systems ............................................................................................................. 59

Integrating using POP3 ......................................................................................................................... 63

APPENDIX A SPECIAL NOTICES ................................................................................................................. 75

APPENDIX B VALIDATION AND FEEDBACK................................................................................................. 76

Customer Validation .............................................................................................................................. 76

Field Validation........................................................................................................................................ 76

APPENDIX C JMS MQ INTEGRATION .......................................................................................................... 77

APPENDIX D REVISION HISTORY................................................................................................................ 84


Authors ........................................................................................................................................................................................................... 84
Reviewers........................................................................................................................................................................................................ 84
Revision History ............................................................................................................................................................................................ 84

5
3/8/2012

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


3/8/2012

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 gatewa y 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 connect ors 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 currentl y 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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 7


3/8/2012
PeopleSoftTargetConnector handles requests being sent to other integration brokers.

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
JOLT
Request Request
External Listening PeopleSoft Application
System Connector Target Server
Connector
Response JOLT
Response

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.

1 The gateways integration properties file is used to set the logging level, which controls what is ac tually 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


3/8/2012
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.

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 creat ed.

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.

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


3/8/2012
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
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 processin g 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 respon se
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 message s 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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 10


3/8/2012

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 o perated 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.

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

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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 11


3/8/2012

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.

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 MIMEd 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. Messag es
received without such info will be rejected and will result in errors being thrown.

Two elements are always required for all incoming requests:

Copyright PeopleSoft Corporation 2001. All rights reserved. 12


3/8/2012
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 mess ages 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 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 transac tion 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 m essage 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"/>

Copyright PeopleSoft Corporation 2001. All rights reserved. 13


3/8/2012
</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>
<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 systems 3, it is important to understand it for two reasons:

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

Copyright PeopleSoft Corporation 2001. All rights reserved. 14


3/8/2012
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:

Copyright PeopleSoft Corporation 2001. All rights reserved. 15


3/8/2012

Message-ID: <5722340.1008266844175.JavaMail.MNow osel@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</MessageTyp
e><From><RequestingNode><![CDATA[SOURCENODE]]></RequestingNode><OrigTimeStamp>2001-11-13T10:07:18.817-
0800</OrigTimeStamp></From><PathInfo><![CDATA[/PSIGW/PeopleSoftListeningConnector]]></PathInfo><ContentSections><ContentSection>
<ID>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 messages 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. 16


3/8/2012

<?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>

Copyright PeopleSoft Corporation 2001. All rights reserved. 17


3/8/2012

While the basic structure is the same for all requests, not all elements are always required. An example of t his 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.

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 Description

IBInfo / MessageName The name of the request message. This is a mandatory


field.

IBInfo / MessageType This is the type of the message. Currently, there are three
types: async, sinc, and ping.

IBInfo / TransactionID The transaction id is used to uniquely identify a request.

IBInfo / From / RequestingNode The requesting node is the node that sent the request to
the current system. This is a mandatory field.

IBInfo / From / Password This is the password for the requesting node.

IBInfo / From / DN For incoming requests, the DN gives the Distinguished


Name extracted from the certificate authentication
process.

IBInfo / From / OrigNode For requests that cross multiple nodes, the OrigNode is
used to identify the node that initiated the request.

IBInfo / From / OrigTimeStamp 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.

IBInfo / To / DestinationNode This is the node that this request is to be delivered to.

IBInfo / To / FinalDestinationNode In cases where the message will be passed across


several nodes, this value specifies the ultimate target of
the message.

IBInfo / QStrArgs Specific to incoming HTTP requests. These are the query
string parameters found when the request was received
by the HTTPListeningConnector.

IBInfo / Cookies Specific to incoming HTTP requests. This is cookie string


found when the request was received by the
HTTPListeningConnector.

Copyright PeopleSoft Corporation 2001. All rights reserved. 18


3/8/2012

Element Description

IBInfo / PathInfo Specific to incoming HTTP requests. This is the pathinfo


extracted from the request.

IBInfo / ContentSections / ContentSection This node provides metadata about the text present in the
ContentSection.

IBInfo / ContentSections / ContentSection / ID The index number of the content section.

IBInfo / ContentSections / ContentSection / Indicates as to whether NR should be performed.


NonRepudiation

IBInfo / ContentSections / ContentSection / Headers Provides additional information about the data.

IBInfo / InternalInfo / AppMsg / PublishingNode The node that published the message.

IBInfo / InternalInfo / AppMsg / Channel The channel that the message was published to.

IBInfo / InternalInfo / AppMsg / SubChannel The subchannel that the message was published to.

IBInfo / InternalInfo / AppMsg / DefaultDataVersion The default data version for this message on the node
sending the message.

IBInfo / InternalInfo / AppMsg / VisitedNodes The list of nodes that have already received this message.
This is useful when a message is being propagated
across multiple nodes.

IBInfo / InternalInfo / AppMsg / PublicationID The publication id for this message.

IBInfo / Connector Connector information instructs the gateway as to how to


process the request.

IBInfo / Connector / ConnectorName This is the proper name of the target connector to invoke
to send the message.

IBInfo / Connector / ConnectorClassName This is the class name of the target connector to invoke.

IBInfo / Connector / ConnectorParameters Connector parameters are processing instructions for the
Target Connector to be invoked.

IBInfo / Connector / ConnectorHeaders Connector headers provide further metadata about the
contents of the message to be sent.

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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 19


3/8/2012

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. 20


3/8/2012

Message-ID: <2351889.1008355101212.JavaMail.MNow osel@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>In tegration


Broker Response
Message</DefaultTitle></Status><ContentSections><ContentSection><ID>ContentSection0</ID><NonRepudiation>N</NonRepudiation></Conte
ntSection></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:

Copyright PeopleSoft Corporation 2001. All rights reserved. 21


3/8/2012

Element Description

IBInfo / Status / StatusCode Describes the result of the request. The status codes are:
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.

IBInfo / Status / MsgID 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.

IBInfo / Status / DefaultTitle Used if the message catalog is unavailable. This value
corresponds to the Message Text for a given entry in the
message catalog.

IBInfo / Status / DefaultMsg Used if the message catalog is unavailable. This value
corresponds to the Explanation for a given entry in the
message catalog.

IBInfo / Status / Parameters Parameters may be used to provide additional information


for error responses.

IBInfo / ContentSection 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.

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 m essage 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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 22


3/8/2012
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:

Message-ID: <4328049.1008270392287.JavaMail.MNow osel@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 Gatew ay 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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 23


3/8/2012
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 t he 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.

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 messages 4 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 s erver, 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 UTF 8. 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 thi s.

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 c onfigurable value set on the application server.

Copyright PeopleSoft Corporation 2001. All rights reserved. 24


3/8/2012

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 inclu des 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. 25


3/8/2012
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

Copyright PeopleSoft Corporation 2001. All rights reserved. 26


3/8/2012
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.

Add the Target Transaction

From PIA:

Copyright PeopleSoft Corporation 2001. All rights reserved. 27


3/8/2012
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. Cli ck 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:

Type in An example relationship in the Description field.

Set the Relationship Status to Active.

In the first Node Name field, type in SOURCENODE.

Copyright PeopleSoft Corporation 2001. All rights reserved. 28


3/8/2012
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 shouldnt 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 shouldnt 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. 29


3/8/2012

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: Description:

From The name of the node making the request.

Password The requesting nodes password.

MessageName The name of the message.

MessageType The message type. Can be one of Sync, Async, Ping.

MessageVersion The message version.

To The node that the request is being sent to.

FinalDestination The ultimate final destination for the request.

OrigUser The user that originated the request.

OrigNode The node that originated the request.

OrigTimeStamp A timestamp corresponding to when the message was first


created.

NonRepudiation 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 corres pond 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. 30


3/8/2012

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 HTTP 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&MessageNam
e=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 HTTP 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.

PeopleSofts 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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 31


3/8/2012

Message Credentials in the body of the HTTP POST

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.

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 HTTP 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 a re
running.

Copyright PeopleSoft Corporation 2001. All rights reserved. 32


3/8/2012
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:

Local Message &request, &response;

&request = GetMessage();

REM Now we could manipulate the request message. However in this case;
REM well 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>

Copyright PeopleSoft Corporation 2001. All rights reserved. 33


3/8/2012
<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.

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:

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. 34


3/8/2012

Property Description

HTTPPROPERTY;Method This is the type of HTTP request being made.


Values are GET or POST.

PRIMARYURL; URL 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.

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 HTTP 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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 35


3/8/2012

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.

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>

Copyright PeopleSoft Corporation 2001. All rights reserved. 36


3/8/2012
<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 serve r
specified by the URL. Since this POST is meaningless to Yahoos 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 SendMas ter:
<?xml version="1.0"?>
<IBResponse type="error">
<DefaultTitle>Integration Broker Response</DefaultTitle>
<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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 37


3/8/2012
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. 38


3/8/2012

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 speci fic 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>
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. 39


3/8/2012

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 proc essed by PeopleCode.
The PeopleCode will build a SOAP response message, and this will be returned to the requestor.

Copyright PeopleSoft Corporation 2001. All rights reserved. 40


3/8/2012
Example Specific Setup

1) 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.

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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 41


3/8/2012
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.

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:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<StockQuoteResponse>
<symbol>PSFT</symbol>
<price>278.37</price>

Copyright PeopleSoft Corporation 2001. All rights reserved. 42


3/8/2012
</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.

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:

Copyright PeopleSoft Corporation 2001. All rights reserved. 43


3/8/2012
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. 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>

Copyright PeopleSoft Corporation 2001. All rights reserved. 44


3/8/2012

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. 45


3/8/2012

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

FTP Connector Properties

There are several connector properties used for outgoing FTP requests:

Property Name Description

HOSTNAME 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.

USERNAME This is the username for the account on the remote FTP server. This is a mandatory
property.

PASSWORD This is the password for the account on the remote FTP server. This is a mandatory
property.

FILENAME 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 Originating Node + "_" +
the Originating User + "_" +
the Message Name + "_" +
the Originating Timestamp + ".ftp"
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 servers default directory will
be used.

Copyright PeopleSoft Corporation 2001. All rights reserved. 46


3/8/2012

sendUncompressed 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.

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 FTP 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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 47


3/8/2012
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.]]></Dat a>
</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. 48


3/8/2012

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: BEAs Weblogic, IBMs MQSeries, and IPlanets 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 ac cess 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 providers 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 mess age 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 propert ies required are:

Property Name Description

ig.jms.XXX The name of the topic or queue. Mandatory.

Copyright PeopleSoft Corporation 2001. All rights reserved. 49


3/8/2012

Property Name Description

ig.jms.XXX.Provider The name of the JMS Provider. Mandatory.

ig.jms.XXX.JMSFactory 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.

ig.jms.XXX.Url JNDI URL to file system.

ig.jms.XXX.User The user name requried to access the JMS


provider. Mandatory.

ig.jms.XXX.Password The password required to access the JMS


provider. Mandatory.

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 messages header and property field values. Messages that match the selector are retrieved, while
those that dont 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 Suns 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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 50


3/8/2012

Incoming Message Fo rmat

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

Property Name Description

MessageName The name of the incoming message. (Required


property)

RequestingNode The name of the requesting node. (Required


property)

Password The users password.

FinalDestinationNode The node that the message is to ultimately be


delivered to. If no final destination, set this to
NULL.

DestinationNodes 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.

ReplyTo True/False. True if the sender wants a reply


generated to the message, False otherwise.

Additionally, the message type of the message must be TextMes sage.

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 providers 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 providers documentation for details.

Copyright PeopleSoft Corporation 2001. All rights reserved. 51


3/8/2012
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 BEAs 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.

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

Copyright PeopleSoft Corporation 2001. All rights reserved. 52


3/8/2012
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

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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 53


3/8/2012
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>

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 Description

JMSAcknowledgement Identifies the Acknowledgement type : Values are

Auto_Acknowledge

Client_Acknowledge

JMSDeliveryMode Identifies Durable or Non-Durable delivery. Values are

Persistent

Non-Persistent

Copyright PeopleSoft Corporation 2001. All rights reserved. 54


3/8/2012

Property Name Description

JMSFactory Identifies the Queue/Topic Connection Factory name.

JMSMessageTimeToLive 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 JMS User name

JMSPassword JMS Provider Password

JMSPriority Identifies the priority of JMS Message

JMSProvider Identifies JMS Provider name. Values are :

Mqseries, Weblogic, iPlanet.

JMSReplyTo True If it is Request/Reply.

False Not a Request/Reply.

JMSTopic Name of the Topic to Publish the message

JMSQueue Name of the Queue to put the message.

JMSMessageTypeClass Identifies the implementation of ProcessJMSMessage.


You must set this property when the JMSMessage type
is anything other that Text.

JMSUrl JNID URL to file system.

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 providers documentation for details.
Configuration of a JMS provider may not be a trivial exercise, so care must be tak en 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 BEAs 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. 55


3/8/2012
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

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

Copyright PeopleSoft Corporation 2001. All rights reserved. 56


3/8/2012
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

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 t ext 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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 57


3/8/2012
10) Check the gateway message log to see the messages exchanged between the gateway, application se rver, and
the JMS provider.

Copyright PeopleSoft Corporation 2001. All rights reserved. 58


3/8/2012

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

SMTP Connector Properties

Property Name Description

DEST_EMAIL The email address to send the message to. Multiple addresses are not supported. This
is a mandatory property.

SOURCE_EMAIL 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.

CC The email address listed here will receive a carbon copy of the email. Multiple
addresses are not supported. This is an optional parameter.

BCC The email address listed here will receive a blind carbon copy of the email. Multiple
addresses are not supported. This is an optional parameter.

CONTENT_TYPE 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.

sendUncompressed 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 gateways 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

Copyright PeopleSoft Corporation 2001. All rights reserved. 59


3/8/2012
To: thirdParty@external.org
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 SMTP Request

If the email message is sent out successfully, the connector will return an internal response message with the s tatus
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 servers 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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 60


3/8/2012
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.

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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 61


3/8/2012
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 targets SMTP server, it may take several seconds ( or minutes! ) for the email to
be delivered.

Copyright PeopleSoft Corporation 2001. All rights reserved. 62


3/8/2012

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 Description

Server The name of the POP3 mail server. This is a mandatory field.

User The userid for the email account on the server. This is a mandatory field.

Password The password for the email account on the server. This is a mandatory field.

Port This is the port number to connect to on the server. This is a mandatory field. This field defaults
to port 110.

Method Name This is the desired POP3 action to take. This is a mandatory field. The list of names is in the
following table.

Count 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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 63


3/8/2012

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 Description

MessageCount Returns the number of messages available in the account.

ReadAll Gets all the messages in the mailbox on the server.

ReadAndDelete Gets all the messages in the mailbox on the server, and then deletes the
messages from the mailbox.

ReadMessage Reads a specified message from the mailbox.

DeleteMessage Deletes a specified message from the mailbox.

ReadHeaders Gets the headers for all the available messages in the mailbox.

ReadHeadersWithAttach Gets the headers and attachment information for all the available messages in
the mailbox.

ReadMessageWithAttach 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 Request Message Name Response Message Name

Message Count EMAIL_REQ_MSGCOUNT EMAIL_RES_MSGCOUNT

ReadAll EMAIL_REQ_READALL EMAIL_RES_READALL

ReadAndDelete EMAIL_REQ_READDELALL EMAIL_RES_READDELALL

ReadMessage EMAIL_REQ_READMSG EMAIL_RES_READMSG

Copyright PeopleSoft Corporation 2001. All rights reserved. 64


3/8/2012

Method Name Request Message Name Response Message Name

DeleteMessage EMAIL_REQ_DELMSG EMAIL_RES_DELMSG

ReadHeaders EMAIL_REQ_READHDR EMAIL_RES_READHDR

ReadHeadersWithAttach EMAIL_REQ_READHDRATT EMAIL_RES_READDHRATT

ReadMessageWithAttach EMAIL_REQ_READMSGATT 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 Description

EMAIL_FROM The address that the email was sent from.

EMAIL_SENDER The address that replies to the message should be sent to.

UIDL The ID of the message on the server.

WL_SUBJECT The subject line of the message.

EMAIL_TEXTLONG The text of the message.

DATE_FROM The date that the email was received.

NUMROWS The count of messages found.

Copyright PeopleSoft Corporation 2001. All rights reserved. 65


3/8/2012

Field Name Description

NOTIFY_TO The list of addressess on the TO: list in the email.

NOTIFY_CC The list of addresses in the CC: list in the email.

The EMAIL_RES_READMSGATT has an additional child record used to capture attachment information:
EMAIL_ATT_WRK.

Field Name Description

EMAIL_TEXTLONG The text of the attachment.

CONTENT_TYPE The content-type of the attachment.

FILENAME The name of the file.

FILE_DATA This is used when the data is of type binary. The actual data will be in this field.

The PT_EMAIL_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 t ransactions 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 us ing 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;

Copyright PeopleSoft Corporation 2001. All rights reserved. 66


3/8/2012

&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).Value;

REM str now contains the the number of email messages for the account on the POP3 server;

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).Value =
"the_email_account_password";
&request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.METHODNAME).Value =
"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

Copyright PeopleSoft Corporation 2001. All rights reserved. 67


3/8/2012

&str =
&response.GetRowset().GetRow(1).GetRecord(Record.EMAIL_RES_WRK).GetField(Field.NUMROWS).Value;

REM str now contains the number of email messages in the account on the POP3 server;

End-If;

ReturnToServer(&response);

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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 68


3/8/2012
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

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>

Copyright PeopleSoft Corporation 2001. All rights reserved. 69


3/8/2012
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"/>
<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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 70


3/8/2012

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. Its 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.

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 isnt 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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 71


3/8/2012
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).Value
= 1;
&request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.SERVER).Valu
e = "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).Va
lue = "the_email_account_password";
&request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.METHODNAME).
Value = "ReadAll";
&request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.PORT).Value
= 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.

Copyright PeopleSoft Corporation 2001. All rights reserved. 72


3/8/2012
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 message has been sent, a response message will be generated and sent back t o 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"/>

Copyright PeopleSoft Corporation 2001. All rights reserved. 73


3/8/2012
<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. 74


3/8/2012

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 doc umentation.

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. 75


3/8/2012

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. 76


3/8/2012

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. 77


3/8/2012

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

Copyright PeopleSoft Corporation 2001. All rights reserved. 78


3/8/2012

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)

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 Co nnector

1. Use JMS Providers Administrative tool to Bind Connection factories, Topics and Queues.

2. Please uncomment the following line in the integrationgateway.properties file

Copyright PeopleSoft Corporation 2001. All rights reserved. 79


3/8/2012
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

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. 80


3/8/2012
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. 81


3/8/2012
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/com.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/ja
va/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. 82
3/8/2012
JMSReplyTo

Add the property name JMSQueue

FAQs 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 Applica tion 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 nee d 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. 83


3/8/2012

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 t ype
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 conne ctor
properties. These connector properties can be overided at Transaction level too. All JMS Listening Conenctor properties are s et
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. 84


3/8/2012
2.

Copyright PeopleSoft Corporation 2001. All rights reserved. 85

S-ar putea să vă placă și