Integration Broker

Concepts
Integration broker is one of those areas of PeopleSoft that introduces a lot of terminology.
You really need to get your head around this terminology before you can really
understand what's going on. Unfortunately, the documentation in PeopleBooks can be a
little terse. So here's my (limited) understanding of the major concepts (please feel free to
comment):
● Gateways are essetially a pathway out of the system. There is always a LOCAL
gateway in PeopleSoft which refers to the source PeopleSoft system. Other
gateways may exist - for example when there are differences between
PeopleTools versions.
● Domains refer to PeopleSoft application server (tuxedo) domains.
● Nodes define what application a message belongs to - any system that integration
broker can talk to (including the local system) will have a node.
● Messages define the structure of the XML sent between nodes. The key
difference between asynchronous and synchronous messages is acknowledgement
- synchronous messages need to be acknowledge by the receiver, aynychronous
ones don't. Synchronous messages aren't used much in PeopleSoft, but I believe
their main purpose is for reliability.
● Queues are used to manage and group messages so that all messages are sent
through the multiple pipes. Queues are used for administration of integration
broker to avoid stopping everything when something is wrong. For example you
can pause a one queue for messages to the report architecture without say
stopping messages to the finance system.
● Service Operations bring together messages, queues, handlers and routings. They
essentially define how the message moves between systems.
● Services seem to be used to group service operations.
● Routings are used to link a service operation to a node, and can also specify
transformation of a message.
● Handlers contain code and logic for sending/receiving/manipulating mesages.

Messages
Use the following SQL to return the fields for a record in your message that are set to
include in your messsage field properties:
select RF.FIELDNAME
from PSRECFIELD RF
where
RF.RECNAME = 'MESSAGE_RECNAME'
and not exists (
select 1
from PSMSGFLDOVR MFO
where MFO.MSGNAME = 'MSGNAME'
and MFO.APMSGVER = 'VERSION_N'
and MFO.RECNAME = RF.RECNAME
and MFO.FIELDNAME = RF.FIELDNAME
 and MFO.DONOTPUBLISH = 1
)
order by RF.FIELDNUM;

Further Information
● Integration Broker Basics (ERP Associates)

Integration Broker Basics

Building Blocks of Integration Broker
Nodes
If you think about the e-mail analogy, the Node would be like the Domain part of the e-
mail addresses. For PeopleSoft-to-PeopleSoft communication, Nodes are (usually)
PSFT_EP for Financials, PSFT_HR for HRMS, PSFT_LM for LMS, and PSFT_CRM
for CRM. They basically tell which application a message belongs to.

The node definition is where you define what messages are valid for that node. Prior to
PeopleTools 8.48, you’d define them on the “Transaction” tab. In 8.48 and above, you’d
define them on the “Routings” tab.

Since you might not want just anybody being able to publish a message to a node, you’ll
need to set a node password on the first page of the node definition. This password will
have to be the same in all of the environments. For example, if you want to publish a
message to PSFT_EP from HRMS, the PSFT_EP node password will have to be the same
in both Financials and HRMS.

Messages
The message definition is where the developer specifies what data a message will
contain. It includes records and fields, and child records are nested under their parent
records.

If you think of the e-mail analogy, the message name would be both the User part of the
e-mail address, and the message itself would be the Body of the e-mail.

Transformations
A transformation is a program that gets executed against a message either when it’s sent,
or when it’s received. If you think about it, this can be important because data structures
are different with different PeopleSoft versions. So if you’re sending a message with
employee data from HRMS 8.8 back to Financials version 8.4, there’s a good chance that
the message that HRMS sends is different from what Financials is able to receive. So
you need a transformation.

The transformation itself is a special type of Application Engine program that integration
broker can execute by itself against the XML of a message. It uses either PeopleCode, or
XSLT (a special language for transforming XML) to put the message into the new
format.

In the e-mail analogy, this would be like me sending an e-mail to someone who doesn’t
speak English. I'd either have to translate it before I sent it, or the recipient would have
to translate it.

Prior to PeopleTools 8.48, you use “Relationships” to associate a Transformation

program to a message. In 8.48 and above, you can associate a Transformation to a
Message with either a Service Operation or a Routing.

Gateways
The gateway is kind of like the e-mail server. It knows the nodes – that is to say for a
given node it knows the server name, app server port number, username and password so
that it can connect to the node’s app server and push the message to the integration broker
running in that environment.

The gateway runs as part of the PIA web server. Integration Broker sends messages to it
with a plain ‘ol Post HTTP request. This makes talking to Integration Broker pretty easy
for 3rd party applications since they don’t have to write any special protocols.

