Documente Academic
Documente Profesional
Documente Cultură
Integration Broker
Contains:
Prepared by:
T IT LE OF P AP E R
3 /8 /2 0 1 2
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
4
3/8/2012
Field Validation........................................................................................................................................ 76
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.
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
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
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:
FTPTargetConnector allows the retrieval of files from a File Transfer Protocol (FTP) server
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.
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.
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.
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.
Credentials are discussed in more detail in the section Credentials on page 12.
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.
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.
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.
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.
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.
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.
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
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.
When the MIME request is received by the PeopleSoftListeningConnector, it is written to the gateway log file.
The connector then examines the request to determine what TargetConnector the request is to be sent to; that
TargetConnector is then invoked.
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.
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.
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.
A response object is built out of the MIME response, and is returned to the routine that created the request.
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.
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.
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"/>
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.
3 Unless they decide to integrate directly to the PeopleSoft Listening or Target Connectors.
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.
------=_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
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):
<?xml version="1.0"?>
<IBInfo>
<MessageName><![CDATA[EXAMPLE_REQUEST_MESSAGE]]></MessageName>
<MessageType>sync</MessageType>
<TransactionID><![CDATA[]]></TransactionID>
<From>
<RequestingNode><![CDATA[QE_LOCAL]]></RequestingNode>
<Password><![CDATA[]]></Password>
<DN><![CDATA[]]></DN>
<OrigUser><![CDATA[]]></OrigUser>
<OrigNode><![CDATA[]]></OrigNode>
<OrigProcess><![CDATA[]]></OrigProcess>
<OrigTimeStamp>2001-11-13T11:06:22.142-0800</OrigTimeStamp>
</From>
<To>
<DestinationNode><![CDATA[TARGETNODE]]></DestinationNode>
<FinalDestinationNode><![CDATA[]]></FinalDestinationNode>
</To>
<QStrArgs/>
<Cookies><![CDATA[]]></Cookies>
<PathInfo><![CDATA[/PSIGW/PeopleSoftListeningConnector]]></PathInfo>
<ContentSections>
<ContentSection>
<ID>ContentSection0</ID>
<NonRepudiation>N</NonRepudiation>
<Headers>
<version><![CDATA[VERSION_1]]></version>
</Headers>
</ContentSection>
</ContentSections>
<InternalInfo>
<AppMsg>
<PublishingNode><![CDATA[]]></PublishingNode>
<Channel><![CDATA[]]></Channel>
<SubChannel><![CDATA[]]></SubChannel>
<DefaultDataVersion>VERSION_1</DefaultDataVersion>
<VisitedNodes><![CDATA[|QE_LOCAL|]]></VisitedNodes>
<PublicationID></PublicationID>
</AppMsg>
</InternalInfo>
<Connector>
<ConnectorName><![CDATA[HTTPTARGET]]></ConnectorName>
<ConnectorClassName><![CDATA[HttpTargetConnector]]></ConnectorClassName>
<RemoteFrameworkURL><![CDATA[]]></RemoteFrameworkURL>
<ConnectorParameters>
<ConnectorParam>
<Name><![CDATA[Method]]></Name>
<Value><![CDATA[POST]]></Value>
</ConnectorParam>
<ConnectorParam>
<Name><![CDATA[URL]]></Name>
<Value><![CDATA[http://www.externalsystem.com/serlvet]]></Value>
</ConnectorParam>
</ConnectorParameters>
<ConnectorHeaders>
<Header>
<Name><![CDATA[sendUncompressed]]></Name>
<Value><![CDATA[Y]]></Value>
</Header>
</ConnectorHeaders>
</Connector>
</IBInfo>
While the basic structure is the same for all requests, not all elements are always required. An example of 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 / MessageType This is the type of the message. Currently, there are three
types: async, sinc, and ping.
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 / 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 / QStrArgs Specific to incoming HTTP requests. These are the query
string parameters found when the request was received
by the HTTPListeningConnector.
Element Description
IBInfo / ContentSections / ContentSection This node provides metadata about the text present in the
ContentSection.
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 / 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.
MIME
Internal response messages have the same basic MIME structure as request messages.
------=_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"?>
<TestXml>This is a sample response message.</TestXml>
------=_Part_4_7210339.1008355101202--
There are two logical components to a MIME response message: the IBInfo and the Content Section.
IBInfo XML
The format for the XML for the IBInfo for a response message is different than that for the request message. The
following is a sample:
<?xml version="1.0"?>
<IBInfo>
<Status>
<StatusCode>0</StatusCode>
<MsgSet>158</MsgSet>
<MsgID>10000</MsgID>
<DefaultMsg>OK</DefaultMsg>
<DefaultTitle>Integration Broker Response Message</DefaultTitle>
</Status>
<ContentSections>
<ContentSection>
<ID>ContentSection0</ID>
<NonRepudiation>N</NonRepudiation>
</ContentSection>
</ContentSections>
</IBInfo>
The following is the list of all the elements that may be present in the IBInfo for a response:
Element 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.
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.
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.
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.
------=_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:
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.
A mechanism is provided to manipulate the data in content sections; these are called transforms.
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.
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 .
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.
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.
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.
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.
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.
select File->Save as. Enter EXAMPLE_REQUEST_MESSAGE in the message box and click Ok.
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.
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.
From PIA :
From PIA:
From PIA:
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.
The Transaction Detail page will appear. Ensure that the Status is set to Active. Click on the Messages tab.
From PIA:
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.
The Transaction Detail page will appear. Ensure that the Status is set to Active. Cli ck on the Messages tab.
From PIA:
Click on Relationships. The Relationships page will appear in the right frame of the browser.
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 ID and the Effective date fields will be filled out. These values shouldnt be changed.
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.
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.
Name: Description:
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.
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.
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.
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
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.
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.
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.
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.
<?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>
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.
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.
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:
&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);
6) Start up a web browser and access the PIA page for the Integration Broker.
7) Select Relationships
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.
1) Start up SendMaster.
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
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>
After a brief delay, a response looking like the following will be returned to SendMaster:
2) Check the gateway message log to see the messages exchanged between the gateway and the application
server.
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
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.
Property Description
Example:
http://www.someserver.com
http://127.0.0.1
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.
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.
Assuming that the HTTP Request was successfully received and handled by the target destination, a response will be
returned to the HttpListeningConnector. The connector will then build an IB internal response message and will add
the text returned to the content section of this message. The message will be returned back to the application server.
However, if the HTTP Request was not successfully processed by the target and the HTTP status code returned is
other than 200 the connector will build an IB internal error response message, and will return this back to the
application server. Any text returned in conjunction with an error will not be included in this response message, but will
be visible in the message log.
If the connector is unable to send the request to the target destination due to a bad URL or the target server being
down, an IB internal error message will be created with the appropriate error code and this will be propagated back to
the application server.
Example
This example builds on the scenario used for the listening connector. Instead of the target of the message being
PeopleCode on the application server, the incoming sync message will be routed out of the app server back to the
gateway, where it will be posted to a third party web server. In addition, the post to the external server will be done in a
way so as to cause a processing error to occur on the third party system. This will show how error messages are
created and propagated back through the broker.
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.
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.
1) Start up SendMaster.
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
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>
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 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.
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.
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.
SOAP requests are handled by the HTTPListeningConnector. No special configuration of the connector is required to
receive such messages.
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.
<?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.
The format for SOAP error responses differs slightly from normal SOAP responses:
</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.
1) Start up a web browser and access the PIA page for the Integration Broker.
Select Relationships.
On the resulting page, set the Status of the modifier to Inactive, and click Save.
Select the OnRequest event, and paste the following code into the window:
&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);
1) Start up SendMaster.
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
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>
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.
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.
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.
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.
1) Start up SendMaster.
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:
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:
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.
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.
There are several connector properties used for outgoing FTP requests:
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.
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.
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.
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.
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.
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.
2) Start up SendMaster.
http://127.0.0.1/PSIGW/HttpListeningConnector
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.
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.
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.
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:
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.
In order to be processed by the connector, the published message must contain the following properties in the JMS
Message header:
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.
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.
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.
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 Shutdown Topic:
ig.jms.shutdown.Provider=Weblogic
ig.jms.shutdown.JMSFactory=TopicConnectionFactory
ig.jms.shutdown.Url=t3://localhost:80
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:
4) Start up a web browser and access the PIA page for the Integration Broker.
Select Relationships.
On the resulting page, set the Status of the modifier to Inactive, and click Save.
Select the OnRequest event, and paste the following code into the window:
&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.
1) Publish a JMS message with the following characteristics to the SampleTopic topic:
MessageName = EXAMPLE_REQUEST_MESSAGE
RequestingNode = SOURCENODE
<?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.
The JMSTargetConnector is responsible for publishing JMS messages to topics and queues.
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.
Auto_Acknowledge
Client_Acknowledge
Persistent
Non-Persistent
Text,Map,Object Message
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.
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.
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.
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
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.
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
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.
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.
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.
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:
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.
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.
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.
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
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.
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.
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.
There are several properties present when defining a POP3 connection for a given node. They are:
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.
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:
ReadAndDelete Gets all the messages in the mailbox on the server, and then deletes the
messages 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.
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 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.
EMAIL_SENDER The address that replies to the message should be sent to.
The EMAIL_RES_READMSGATT has an additional child record used to capture attachment information:
EMAIL_ATT_WRK.
FILE_DATA This is used when the data is of type binary. The actual data will be in this field.
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:
&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:
&request = CreateMessage(Message.EMAIL_REQ_MSGCOUNT);
&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
&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);
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.
Connector properties for the POP3TargetConnector can be set in three different locations:
2) as an override on the transaction for the particular POP3 message being used
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.
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.
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.
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.
1) Start up SendMaster.
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
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
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.
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.
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.
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.
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.
Select the OnRequest event, and paste the following code into the window
&request = CreateMessage(Message.EMAIL_REQ_READALL);
&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.
1) Start up SendMaster.
http://127.0.0.1/PSIGW/HttpListeningConnector
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"/>
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.
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.
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.
Java Message Service makes it easy to write business application that asynchronously/synchronously send and
receive critical business data and events.
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.
4. Administered objects are preconfigured JMS Objects created by administrator for the use of clients.
1. Use JMS Providers Administrative tool to Bind Connection factories, Topics and Queues.
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.
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.
ig.jms.JMSProvider.JNDIFactory.MQSeries=com.sun.jndi.fscontext.RefFSContextFactory
3. Set up the connector properties at the node level/transaction level for JMS Target Connector. (Set up the
ReplyTp property as True for receiving Reply and set up WaitForResponse for waiting time of response)
4. JMS Target Connector uses connector properties and looks up JNDI name space for Connection factory
or Topic or Queue.
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.
1. Use JMS Providers Administrative tool to Bind Connection factories, Topics and Queues.
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
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.
7. Starts Queue Listeners and Topic Subscribers for different Queues and Topics.
INSTALL MQ
Install MA 88 Plug-In (For MQ5.2 and older versions download from www.ibm.com)
Change the JMSADMIN.config using any editor and uncomment the following line
INITIAL_CONTEXT_FACTORY = com.sun.jndi.ldap.RefFSContextFactory
INITIAL_CONTEXT_FACTORY = com.sun.jndi.ldap.LdapCtxFactory
You also can use IVTSetup file to setup different connection factories, Topics and Queues.
Configure WebSphere
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
Change web.xml file for JNDI Settings and ibm-web-bnd.xmi for resource bindings.
JMSFactory
JMSPassword
JMSUserName
JMSUrl
Copyright PeopleSoft Corporation 2001. All rights reserved. 82
3/8/2012
JMSReplyTo
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
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.
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)
Authors
Reviewers
<names>
Revision History
1. <Date>: Created document.