Professional Documents
Culture Documents
Contains:
√
√
√
√
√
√ Prepared by:
T H I R D P A R T Y I N T E G R AT I O N
U S I N G T H E I N T E G R AT I O N
BROKER
4/10/2009
When you send information to PeopleSoft, you grant PeopleSoft a non-exclusive right to use
or distribute the information in any way it believes appropriate without incurring any
obligation to you.
4/10/2009
This material has not been submitted to any formal PeopleSoft test and is published AS IS. It
has not been the subject of rigorous review. PeopleSoft assumes no responsibility for its
accuracy or completeness. The use of this information or the implementation of any of these
techniques is a customer responsibility and depends upon the customer's ability to evaluate
and integrate them into the customers operational environment.
3
Table of Contents
4
4/10/2009
Basic Setup for the Examples...................................................................................................23
Add a Message Channel............................................................................................................................................................23
Add a Request Message.............................................................................................................................................................23
Add a Response Message...........................................................................................................................................................24
Add the Source Node.................................................................................................................................................................24
Add the Target Node..................................................................................................................................................................24
Add the Source Transaction.......................................................................................................................................................25
Add the Target Transaction........................................................................................................................................................26
Add the Relationship and Transaction Modifier.......................................................................................................................26
Integrating using HTTP..............................................................................................................28
HTTP Message Credentials........................................................................................................................................................28
Sending HTTP requests to the Integration Broker....................................................................................................................29
HTTP requests from the Integration Broker to external systems..............................................................................................32
HTTP Cookies............................................................................................................................................................................35
SSL Considerations....................................................................................................................................................................35
Integrating using SOAP..............................................................................................................36
Sending SOAP requests to the Integration Broker....................................................................................................................36
SOAP requests out of the Integration Broker............................................................................................................................40
Integrating using FTP.................................................................................................................42
FTP requests from the Integration Broker to external systems.................................................................................................42
Integrating using JMS................................................................................................................45
Receiving Published JMS Messages .........................................................................................................................................45
Publishing JMS Messages ........................................................................................................................................................50
Integrating using SMTP..............................................................................................................54
Sending email from the Integration Broker to external systems...............................................................................................54
Integrating using POP3..............................................................................................................58
5
4/10/2009
Chapter 1 - Introduction
This Red Paper is a practical guide for technical users, installers, system administrators, and programmers who
implement, maintain, or develop applications for your PeopleSoft system. In this Red Paper, we discuss
guidelines on how to use the Integration Broker and the Connectors on the Gateway in order to integrate the broker
with third party systems.
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
gateway isolates the application server from the various communication protocols that can be used to access it.
The gateway also normalizes all incoming requests so that by the time they reach the applications server, they are
in a standard format. Similarly, it also converts requests being sent out of the application server from the standard
to a format suitable for the outgoing protocol being used.
Although the gateway is comprised of many different classes, two broad types are of interest here: Listening
Connectors and Target Connectors.
Listening Connectors are used to “listen” for incoming requests from external systems. These connectors provide
the point of entry for external systems into the integration broker, and such systems directly access these
connectors in order to send requests. Each connector is responsible for normalizing the incoming protocol
dependant request before it is sent on to the application server.
Listening Connectors are protocol specific. The following listening connectors are currently available:
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
PeopleSoft
External Listening 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.
A message without credentials cannot be processed. If the gateway receives such a message an error will occur
and an error message will be returned to the requestor.
Credentials are discussed in more detail in the section “Credentials” on page 12.
1 The gateway’s integration properties file is used to set the logging level, which controls what is actually written to
the log. If messages are not being seen in the log file, check to ensure that the log level is set correctly.
© Copyright PeopleSoft Corporation 2001. All rights reserved. 8
4/10/2009
In order for a message to be sent from the gateway to the application server, it must pass through the
PeopleSoftTargetConnector. This connector has two major responsibilities: it serializes the message to a string,
and sends that string via a JOLT connection to the app server.
All communication between the gateway and the app server is done via the use of Multipurpose Internet Mail
Extensions (MIME) messages. When the message is received by the connector, it builds a MIME message.
Typically the MIME message will only have two sections. In the first, the message credentials are stored in an XML
document in a specific format. The second section stores the message body.
At this point the message is in a standard format understood by both the gateway and the application server. All
messages must eventually resolve to this format before they can be sent to the app server for processing. This
format effectively isolates the app server from the protocols supported by the gateway; there is no information
present about what listening connector was initially invoked by the external request.2
Once the MIME message has been built, it is written to the gateway log.
Finally, the connector looks up the JOLT connection properties from the integration properties file and attempts to
send the MIME to the application server. If these properties are not set up correctly, the gateway will be unable to
send requests. This is a common source of error, so care should be taken when configuring this file.
An important point to keep in mind is that even though the MIME request to the appserver may appear in the
gateway log file, the actual request may not have made it to the app server, since the log entry is written before
the message is sent. If a communication error occurs, the entry will still be present in the log file. However, if this
situation occurs an exception will be thrown and an error log entry will also be created.
When the MIME request is received by the application server, the message is parsed and is used to build a
request object. The MIME structure is not propagated into the server.
Assuming the message parses without error, the application server must pre-process the message before the
request can actually be handled.
Pre-processing involves:
• authenticating the message, depending on the authentication scheme configured. If the request fails
authentication, an error is returned.
• determining if there is a transaction corresponding to the request in the Node Transaction table. Aside
from Ping messages, all incoming messages must resolve to a single, unique entry in this table. If a
suitable transaction cannot be found for a request, an error occurs.
• determining the message handler to invoke. Currently, there are three message types supported by
the integration broker: Ping, Synchronous, and Asynchronous. The message type determines the
handler code to invoke. Synchronous messages are passed to sync-specific code, and async
messages are passed to the publish/subscribe subsytem.
Once messages have been passed to their respective handlers, further processing is dictated by the data and
PeopleCode specific to a particular system. Async requests will be published, and subscription PeopleCode will be
2 This is not entirely true. One credential element that may be present is the one for “Cookies”. Obviously if this is
set, the app server would be right in assuming that the request came through the HTTP ListeningConnector.
Similarly, SOAP requests are passed into the app server in SOAP format. However, as a general rule the app
server is isolated from the details of the protocol and the general broker code on the server does not care what
listening connector was used for a given request.
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 processing of the request.
A response cannot be generated until the message runs to completion. There may be a noticable delay in
receiving the response, depending if PeopleCode is being run or if the request message is being sent out of the
broker to an external system for additional processing.
Asynchronous requests behave differently. Unlike sync requests, there is no blocking. A response is generated for
an asynchronous request as soon as the request is written to the publication queue. Because of this, a response
generated for an asynchronous request is not a response in the strictest sense of the term. Such responses should
really be considered acknowledgments that the pub/sub system has received the message. Receipt of such a
response is not a guarantee that any applicable subscription PeopleCode has been successfully run.
Response messages are converted to the MIME standard by the app server, and are returned to the gateway.
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 messages is
done synchronously. A request is received by a ListeningConnector which then coverts it to a suitable format,
makes a blocking call to the gateway to handle the message, and ultimately gets a response back all in the same
thread of execution.
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 Target External
Server Listening 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 MIME’d response is then written to the gateway log file, and is then returned to the app server.
Again, it should be emphasized that interactions with the gateway are always synchronous. If a request is sent to
the gateway, a response should be expected.
Step 2 is an HTTP POST request made of the gateway, and the response created here in Step 5 is returned in the
response to that HTTP request. The HTTP connection is open for the duration of the processing for that request.
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. Messages
received without such info will be rejected and will result in errors being thrown.
1. Requesting Node – this is the name of the node sending the request to the local Integration Broker
2. Message Name – the name of the message being sent. This can also be an “external message” name.
Without these elements, the broker will be unable to lookup the associated transaction in the system for the
request. When such messages are received explicit error messages will be returned.
Other elements may be also necessary, depending on circumstance. For example, if password authentication is
being done for a specific requesting node, then the requests must also include this information as well.
All requests must be able to be resolved to a single transaction in the node transaction table – PSNODETRX.
Although this is not a requirement, it is advantageous for incoming messages to also specify the transaction type
and the message version. If this information is not included, the integration broker must go to the transaction table
and attempt to find a transaction that matches the requesting node and message name given in the request
If the request message explicitly includes the requesting node, message name, transaction type and version it is
relatively easy for an administrator to verify as to whether a matching transaction exists in the system.
Message Body
The requirements for the message body depend on how the request is being used.
As far as the infrastructure of the integration broker is concerned, the only requirements on the message body be
that is is composed of text. Binary cannot be directly handled by the system. However a way around this is to
encode the binary in a BASE64 string. Since such a string is simply composed of ASCII text, the string can be
transported like any other text.
In fact, this is commonly done in the system for asynchronous messages that are sent between two different
PeopleSoft nodes. Such messages can be quite large, and it is desireable to make the message as small as
possible to reduce strain on the system. Before the outgoing request is built, the pub/sub system takes the XML
and compresses it. The result of this is a binary ZIP stream. This stream is then BASE64 encoded, and is added to
the outgoing request. The receiving PeopleSoft system reverses the procedure: upon receipt of the message the
message body is BASE64 decoded, unzipped, and the resulting XML is then processed. The BASE64 message
bodies can be seen being transported across gateways by looking at the appropriate gateway logs.
In reality arbitrary data encoded in the message body is really only a possibility when the integration broker is
being used as a hub between two third party systems. If the eventual target of the request is a PeopleSoft system,
there are further requirements on the content of the body.
If the ultimate target of the message is a PeopleSoft system, the message body must be XML, and must conform
to a specific standard. The following is an example of that standard:
<?xml version='1.0'?>
<EXAMPLE_REQUEST_MESSAGE>
<FieldTypes>
<EXAMPLE_ITEM class="R">
<EX_MANUFACTURER type="CHAR"/>
<EX_MODEL type="CHAR"/>
<EX_SKU type="CHAR"/>
<EX_COST type="CHAR"/>
</EXAMPLE_ITEM>
<PSCAMA class="R">
<LANGUAGE_CD type="CHAR"/>
<AUDIT_ACTN type="CHAR"/>
<BASE_LANGUAGE_CD type="CHAR"/>
<MSG_SEQ_FLG type="CHAR"/>
<PROCESS_INSTANCE type="NUMBER"/>
<PUBLISH_RULE_ID type="CHAR"/>
<MSGNODENAME type="CHAR"/>
</PSCAMA>
</FieldTypes>
<MsgData>
<Transaction>
<EXAMPLE_ITEM class="R">
<EX_MANUFACTURER>Ford</EX_MANUFACTURER>
<EX_MODEL>Mustang GT Cobra</EX_MODEL>
<EX_SKU>FRD23397GC</EX_SKU>
<EX_COST>26459.90</EX_COST>
</EXAMPLE_ITEM>
<PSCAMA class="R">
<LANGUAGE_CD></LANGUAGE_CD>
<AUDIT_ACTN></AUDIT_ACTN>
<BASE_LANGUAGE_CD>ENG</BASE_LANGUAGE_CD>
<MSG_SEQ_FLG></MSG_SEQ_FLG>
<PROCESS_INSTANCE>0</PROCESS_INSTANCE>
<PUBLISH_RULE_ID></PUBLISH_RULE_ID>
<MSGNODENAME></MSGNODENAME>
</PSCAMA>
</Transaction>
</MsgData>
</EXAMPLE_REQUEST_MESSAGE>
The root node of the document is the name of the corresponding message in the message table, in this case the
EXAMPLE_REQUEST_MESSAGE.
Under the “FieldTypes” node, the next element is the name of the child record for this particular version of the
message: EXAMPLE_ITEM. Under EXAMPLE_ITEM is a list of nodes that describe each field in the record.
Under the “MsgData” and “Transaction” nodes is the actual data in the request. The next node is the name of the
child record of the message, followed by the list of all the field names with concrete values for each.
For further information about this standard, please refer to the Integration Broker PeopleBook.
1) all incoming requests must eventually be able to be mapped into this format before they can be
processed by the app server.
2) messages using the internal format will show up in the gateway log file. Since the log file is a valuable
tool for debugging, anyone reading the file will need to understand how the messages are structured.
MIME
The Multipurpose Internet Mail Extension standard (MIME) is used as the basic structure for internal messaging.
MIME has several advantages in that the standard is well known and supported, and because it is text based it is
human readable and easily serializable.
3 Unless they decide to integrate directly to the PeopleSoft Listening or Target Connectors.
© Copyright PeopleSoft Corporation 2001. All rights reserved. 14
4/10/2009
Message-ID: <5722340.1008266844175.JavaMail.MNowosel@MNOWOSEL071900>
Date: Thu, 13 Dec 2001 10:07:24 -0800 (PST)
Mime-Version: 1.0
Content-Type: multipart/related;
boundary="----=_Part_5_7190308.1008266838787"
Content-ID: PeopleSoft-Integration-Broker-Internal-Mime-Message
------=_Part_5_7190308.1008266838787
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-Disposition: inline
Content-ID: IBInfo
<?xml
version="1.0"?><IBInfo><MessageName><![CDATA[EXAMPLE_REQUEST_MESSAGE]]></MessageName><MessageType>sync</MessageType>
<From><RequestingNode><![CDATA[SOURCENODE]]></RequestingNode><OrigTimeStamp>2001-11-13T10:07:18.817-
0800</OrigTimeStamp></From><PathInfo><![CDATA[/PSIGW/PeopleSoftListeningConnector]]></PathInfo><ContentSections><ContentSection><I
D>ContentSection0</ID><NonRepudiation>N</NonRepudiation></ContentSection></ContentSections></IBInfo>
------=_Part_5_7190308.1008266838787
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-Disposition: inline
Content-ID: ContentSection0
<?xml version="1.0"?>
<TestXml>This is a sample request message.</TestXml>
------=_Part_5_7190308.1008266838787—
The first part of the message contains the MIME headers, which describe the attributes of the whole message.
Next is the IBInfo – or “Integration Broker Information” – section. The IBInfo contains the credentials of the request
as well as all other information required by the broker to process the message. The IBInfo for a request has a
specific XML structure which is used for all request messages in the system, regardless if the message is being
sent to the app server or to the gateway.
The final section contains the message body of the original request. This is the payload and is what ultimately will
be delivered to the message’s final destination. This is the “Content Section”.
IBInfo XML
The following is an example of the IBInfo for a request message that was sent from the app server to the gateway
(formatted for easier reading):
<?xml version="1.0"?>
<IBInfo>
<MessageName><![CDATA[EXAMPLE_REQUEST_MESSAGE]]></MessageName>
<MessageType>sync</MessageType>
<TransactionID><![CDATA[]]></TransactionID>
<From>
<RequestingNode><![CDATA[QE_LOCAL]]></RequestingNode>
<Password><![CDATA[]]></Password>
<DN><![CDATA[]]></DN>
<OrigUser><![CDATA[]]></OrigUser>
<OrigNode><![CDATA[]]></OrigNode>
<OrigProcess><![CDATA[]]></OrigProcess>
<OrigTimeStamp>2001-11-13T11:06:22.142-0800</OrigTimeStamp>
</From>
<To>
<DestinationNode><![CDATA[TARGETNODE]]></DestinationNode>
<FinalDestinationNode><![CDATA[]]></FinalDestinationNode>
</To>
<QStrArgs/>
<Cookies><![CDATA[]]></Cookies>
<PathInfo><![CDATA[/PSIGW/PeopleSoftListeningConnector]]></PathInfo>
<ContentSections>
<ContentSection>
<ID>ContentSection0</ID>
<NonRepudiation>N</NonRepudiation>
<Headers>
<version><![CDATA[VERSION_1]]></version>
</Headers>
</ContentSection>
</ContentSections>
<InternalInfo>
<AppMsg>
<PublishingNode><![CDATA[]]></PublishingNode>
<Channel><![CDATA[]]></Channel>
<SubChannel><![CDATA[]]></SubChannel>
<DefaultDataVersion>VERSION_1</DefaultDataVersion>
<VisitedNodes><![CDATA[|QE_LOCAL|]]></VisitedNodes>
<PublicationID></PublicationID>
</AppMsg>
</InternalInfo>
<Connector>
<ConnectorName><![CDATA[HTTPTARGET]]></ConnectorName>
<ConnectorClassName><![CDATA[HttpTargetConnector]]></ConnectorClassName>
<RemoteFrameworkURL><![CDATA[]]></RemoteFrameworkURL>
<ConnectorParameters>
<ConnectorParam>
<Name><![CDATA[Method]]></Name>
<Value><![CDATA[POST]]></Value>
</ConnectorParam>
<ConnectorParam>
<Name><![CDATA[URL]]></Name>
<Value><![CDATA[http://www.externalsystem.com/serlvet]]></Value>
</ConnectorParam>
</ConnectorParameters>
<ConnectorHeaders>
<Header>
<Name><![CDATA[sendUncompressed]]></Name>
<Value><![CDATA[Y]]></Value>
</Header>
</ConnectorHeaders>
</Connector>
</IBInfo>
While the basic structure is the same for all requests, not all elements are always required. An example of this is
the “Connector” section. The Connector XML is used to tell the gateway to route this message to the named target
connector. It also lists configuration parameters for the outbound request. This XML would only be seen in requests
sent from the app server to the gateway. For requests going in the other direction, the section would be empty.
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 / 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.
Element Description
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 / 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.
Message-ID: <2351889.1008355101212.JavaMail.MNowosel@MNOWOSEL071900>
Date: Fri, 14 Dec 2001 10:38:21 -0800 (PST)
Mime-Version: 1.0
Content-Type: multipart/related;
boundary="----=_Part_4_7210339.1008355101202"
Content-ID: PeopleSoft-Integration-Broker-Internal-Mime-Message
------=_Part_4_7210339.1008355101202
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-Disposition: inline
Content-ID: IBInfo
<?xml version="1.0"?><IBInfo><Status><StatusCode>0</StatusCode><MsgSet>158</MsgSet><MsgID>10000</MsgID><DefaultTitle>Integration
Broker Response
Message</DefaultTitle></Status><ContentSections><ContentSection><ID>ContentSection0</ID><NonRepudiation>N</NonRepudiation></ContentS
ection></ContentSections></IBInfo>
------=_Part_4_7210339.1008355101202
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-Disposition: inline
Content-ID: ContentSection0
<?xml version="1.0"?>
<TestXml>This is a sample response message.</TestXml>
------=_Part_4_7210339.1008355101202--
There are two logical components to a MIME response message: the IBInfo and the Content Section.
IBInfo XML
The format for the XML for the IBInfo for a response message is different than that for the request message. The
following is a sample:
<?xml version="1.0"?>
<IBInfo>
<Status>
<StatusCode>0</StatusCode>
<MsgSet>158</MsgSet>
<MsgID>10000</MsgID>
<DefaultMsg>OK</DefaultMsg>
<DefaultTitle>Integration Broker Response Message</DefaultTitle>
</Status>
<ContentSections>
<ContentSection>
<ID>ContentSection0</ID>
<NonRepudiation>N</NonRepudiation>
</ContentSection>
</ContentSections>
</IBInfo>
The following is the list of all the elements that may be present in the IBInfo for a response:
Element Description
IBInfo / Status / StatusCode Describes the result of the request. The status codes
are:
Element Description
0 – Request successfully processed.
10 – Temporary error occurred. Request can be resent.
20 – Fatal error occurred. Do not resend request.
30 – Request message is a duplicate of a message
previously received.
IBInfo / Status / MsgSet The MessageSetNumber for this message in the
Message Catalog. 158 is the message set number
assigned to the Integration Broker.
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 message 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.
The status code describes the nature of the response message. If anything other than “0” is present, an error has
occurred.
All integration broker error messages are stored in the message catalog. A short and long description for every
error can be found there. Catalog entries are given a number, and this number is used in the response messages.
Message-ID: <4328049.1008270392287.JavaMail.MNowosel@MNOWOSEL071900>
Date: Thu, 13 Dec 2001 11:06:32 -0800 (PST)
Mime-Version: 1.0
Content-Type: multipart/related;
boundary="----=_Part_25_2235074.1008270392277"
Content-ID: PeopleSoft-Integration-Broker-Internal-Mime-Message
------=_Part_25_2235074.1008270392277
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-Disposition: inline
Content-ID: IBInfo
<?xml version="1.0"?><IBInfo><Status><StatusCode>10</StatusCode><MsgSet>158</MsgSet><MsgID>10721</MsgID><Parameters
count="1"><Parm>404</Parm></Parameters><DefaultTitle>Integration Gateway Error</DefaultTitle></Status></IBInfo>
------=_Part_25_2235074.1008270392277--
All Integration Broker errors use message set 158. The actual error seen here is 10721.
Going to the message catalog, the description for message set 158, error 10721 is:
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.
Transforms are implemented in the broker by means of the Extensible Stylesheet Language (XSL). A transform
involves running an XSL stylesheet against the text in the content section, with the results of the transform
replacing the original text.
Because XSL is used, there is a restriction on the text in the content section to be transformed – it must be valid
XML. If it is not, the transform will fail. XSL does allow for the creation of non XML documents however, so the
output of the transform need not be XML.
In order to use a transform, a relationship must be defined. Transforms are optional when creating a relationship,
but relationships are the only way that transforms can be invoked. For a given relationship, one transform can be
specified for the request message and a different transform for the response.
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 messages4 sent out of the broker will have the data in their content sections zipped and
BASE64 encoded. This is done in order to reduce the overall size of such messages and reduce strain on the
system. Zipping text reduces the overall size, but the output of the zipping is a binary stream. Since binary is
sometimes difficult to transport, the stream is then BASE64 encoded. This results in a text stream that is larger in
size than the binary stream, but is much smaller than the original text.
If the zipping and encoding were not done, and the data was just normal text inside of the message, encoding
would not be an issue – it would be automatic. UCS2 is used within the app server, but when the message is sent
to the gateway, the message would be converted to the particular flavour of UTF16 used by the Java Virtual
Machine running on the gateway. If the request was being sent out via HTTP, the request might be converted to
UTF8. In such cases, character encoding is handled at the boundaries of the various components automatically.
However, when text is zipped and encoded this is no longer the case. Whatever encoding that the text was in when
zipped, will be the encoding that the text will be in when it is unzipped. The application server will always encode
text to be zipped in UTF8, so any consumers of the message must be able to handle this encoding.
Conversely, if an external system is sending a request into the broker to be processed locally, and the message is
zipped and BASE64 encoded, then the encoding of the characters must be UTF8, otherwise an error will occur.
In certain situations, conversion to or from UTF8 may be a problem for third parties. There are ways around this.
For messages being sent into the broker, simply do not zip and encode the message body. The broker is capable
of handling messages either in “zipped and encoded” or “plain text” format.
For messages being sent out of the broker, there exists a Gateway Connector configuration parameter called
“sendUncompressed”. If this parameter is activated, the gateway will automatically decode and inflate all
messages sent to a particular node. The external party will then receive normal, uncompressed text.
4 Sync messages whose total size is greater than a configurable value set on the application server.
© Copyright PeopleSoft Corporation 2001. All rights reserved. 22
4/10/2009
In this chapter, concrete examples will be given for using the various connectors present on the gateway.
All the examples assume that the integration broker and gateway have been installed correctly. This includes that
the appropriate application servers have been configured and are running. For information on how to install the
basic components, refer to the Integration Broker PeopleBook.
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.
• on the “Message Channel” drop down, select EXAMPLE_CHANNEL and click “Ok.
• select “File”->”Save as…”. Enter EXAMPLE_REQUEST_MESSAGE in the message box and click “Ok.”
• 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”. Click 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 shouldn’t be any.
Click on the “Add Transaction Modifier” button.
• The “Relationship ID” and the “Effective date” fields will be filled out. These values shouldn’t 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 correspond to the
HTTP message credential elements “From” and “MessageName”. Other elements may be required depending on
circumstance.
In the examples in this section, only a subset of these credentials will be used in order to make the examples more
concise.
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&MessageN
ame=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.
PeopleSoft’s SendMaster utility can also be used to test this functionality. SendMaster allows header values to be
set via the “Header” section in the Project Definitions as a name-value pair.
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 are
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 – we’ll 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>
<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>
• 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:
Property Description
Example:
http://www.someserver.com
5Message credentials in the outgoing HTTP request would only theorectically be needed if the message was being
sent to an HTTP Listening connector on a gateway belonging to another integration broker. However, this
configuration is not recommended. If you want to send messages between two brokers, use the
PeopleSoftListening and PeopleSoftTarget connectors instead.
© Copyright PeopleSoft Corporation 2001. All rights reserved. 32
4/10/2009
Property Description
http://127.0.0.1
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>
<ContentSections>
<ContentSection>
<NonRepudiation/>
<Data><![CDATA[This is the body of the request.]]></Data>
</ContentSection>
</ContentSections>
</IBRequest>
• Click the POST button to send the request to the broker. The request will be sent to the gateway, which will
forward it on to the application server, who will then forward it back out to the gateway. The gateway will
attempt to POST the data ( which in this case is the string “This is the body of the request” ) to the server
specified by the URL. Since this POST is meaningless to Yahoo’s server, it will return an error back to the
gateway, which will then propagate back through the system.
• After a brief delay, a response looking like the following will be returned to SendMaster:
<?xml version="1.0"?>
<IBResponse type="error">
<DefaultTitle>Integration Broker Response</DefaultTitle>
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.
If any cookie information is present on a message that is to be sent out by the HttpTargetConnector, the cookie
string will be set on the outgoing HTTP request.
Please note that while cookie information could be set in PeopleCode on a message that will ultimately use a
target connector other than HTTP, the cookie information would be discarded by the connector. Setting and getting
cookies are only valid for HTTP requests.
SSL Considerations
In cases where sensitive information is sent over HTTP, it may be necessary to enable SSL encryption. The
gateway fully supports HTTPS.
In order to use SSL, digital certificates will have to be installed on the web server running the gateway. Once this is
done, the gateway will be able to send and receive HTTPS requests.
Receiving HTTPS requests is pretty much automatic. When the web server gets such a request, it will be
forwarded on to the gateway for processing.
Enabling outgoing HTTPS is not much more complex. Simply define the value for PRIMARYURL;URL to start with
https:// instead of http://. The HttpTargetConnector will then make the necessary SSL connection at runtime.
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 specific 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 processed 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);
This code will take parse the incoming message, looking for “PSFT” in the XML in the body of the
SOAP request. If this is found, a SOAP response is returned with a stock quote. If not found, an error
message is returned.
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>
</StockQuoteResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
2) Check the gateway message log to see the messages exchanged between the gateway and the application
server.
To see an example of a SOAP error message, change the value for “Symbol” in the input XML to a value other
than “PSFT”. The PeopleCode will build and return an error message when the request is received.
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:
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"?>
© Copyright PeopleSoft Corporation 2001. All rights reserved. 40
4/10/2009
<SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlSOAP.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlSOAP.org/soap/envelope/">
<SOAP-ENV:Body>
<GetQuote>
<Symbol>PSFT</Symbol>
</GetQuote>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
• Click the POST button to send the request to the broker. The request will be sent to the gateway, which will
forward it on to the application server. The application server will then send the SOAP request on to the
external party specified.
• However, the external party does not understand the request, and an error message is eventually returned
to SendMaster:
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.
F TP Connector Properties
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.
• 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
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: BEA’s Weblogic, IBM’s MQSeries, and IPlanet’s Message Queue for
Java. The JMS runtime chosen must be installed and configured before the JMS connector can be used.
The JMS connectors differ from the others in the integration broker in that while most connectors provide access to
the broker via a communication protocol, in order to test the interaction with the JMS connectors actual Java code
must be written. Please refer to your JMS provider’s documentation for examples of how to do this.
The JMSListeningConnector starts a thread for each queue or topic specified in the integration properties file.
These threads will listen for newly published messages.
When a message is published to a queue of interest, the connector will retrieve the message and will send it to the
application server. This also occurs when messages are published to topics that the connector is interested in.
The gateway must be configured in order to be able to listen to specific topics and queues. This is done by adding
entries to the integration properties file.
In order to know how many queues and topics that are to be monitored, the following two values must be set:
ig.jms.Queues
ig.jms.Topics
If no queue or topics are to be monitored, both should be set to 0. If the gateway is going to be setup to monitor
two queues and three topics, these entries would be set to:
ig.jms.Queues=2
ig.jms.Topics=3
Each topic or queue being monitored will require individual property entries. The properties required are:
The XXX in the property names above refer to a specific naming convention that must be followed. For queues,
this would be QueueX, where X is the number of the queue. So if there were two queues to be configured, there
would be two sets of queue properties. The first set would use the name Queue1, and the second Queue2.
Topics follow the same format. If three topics were being configured, there would be property entries for Topic1,
Topic2, and Topic3.
MessageSelectors are a JMS standard way of filtering messages. Selectors allow messages to be chosen based
on a combination of the message’s header and property field values. Messages that match the selector are
retrieved, while those that don’t are not. MessageSelector syntax is based on a subset of SQL, and is quite
powerful. For a complete description of how to use MessageSelectors, please refer to Sun’s Java API
documentation for the Java Message Service.
The JNDIFactory class name must be set up for the JMS provider being used. In the configuration file there are
the following entries:
#The JNDIFactory Classnames for Weblogic, IPlanet, MQSeries.
# ig.jms.JMSProvider.JNDIFactory.Weblogic=weblogic.jndi.WLInitialContextFactory
# ig.jms.JMSProvider.JNDIFactory.IPlanet=com.sun.jndi.fscontext.RefFSContextFactory
# ig.jms.JMSProvider.JNDIFactory.MQSeries=com.sun.jndi.fscontext.RefFSContextFactory
Simply uncomment the line corresponding to the JMS provider being used.
Finally, the ErrorTopic and ShutdownTopic must be configured. These topics have similar properties to normal
topics. Each has a specific entry in the integration gateway properties file. Uncomment and set the properties for
each. These topics should not be counted when setting the value for ig.jms.Topics.
Java is case sensitive, so if there are problems in getting JMS to work, check to ensure that the case of all
property file entries is correct.
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 provider’s documentation for specific instructions on how to set these up.
The contents of the response will be the contents of the body of the message received by the connector.
Example Of Use
The following example assumes that the JMS provider being used has been configured correctly. Since each
provider has specific configuration requirements – that may vary between product releases - it is impossible to
present a generic sequence of steps to accomplish this here. Please refer to your provider’s documentation for
details. Configuration of a JMS provider may not be a trivial exercise, so care must be taken in order to ensure
that the provider is working correctly. Before attempting the example here, check to make sure that messages can
be published and retrieved from named topics and queues. Many providers come with sample programs that can
be run to verify this.
This example will assume that the JMS Provider being used is BEA’s Weblogic.
Additionally, a means to publish messages to a topic must be available for this to work. The sample programs for
your JMS provider should provide examples of how to accomplish this.
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
ig.jms.shutdown.User=system
ig.jms.shutdown.Password=password
• Save and close the integration properties file.
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:
• 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 provider’s documentation for
details. Configuration of a JMS provider may not be a trivial exercise, so care must be taken in order to ensure
that the provider is working correctly. Before attempting the example here, check to make sure that messages can
be published and retrieved from named topics and queues. Many providers come with sample programs that can
be run to verify this.
This example will assume that the JMS Provider being used is BEA’s Weblogic.
Additionally, a means to publish messages to a topic must be available for this to work. The sample programs for
your JMS provider should provide examples of how to accomplish this.
This example will mimic a hub configuration. An incoming HTTP sync message received by the gateway, sent to
the application server and will be converted into a JMS message that will be published to a specific topic.
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
ig.jms.shutdown.Url=t3://localhost:80
ig.jms.shutdown.User=system
ig.jms.shutdown.Password=password
• Save and close the integration properties file.
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
• Click the POST button to send the request to the broker. The request will be sent to the gateway, which will
forward it on to the application server, who will then forward it back out to the gateway. The gateway will
take the message and will publish it to JMS using the connector settings specified for the node.
• Once the transfer has occurred, a response message will be generated and sent back to SendMaster.
Since there is no information in the body of the message, the output information area will not have any
text in it.
9) The program monitoring the topic should receive the message sent by the gateway. The body of the message
should be “This is the body of the request.”
10) Check the gateway message log to see the messages exchanged between the gateway, application server,
and the JMS provider.
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.
SM TP Connector Properties
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 gateway’s integration properties file. This property
specifies the forwarding SMTP server that the SMTPTargetConnector will send messages to. If this parameter is
not set, or incorrectly set, the connector will be unable to send email.
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
status set to OK. Outgoing email is one way communication, and therefore nothing will be returned in the content
section of the response.
If the connector is unable to send the email, an error response message will be generated and returned.
Note: a successful response message means that the email was successfully transferred to the forwarding email
server. It does not necessarily mean that the email was delivered to the final destination! Since an email may
travel between multiple servers, there is a chance that an error could occur during transport. If such an error does
occur the gateway and application server will not be aware of it. The forwarding SMTP server’s error log shold be
periodically checked to catch such cases.
Example of Use
SendMaster will be used to send a sync message into the broker. The broker will be configured so that the
incoming message will be routed to the SMTPTargetConnector, which will then attempt to send the body of the
message to the specified SMTP server.
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.
12) Check the gateway message log to see the messages exchanged between the gateway, the application server,
and the SMTP server. Specific log entries will be seen for the SMTP connector showing that the email was
sent successfully.
13) Check the target email account for the message. Note that depending on the load on the forwarding SMTP
server and the traffic between it and the target’s SMTP server, it may take several seconds ( or minutes! ) for
the email to be delivered.
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.
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 transactions are necessary in order to be
able to use PeopleCode to control the POP3 connection. Since PT_EMAIL_POP3 has all these transactions
already defined, this node can be used with little additional setup required.
However, if it is desired to use another target node, then transactions must be created for that node for the POP3
messages. Use PT_EMAIL_POP3 as a reference when setting up these transactions.
PeopleCode Examples
As previously mentioned, there are two main ways to use the connector: by using the properties defined for the
connector for the target node, or by specifying them in the body of the message.
The connector properties for the target node are always available for POP3 requests. They provide default
behaviour when property values cannot be found on an outgoing request. However, if the user explicitly provides
said values when building the message, these default properties can be ignored.
Connector Properties
By using the connector properties defined for the node, less PeopleCode needs to be written.
This sample code gets the current count of available messages on the mail server:
&request = CreateMessage(Message.EMAIL_REQ_MSGCOUNT);
&request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.UIDL).Value =
1;
&response = &request.SyncRequest(Node.PT_EMAIL_POP3);
If (&response.ResponseStatus = 0) Then
&str =
&response.GetRowset().GetRow(1).GetRecord(Record.EMAIL_RES_WRK).GetField(Field.NUMROWS).Valu
e;
REM str now contains the the number of email messages for the account on the POP3 server;
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).Valu
e = "the_email_account_password";
&request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.METHODNAME).Va
lue = "MessageCount";
&request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.PORT).Value =
110;
&response = &request.SyncRequest(Node.PT_EMAIL_POP3);
If (&response.ResponseStatus = 0) Then
&str =
&response.GetRowset().GetRow(1).GetRecord(Record.EMAIL_RES_WRK).GetField(Field.NUMROWS).Valu
e;
REM str now contains the number of email messages in the account on the POP3 server;
End-If;
ReturnToServer(&response);
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>
Note: there is actually no data in this message that is specific to counting messages or even POP3. This
message is simply used as a trigger to invoke the POP3 server.
• Click the POST button to send the request to the broker. The request will be sent to the gateway, which will
forward it on to the application server, who will then forward it back out to the gateway. The
POP3TargetConnector will query the mail server and will get back a count of the available messages in
the mailbox.
• Once the email has been sent, a response message will be generated and sent back to SendMaster. This
is an example of what might be seen:
<?xml version='1.0'?>
<EMAIL_RES_MSGCOUNT>
<FieldTypes>
<EMAIL_RES_WRK class="R">
<EMAIL_FROM type="CHAR"/>
<NUMROWS type="NUMBER"/>
</EMAIL_RES_WRK>
<PSCAMA class="R">
<LANGUAGE_CD type="CHAR"/>
<AUDIT_ACTN type="CHAR"/>
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. It’s much more probable that users will
write PeopleCode to invoke the POP3 connector
This example will be similar to the ones past in that SendMaster will be used to send a message into the broker.
OnRequest PeopleCode will be written against this message. This PeopleCode will attempt to get all the messages
on the server. Additionally, the connector properties will be set explicitly in the message created, and will not be
read from the transaction or node data.
The example will not use the PT_EMAIL_POP3 node; transactions will be setup on TARGETNODE to support the
POP3 message.
An active POP3 server will be needed for this example, as well as a valid account on it.
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 isn’t necessary, but is done to show that the message can be created and sent
without any connector values being specified on the node.
• 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).Va
lue = 1;
&request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.SERVER).
© Copyright PeopleSoft Corporation 2001. All rights reserved. 66
4/10/2009
Value = "the_POP3_server_name";
&request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.USER).Va
lue = "the_email_account_username";
&request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.PASSWORD
).Value = "the_email_account_password";
&request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.METHODNA
ME).Value = "ReadAll";
&request.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField(Field.PORT).Va
lue = 110;
&response = &request.SyncRequest(Node.TARGETNODE);
ReturnToServer(&response);
Note that SERVER, USER, and PASSWORD will have to be set to the appropriate values for the POP3
account being used.
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>
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 to SendMaster.
This is an example of what might be seen:
<?xml version='1.0'?>
<EMAIL_RES_READALL>
<FieldTypes>
<EMAIL_RES_WRK class="R">
<EMAIL_FROM type="CHAR"/>
<EMAIL_SENDER type="CHAR"/>
<UIDL type="CHAR"/>
<WL_SUBJECT type="CHAR"/>
<EMAIL_TEXTLONG type="CHAR"/>
<NOTIFY_TO type="CHAR"/>
<NOTIFY_CC type="CHAR"/>
</EMAIL_RES_WRK>
<PSCAMA class="R">
<LANGUAGE_CD type="CHAR"/>
<AUDIT_ACTN type="CHAR"/>
<BASE_LANGUAGE_CD type="CHAR"/>
<MSG_SEQ_FLG type="CHAR"/>
<PROCESS_INSTANCE type="NUMBER"/>
<PUBLISH_RULE_ID type="CHAR"/>
<MSGNODENAME type="CHAR"/>
</PSCAMA>
</FieldTypes>
<MsgData>
<Transaction>
<EMAIL_RES_WRK class="R">
<EMAIL_FROM>someone@peoplesoft.com</EMAIL_FROM>
<EMAIL_SENDER>someone@peoplesoft.com</EMAIL_SENDER>
<UIDL>>&["!nVl!!Q*+"!6DZ!!</UIDL>
<WL_SUBJECT>test message</WL_SUBJECT>
<EMAIL_TEXTLONG>This is the body of a test email</EMAIL_TEXTLONG>
<NOTIFY_TO>someoneElse@peoplesoft.com;</NOTIFY_TO>
<NOTIFY_CC></NOTIFY_CC>
</EMAIL_RES_WRK>
<PSCAMA class="R">
<LANGUAGE_CD></LANGUAGE_CD>
<AUDIT_ACTN></AUDIT_ACTN>
<BASE_LANGUAGE_CD></BASE_LANGUAGE_CD>
<MSG_SEQ_FLG></MSG_SEQ_FLG>
<PROCESS_INSTANCE>0</PROCESS_INSTANCE>
<PUBLISH_RULE_ID></PUBLISH_RULE_ID>
<MSGNODENAME></MSGNODENAME>
</PSCAMA>
</Transaction>
</MsgData>
</EMAIL_RES_READALL>
2) Check the gateway message log to see the messages exchanged between the gateway, the application server,
and the POP3 server. Specific log entries will be seen for the POP3 connector showing that the request was
handled successfully.
All material contained in this documentation is proprietary and confidential to PeopleSoft, Inc., is protected by
copyright laws, and subject to the nondisclosure provisions of the applicable PeopleSoft agreement. No part of this
documentation may be reproduced, stored in a retrieval system, or transmitted in any form or by any means,
including, but not limited to, electronic, graphic, mechanical, photocopying, recording, or otherwise without the
prior written permission of PeopleSoft, Inc.
This documentation is subject to change without notice, and PeopleSoft, Inc. does not warrant that the material
contained in this documentation is free of errors. Any errors found in this document should be reported to
PeopleSoft, Inc. in writing.
The copyrighted software that accompanies this documentation is licensed for use only in strict accordance with
the applicable license agreement, which should be read carefully as it governs the terms of use of the software
and this documentation, including the disclosure thereof. See Customer Connection or PeopleBooks for more
information about what publications are considered to be product documentation.
PeopleSoft, the PeopleSoft logo, PeopleTools, PS/nVision, PeopleCode, PeopleBooks, and Vantive are registered
trademarks, and PeopleTalk and "People power the internet." are trademarks of PeopleSoft, Inc. All other company
and product names may be trademarks of their respective owners. The information contained herein is subject to
change without notice.
Information in this book was developed in conjunction with use of the product specified, and is limited in
application to those specific hardware and software products and levels.
PeopleSoft may have patents or pending patent applications covering subject matter in this document. The
furnishing of this document does not give you any license to these patents.
The information contained in this document has not been submitted to any formal PeopleSoft test and is
distributed AS IS. The use of this information or the implementation of any of these techniques is a customer
responsibility and depends on the customer's ability to evaluate and integrate them into the customer's operational
environment. While each item may have been reviewed by PeopleSoft for accuracy in a specific situation, there is
no guarantee that the same or similar results will be obtained elsewhere. Customers attempting to adapt these
techniques to their own environments do so at their own risk. Any pointers in this publication to external Web sites
are provided for convenience only and do not in any manner serve as an endorsement of these Web sites.
This section documents that real-world validation that this Red Paper has received.
CUSTOMER VALIDATION
PeopleSoft is working with PeopleSoft customers to get feedback and validation on this document. Lessons
learned from these customer experiences will be posted here.
FIELD VALIDATION
PeopleSoft Consulting has provided feedback and validation on this document. Additional lessons learned from
field experience will be posted here.
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)
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.
a. ig.jms.JMSProvider.JNDIFactory.MQSeries=com.sun.jndi.fscontext.RefFSContextFactory
3. Set up the following properties for Queue(if Topic need to setup Topic properties) in the
integrationgateway.properties file
ig.jms.Queues
ig.jms.Queue1
ig.jms.Queue1.Provider
ig.jms.Queue1.JMSFactory
ig.jms.Queue1.MessageSelector
ig.jms.Queue1.Url
ig.jms.Queue1.User
ig.jms.Queue1.Password
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.
Run IVTSetup
Configure WebSphere
Ex:
:/usr/mqm/java/bin:/usr/mqm/java/lib:/usr/mqm/java/lib/com.ibm.mq.jar:/usr/mqm/java/lib/co
m.ibm.mqbind.jar:/usr/mqm/java/lib/com.ibm.mqjms.jar:/usr/mqm/java/lib/connector.jar:/usr/
mqm/java/lib/fscontext.jar:/usr/mqm/java/lib/jms.jar:/usr/mqm/java/lib/jndi.jar:/usr/mqm/java/
lib/jta.jar:/usr/mqm/java/libldap.jar:/usr/mqm/java/lib/providerutil.jar
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. 76
4/10/2009
JMSReplyTo
Question - Let's start with simplest scenario. We have single MQSeries queue manager (named QM1) located on the same
machine as PS WebServer. We have a single queue (named Q1_OUT) and we want to send PS messages into this queue. We
have installed MQSeries JMS (MQSeries Java classes) in /opt/mqm/java.What configuration steps we have to perform to have
this connection working
Ans -
Configure JNDI for MQ. (Set Queue & Queue Manager).
Set up JNDI in Websphere (This step is only for Websphere not necessary for Weblogic. For weblogic you need to
specify the class path).
Set up connector properties using PIA.
In the integrationgateway.properties uncomment this line
ig.jms.JMSProvider.JNDIFactory.MQSeries=com.sun.jndi.fscontext.RefFSContextFactory
Refresh teh gateway.
Question -We have two input queues (Q1_IN, Q2_IN) how to configure Gateway and Application Server to distinguisly
listen to them
Ans -
#Define two queues in Properties file.
ig.jms.Queues=2
ig.jms.Queue1=Q1_IN
ig.jms.Queue1.Provider=MQSeries
ig.jms.Queue1.JMSFactory=QueueConnectionFactory
ig.jms.Queue1.Url=file:c:/MQSeries/JNDI
ig.jms.Queue1.User=sam
ig.jms.Queue1.Password=sam
ig.jms.Queue2=Q2_IN
ig.jms.Queue2.Provider=MQSeries
ig.jms.Queue2.JMSFactory=QueueConnectionFactory
ig.jms.Queue2.Url=file:c:/MQSeries/JNDI
ig.jms.Queue2.User=sam
ig.jms.Queue2.Password=sam
Question - In request/response mode we need two queues (output and input). We will also need both TargetConnector and
Listener. How to configure that staff? (For example single queue manager QM1 one output queue Q1_OUT and one input
queue Q1_IN)
Ans –
1.Define Q1_OUT using TargetConnector.
2. Define Q1_IN using Listening Connector.
Question - Is it possible to address bigger (dynamic) number of queues from PeopleCode (e.g. 100) without registering each
of them? For example in PeopleCode I will explicitly name the queue. This could be useful if we would like to put each
message type into different queue with queue name based on message type name (e.g. message "XYZ" in queue
"PS.XYZ.OUT")
Ans - This can be done, but this must be preconfigured at the transaction level. We can not do this using PeopleCode right
now.
Question - What is the relationship between (purpose of) contents of integrationGateway.properties and "Integration
Broker/Monitor/Gateways" screen in PeopleSoft (screen contains a greed with entries like this "JMSTARGET |
JMSAcknowledgment | [x] | AUTO_ACKNOWLEDGE | [x]". Is it so that properties file defines Listners and PS screen
TargetConnectors? (Probably the answer for this question is in answers for questions 1..4).
Ans - Integration Broker/Monitor/Gateway is the place where we can define the gateway, connector and Target connector
properties. These connector properties can be overided at Transaction level too. All JMS Listening Conenctor properties are
set using integrationgateway.properties.
Question - What configuration files are important other than integrationgateway.properties? Do you have an example of this
and any others we can look at?
Ans - You dont require any thing other than integrationgateway.properties file for gateway. If you are using websphere you
may need to change some files for JNDI setting(refer to Websphere JNDI setup document).
Question - Does MQSeries have the ability to prioritize these messages? How does the PeopleSoft/MQSeries integration
support this requirement?
Ans - Yes MQ has ability to prioritize message, and we can prioritize the messages when they go out from PeopleSoft.
Scenario - Multiple non-Psft apps sending non-XML messages into Psft via JMS. How is the IBInfo infomation
sent/configured? With each message? In the JNDI?
Ans - Every message coming in to Listening connector must have following information in the JMS Message header.
1. Message Name (Required)
2. Requesting Node (Required)
3. Password (Optional)
4. Final Destination Node (Optional)
5. Destionation Nodes. (Optional)
Authors
Reviewers
Revision History
1. <Date>: Created document.