Asynchronous versus Synchronous

Integration Broker can do either Synchronous or Asynchronous messages. Synchronous
messages are sent and the program waits for a successful response from the remote
system before it will continue.

Asynchronous messages are more like the E-mail analogy – the message is sent and the
program gets on with its life, assuming the message will be OK.

Most PeopleSoft EIP's are Asynchronous, and so I’ll only talk about Asynchronous
messaging in this document.

Message Channels / Queues

PeopleSoft lets you group message definitions into queues. Queues can be paused or
running. So if you want to keep messages with employee data from trying to go from
HRMS to Financials when Financials is going to be down, you can pause the message
queue. When the maintenance is over, you can set the queue to running.

They have another normally unused feature: You can change how many messages get
posted to the integration broker at one time by chunking on specific combinations of
fields. Message Chunking is more of a developer topic, so that’s all I’ll say about it for
now.

Prior to PeopleTools 8.48, Queues were called Message Channels. I don’t believe there’s
any real difference in what they are or what they do.

Service Operations
Service Operations were invented in PeopleTools 8.48. I believe the intention was to
create a single place where you can define which nodes a message is valid for and what
transformations need to be applied to it.

Steps in Integration Broker prior to Tools 8.48

1. PeopleCode event creates and publishes a message

2. Integration Broker looks to see if the message channel for that message is active.

3. Integration Broker creates a message instance for the message

4. Integration Broker looks to see what nodes the message is active for

5. Integration Broker creates a publication contract for each message node.

6. Integration Broker looks to see if any “relationships” exist for the source node/target
node/message/version combination, and executes the transformation associated with the
relationship if it exists.

7. For each publication contract, Integration Broker publishes the message (in XML
format) to the integration gateway. This includes the Source and Target nodes.

8. The Integration Gateway looks for the target node in its configuration file
(integrationgateway.properties), connects to the application server, and passes the
message off to the target integration broker.

9. Integration broker creates a message instance for the message.

10. Integration Broker looks to see if the message is set up as an inbound message on
the source node.

11. Integration Broker creates a subscription contract for the source node (if active).

12. Integration Broker looks to see if any “relationships” exist for the source
node/target node/message/version combination and executes the transformation program
if applicable.

13. Integration Broker inserts the message into the database based on the message
definition.

Steps in Integration Broker 8.49

The process is basically the same, but the terminology has changed.

1. PeopleCode event creates and publishes a message

2. Integration Broker looks to see if the Queue for that message is active.

3. Integration Broker creates a transaction for the message

4. Integration Broker looks to see what nodes the message is active for

5. Integration Broker creates a publication contract for each message node.

6. Integration Broker looks to see if any transformations programs exist for the service
operation routing or the node routing, and executes them if found.

7. For each publication contract, Integration Broker publishes the message (in XML
format) to the integration gateway. This includes the Source and Target nodes.

8. The Integration Gateway looks for the target node in its configuration file
(integrationgateway.properties), connects to the application server, verifies the node
passwords from the source and the target environments match, and passes the message
off to the target integration broker.

9. Integration broker creates a message instance for the message.

10. Integration Broker looks to see if the message is set up as an inbound message on
the source node.

11. Integration Broker creates a subscription contract for the source node (if active).

12. Integration Broker looks to see if any transformation programs exist for the service
operation routing or the node routing, and executes them if found.

13. Integration Broker inserts the message into the database based on the message
definition.

Integration Gateway Considerations

Integration Broker got an overhaul in PeopleTools 8.48, and the older PeopleTools
versions are no longer compatible with the newer PeopleTools versions.

So how can you actually make the old PeopleTools versions send and receive messages
with the new PeopleTools versions? You have to make the older versions use the new
Integration Gateway.

So what the does that mean? Well, you have to do is go to PeopleTools > Integration
Broker > Gateways, and select the LOCAL gateway. Change the URL to be the same as
the environment with latest copy of PeopleTools’ LOCAL gateway URL.
Now if you want to change any Gateway configuration, be sure to do it from the latest
PeopleTools environment. Its bad luck to edit Integration Gateway configuration using a
version lower than the gateway is running. Also older tools versions won’t encrypt
passwords like the new ones will.

Also, if you shut down a shared Integration Gateway web server, it’s going to impact
Integration Broker on all of the environments that share it. Messages should catch up
whenever you bring the Integration Gateway web server back up, as long as you go to
Message Monitor and resubmit the ones in error.