4/02/2012

My Integration Broker Experience


At my former customer, I had to setup, configure and customize integration broker to exchange data between HR and Financial environments, both on PSFT 9.0 Tools 8.49, but didn't know from where to start.  I finally understood the mechanism and decided to share it, because I didn't find any clear, quick and sweet guide to start with this monster.

Introduction

Integration Broker is a mechansim used by Peoplesoft to exchange with itself, with another instance or with external web services.

Data is sent as an XML File, the message, which is generated by the source environment and read by the destination environment.  The message is sent from destination into a queue and received from the same queue by the source.

There are two types of Peoplesoft messages: one row message (SYNC) and all rows messages (FULL_SYNC).  SYNC message are used to synchronize a row, when created or modified (when triggered).  The FULL_SYNC messages are launched via an Application Engine executed by the user.

Once received, the message is interpreted by an Application Class: the Handler.  For SYNC messages, the handler usually inserts or updates only 1 line of data.  For FULL_SYNC messages, the handler deletes the data and replaced it with the one contained into the message; exception can be made, such as the person data created in FS (non-HR) which are not deleted when a FULL_SYNC is received from HR.

For some messages, the table structure differs between environments.  To be able to synchronize the data, the message must be transformed to reflect the target environment.  This is done by a transformation, which is an Application Engine of type “Transfrom Only”

Routing is used to specify source and target nodes for a given message.  Nodes represent the target and source environments.  Addresses of servers associated to nodes are defined into the gateway, which represents the connexion with outside.

All those elements (Message, Queue, Routing, Handlers) are grouped into a Service Operation.

Configuration
Gateway
PeopleTools > Integration Broker > Configuration > Gateways

PSFTTARGET connector is used to exchange between two instances of Peoplesoft.  Gateway Setup Properties links to the nodes configuration page, to associate them to servers.

Nodes
PeopleTools > Integration Broker > Integration Setup >  Nodes
When we work with two distinct Peoplesoft environments, it is important to configure and activate the corresponding nodes, in each environment.  Peoplesoft nodes type is PIA; in some, we need to set a node type to External even if it represents a Peoplesoft environment (see in Security for more information).

Messages
PeopleTools > Integration Broker > Integration Setup >  Messages
Queues
PeopleTools > Integration Broker > Integration Setup >  Queues
The queue status must be set at Run to let messages go threw.  It is possible to split a queue into sub queues, using a list of fieds to split on.

Service Operations
PeopleTools > Integration Broker > Integration Setup >  Service Operations
A service operation is the object that links all elements.  It links the message and the queue, specifies the code to execute at the reception (handler), the routing (target node, destination node), and the transformation to apply if necessary.
 
Messages FullSync
Rules
Enterprise Components > Integration Definitions > Full Data Publish Rules

The language tab is not used for all messages; mainly for setup tables (countries, languages, diploma, business unit, …)

Exécution
Enterprise Components > Integration Definitions > Initiate Processes > Full Data Publish

The process to execute is EOP_PUBLISHT

Security
For a successful exchange from HR to FN, the user must be present in both environment and have the security to use the Services Operations; it is possible in Peopletoos >= 8.50 to specify a default userid which is used in the source environment to manipulate the Service Operation.  For version below 8.50, workaround exists : the « non-local » node  (PSFT_EP in HR, PSFT_HR in FN) must be of type External the default userid must be set (see below).

More information is available here:
The security must be set to give access to Service Operations to the default user (and any other users allowed to transfer messages).  This must be done in both environments :

Code

Transformation
The transformation is used to translate a message into another version.  PERSON_BASIC and WORKFORCE messages are using such transformation, because datamodel is different between FN and HR.

A transformation is an Application Engine (AE) of type Transform Only.  This AE has only one Peoplecode step, which does the transformation.  %TransformData variable refers to the message (rowset) to transform.
import XXX_HCR_PUBLICATION_RULES:XXXTransformPersonFullToV1;
[…]
Local TransformData &tdata = %TransformData;
/* Set a temp object to contain the incoming document */
Local XmlDoc &tempDoc = &tdata.XmlDoc;
&PERS_MSG = CreateMessage(Message. XXX_PERSON_BASIC_FULLSYNC);
&RS_CURR = &PERS_MSG.GetRowset();
&XMLDOC_TO_MSG = &tempDoc.CopyToRowset(&RS_CURR, "XXX_PERSON_BASIC_FULLSYNC", "VERSION_3");
&RS_V1 = &PERS_MSG.GetRowset("VERSION_1");
[…]
 Local XXX_HCR_PUBLICATION_RULES: XXXTransformPersonFullToV1 &TransV1;
&TransV1 = create XXX_HCR_PUBLICATION_RULES: XXXTransformPersonFullToV1(&RS_CURR, &RS_V1);
%TransformData.XmlDoc.CopyRowset(&RS_V1, "XXX_PERSON_BASIC_FULLSYNC", "VERSION_1");
[…]

Handler

The handler is code which is executed as a certain ; it can be of type OnNotify, OnReceive, OnRoute and OnSend.  OnNotify handlers are called when the message is recieved.

A handler is coded an application classe.  It can be set by clicking on Details.
 
The handler implemets an interface contained in package PS_PT:Integration.  For a onNotify handler, the class implements PS_PT:Integration:INotificationHandler  as followed :

class XXXPersonBasicSync implements PS_PT:Integration:INotificationHandler
   method XXXPersonBasicSync();
   method OnNotify(&_MSG As Message);
end-class;

The OnNotify method is executed when the message is received.  The code can modify the data in the message and inserts / updates the records.

method OnNotify
   /+ &_MSG as Message +/
   /+ Extends/implements PS_PT:Integration:INotificationHandler.OnNotify +/
   /* Variable Declaration */
     
   Local Message &MSG;
     
   /**For CAFM integration**/
   Local boolean &bHaveCAFM;
   Local RE_UTILITIES:CAFMUtil &objCAFMLib;

   Local Rowset &MSG_ROWSET, &LEVEL1_ROWSET;
   Local number &A0, &B1, &A1;
  
   /* &PersonalData = GetLevel0().GetRow(1).GetRowset(Scroll.PERSONAL_DATA);*/
   &MSG = &_MSG;
   If &MSG.IsActive Then
      /*Make Custom Code to remove the zeros in front of emplid*/
      &MSG_ROWSET = &MSG.GetRowset();
      &MSG_ROWSET(1).PERSONAL_DATA.EMPLID.Value = Substring(&MSG_ROWSET(1).PERSONAL_DATA.EMPLID.Value, 6, 6);
     
      /*Bypass Subscribe_IncrReplication to continue working with the Rowset (the following code is the content of Subscribe_IncrReplication) */
      &MSG_LANG_CD = &MSG_ROWSET(1).PSCAMA.LANGUAGE_CD.Value;
      &MSG_BASE_LANG_CD = &MSG_ROWSET(1).PSCAMA.BASE_LANGUAGE_CD.Value;
      &FULL_INCR = "INCR";
      Proc_Sub_Rowset(&MSG_ROWSET);

   End-If;
[…]

The object of type Message derives from the Rowset type; the method GetRowset() is used to retrieve the message as a rowset, to manipulate it easily.