Understanding Integration PeopleCode

This section discusses the PeopleCode used for integrations and describes:

  • Sending and receiving PeopleCode.

  • Integration application classes.

  • Integration methods.

  • Messaging methods.

  • Error-handling methods.

  • Messaging PeopleCode.

  • Documents PeopleCode.

This section discusses the PeopleCode you use for sending messages from PeopleSoft Integration Broker to other systems, and the PeopleCode you use for receiving messages from other systems.

Sending PeopleCode

PeopleCode for sending messages can be located in PeopleCode events associated with records, record fields, and components, and in application engine programs.

The PeopleCode method used to send messages is highlighted in the following table.

Transmission Type

Sending PeopleCode

Comments

Synchronous

SyncRequest method.

The SyncRequest method belongs to the IntBroker class.

Asynchronous

Publish method.

The Publish method belongs to the IntBroker class.

To work with rowset-based messages in SOAP format, transform the SOAP documents into XML documents and then use the IntBroker class SyncRequest or Publish methods. To work with nonrowset-based messages in SOAP format use the SOAPDoc class.

Receiving PeopleCode

The PeopleCode that you use to receive a message must be associated with the message definition. The transmission type of the message determines the location of the PeopleCode program.

Implement the OnRequest method for synchronous messages. Implement the OnNotify method for asynchronous messages. Both methods are located in the PS_PT application package, in the Integration sub-package, in the IRequestHandler and INotificationHandler classes, respectively.

Transmission Type

Message Structure

Receiving PeopleCode

Comments

Synchronous

Rowset-based

Message is passed into the method.

Implement the OnRequest method in the IRequestHandler application interface.

Synchronous

Nonrowset-based

Message is passed into the method.

Implement the OnRequest method in the IRequestHandler application interface.

Asynchronous

Rowset-based

Message is passed into the method.

Implement the OnNotify method in the INotificationHandler application interface.

Asynchronous

Nonrowset-based

Message is passed into the method.

Implement the OnNotify method in the INotificationHandler application interface.

To get content data out of a request message, use the following guidelines.

Message Structure

PeopleCode

Comments

Rowset-based

GetRowSet method.

None.

Nonrowset-based

GetXMLDoc method.

You can also use Message class functionality with nonrowset-based messages.

See Using Message Object Functionality With Nonrowset-Based Messages.

Application classes house the processing logic for asynchronous and synchronous messages. By implementing the Integration Broker application classes, you can reuse code and access other benefits of application classes.

The following application classes exist for PeopleSoft Integration Broker. See the individual applicable application class interfaces for more information about the methods contained in an application class.

To access these application classes, in PeopleSoft Application Designer, open the PS_PT application package and open the Integration subpackage.

Note: All of the Integration Broker application classes are defined as interfaces. This means that there is no native implementation of them: you must import them to your program and implement them if you want to use them.

Application Class

Methods Contained in Application Class

Comments

INotificationHandler

  • OnNotify

  • OnError

This interface is the equivalent of the Subscription Message event PeopleTools releases prior to PeopleTools 8.48.

IReceiver

  • OnAckReceive

  • OnError

This interface is the equivalent of the OnAckReceive Message event in PeopleTools releases prior to PeopleTools 8.48.

IRequestHandler

  • OnRequest

  • OnError

This interface is the equivalent of the OnRequest Message event in PeopleTools releases prior to PeopleTools 8.48.

IRouter

  • OnRouteSend

  • OnRouteReceive

  • OnError

This interface is the equivalent of the OnRouteSend and OnRouteReceive Message events in PeopleTools releases prior to PeopleTools 8.48.

ISend

  • OnRequestSend

  • OnError

This interface is the equivalent of the OnSend Message event in PeopleTools releases prior to PeopleTools 8.48.

Each of the methods contained in these application classes is described in this section.

Routing methods determine how a message is routed to or from PeopleSoft Integration Broker.

OnRouteSend Method

Implement the OnRouteSend method for outbound synchronous and asynchronous service operations to specify to what node PeopleSoft Integration Broker routes a message. The implementation of this method enables you to apply PeopleCode that filters the destination nodes to which PeopleSoft Integration Broker routes messages.

The OnRouteSend method is contained in the IRouter application class, which is contained in the PS_PT application package, in the Integration subpackage.

When the application PeopleCode is invoked to send a message, the routing definitions in the local database provide a list of target nodes to which PeopleSoft Integration Broker can route the message. The integration engine’s request handler invokes the service operation's OnRouteSend event. You can implement the OnRouteSend method in the application package associated with the handler for this service operation, which enables you to apply additional PeopleCode that determines the final target nodes.

You can use OnRouteSend to validate the outbound service operation's target node list, prevent the message from transmitting, or redirect it to a completely different set of targets.

The following table lists the PeopleCode built-in constants that you can use with the OnRouteSend method:

Constant

Description

%IntBroker_ROUTE_NONE

Do not send this operation to any of the possible nodes.

%IntBroker_ROUTE_SOME

Send this operation to a selected list of nodes. The node list should be an array of strings in the property destinationNodes.

%IntBroker_ROUTE_ALL

Send this operation to all nodes that have a valid routing.

OnRouteSend enables you to account for multiple synchronous targets. Only one target node at a time can receive a request message sent with a synchronous transaction. Even though you can define the same outbound synchronous transaction for multiple nodes, you must make sure the transaction resolves to a single target node or the transaction fails.

The following code example shows an implementation of this class:

import PS_PT:Integration:IRouter;

class RoutingHandler implements PS_PT:Integration:IRouter
   method RoutingHandler();
   property array of any destinationNodes;
   method OnRouteSend(&_MSG As Message) Returns integer;
end-class;

/* constructor */
method RoutingHandler
end-method;

method OnRouteSend
   /+ &_MSG as Message +/
   /+ Returns Integer +/
   /+ Extends/implements PS_PT:Integration:IRouter.OnRouteSend +/
   /* Variable Declaration */
   Local any &aNodeList;
   Local any &rootNode;
   Local any &xmlDoc;
   
   /* Check the message for the instructions on how to execute
     the OnRouteSend.*/
   
   &xmlDoc = &_MSG.GetXmlDoc();
   &rootNode = &xmlDoc.DocumentElement;
   &aNodeList = &rootNode.GetElementsByTagName("OnRouteSend");
   
   If (&aNodeList.Len <> 1) Then
      
      /* No Nodes are in the list, therefore exit. */
      Exit;
   Else
      
      /* check the value of the node to determine the action to 
       take. */
      
      Evaluate &aNodeList [1].NodeValue
      When "True"
         Return (%IntBroker_ROUTE_ALL);
         Break;
      When "False"
         Return (%IntBroker_ROUTE_NONE);
         Break;
      When-Other
         
         /* assume that this is to be routed to the node given */
         Local array &nodeArray;
         &nodeArray = CreateArray();
         &nodeArray.Push(&aNodeList [1].NodeValue);
         
         Local string &sIBVariableTest = GetCurrentType(&nodeArray);
         Evaluate &sIBVariableTest
         When "Array"
            &destinationNodes = &nodeArray.Clone();
            Return %IntBroker_ROUTE_SOME;
         When "BooleanTrue"
            Return %IntBroker_ROUTE_ALL;
         When "BooleanFalse"
            Return %IntBroker_ROUTE_NONE;
         End-Evaluate;
         Break;
         
      End-Evaluate;
      
   End-If;
   
end-method;

OnRouteReceive Method

Implement the OnRouteReceive method for inbound synchronous and asynchronous service operations to apply PeopleCode that determines whether the default local node accepts inbound messages.

The OnRouteReceive method is contained in the IRouter application class, which is contained in the PS_PT application package, in the Integration subpackage.

When the integration engine receives a message, the transaction definitions in the local database provide a list of source nodes from which the application can accept the message. The integration engine’s request handler invokes the service operation's OnRouteReceive event. You can implement the OnRouteReceive method in the application package associated with the handler for this service operation, which enables you to apply PeopleCode that determines whether the default local node accepts the inbound message. You can employ this event regardless of the message transmission type.

The following is an example implementation of this method:

import PS_PT:Integration:IRouter;

class RoutingHandler implements PS_PT:Integration:IRouter
   method RoutingHandler();
   property array of any destinationNodes;
   method OnRouteReceive(&_MSG As Message) Returns boolean;
end-class;

/* constructor */
method RoutingHandler
end-method;

method OnRouteReceive
   /+ &_MSG as Message +/
   /+ Returns Boolean +/
   /+ Extends/implements PS_PT:Integration:IRouter.OnRouteReceive +/
   /* Variable Declaration */
   Local any &aNodeList;
   Local any &rootNode;
   Local any &xmlDoc;
   
   /* Check the message for instructions on how to execute
    the OnRouteReceive.*/
   
   &xmlDoc = &_MSG.GetXmlDoc();
   &rootNode = &xmlDoc.DocumentElement;
   &aNodeList = &rootNode.GetElementsByTagName("OnRouteReceive");
   
   If (&aNodeList.Len <> 1) Then
      
      /* A single node must be present. */
      Exit;
   Else
      
      /* check the value of the node to determine the action to 
        take. */
      
      Evaluate &aNodeList [1].NodeValue
      When "True"
         Return ( True);
         Break;
      When "False"
         Return ( False);
         Break;
      When-Other
         /* don't recognize the value. */
         Exit;
      End-Evaluate;
      
   End-If;
   
end-method;

This section describes methods used in messaging and the application classes in which they are contained.

Outbound Messaging Methods

This section describes methods used on outbound messages from PeopleSoft to other systems.

Term

Definition

OnRequestSend

Implement for outbound synchronous and asynchronous service operations to override connector properties before sending a message to the integration gateway.

This method is contained in the ISend application class.

The OnRequestSend method passes in a message to your derived application class method. The returned value needs to be a message.

The following is an example implementation of this method.

import PS_PT:Integration:ISend;

class SendHandler implements PS_PT:Integration:ISend
   method SendHandler();
   method OnRequestSend(&_MSG As Message) 
    Returns Message;
end-class;

/* constructor */
method SendHandler
end-method;

method OnRequestSend
   /+ &_MSG as Message +/
   /+ Returns Message +/
   /+ Extends/implements PS_PT:Integration:ISend. +/
   /+ OnRequest Send +/
   /* Variable Declaration */
   Local any &tempNode;
   Local any &rootNode;
   Local any &xmlDoc;
   Local any &msg;
   
   &msg = &_MSG;
   
   &xmlDoc = &msg.GetXmlDoc();
   
   /* Add a node to the doc to prove that we can 
      edit it in this event. */
   
   &rootNode = &xmlDoc.DocumentElement;
   
   &tempNode = &rootNode.AddElement("OnSend");
   &tempNode.NodeValue = "If you see this, then 
   the Sync OnSend PCode has altered the message";
   
   /* and write the data back into the message */
   
   &msg.SetXmlDoc(&xmlDoc);
   
   Return (&msg);
   
end-method;

See Setting and Overriding Target Connector Properties at Runtime.

When using the ISend handler with message parts, specifically with rowset-based message parts, the rowsets of the parts must be retrieved in the order that the content data will be sent.

The following is an example that can be used for ISend events that use rowset-based parts (even for the cases where one is just overriding the connectors):

method OnRequestSend
   /+ &MSG as Message +/
   /+ Returns Message +/
   /+ Extends/implements PS_PT:Integration:ISend. +/
   /+ OnRequestSend +/
   If (&MSG.IsPartsStructured) Then
      Local number &i;
      Local Rowset &rs;
      For &i = 1 To &MSG.PartCount
         &rs = &MSG.GetPartRowset(&i);
      End-For;
   End-If;

      Return &MSG;
   
end-method;

OnAckReceive

Implement for outbound asynchronous service operations to access the body of a message acknowledgement to check for SOAP faults.

This method is contained in the IReceiver application class.

The following is an example implementation of this method.

import PS_PT:Integration:IReceiver;

class AckReceiveHandler implements PS_PT:
  Integration:IReceiver
   method AckReceiveHandler();
   method OnAckReceive(&_MSG As Message) Returns 
   integer;
end-class;

/* constructor */
method AckReceiveHandler
end-method;

method OnAckReceive
   /+ &_MSG as Message +/
   /+ Returns Integer +/
   /+ Extends/implements PS_PT:Integration:+/
   /+ IReceiver.OnAck Receive +/
   /* Variable Declaration */
   /*  
/* We return a hardcoded value. In this case, a 
   message error.*/
   
   Return (%Operation_Error);
   
end-method;

See Handling Inbound Asynchronous Transactions.

Inbound Messaging Methods

This section describes methods used on inbound messages to PeopleSoft from other systems.

Term

Definition

OnRequest

Implement for inbound synchronous service operations.

This method is contained in the IRequestHandler application class.

The following is an example implementation of this method:

class RequestHandler implements PS_PT:Integration:
 IRequestHandler
   method RequestHandler();
   method OnRequest(&_MSG As Message) Returns 
   Message;
end-class;

/* constructor */
method RequestHandler
end-method;

method OnRequest
   /+ &_MSG as Message +/
   /+ Returns Message +/
   /+ Extends/implements PS_PT:Integration:+/
   /+ IRequestHandler.OnRequest +/
   /* Variable Declaration */
   Local any &tempNode;
   Local any &descNode;
   Local any &rootNode;
   Local any &xmlDoc;
   Local any &xmldata;
   Local any &msg;
   
   &msg = CreateMessage(Operation.QE_IB_SYNC_RESP,%IntBroker_response);
   
   &xmldata = "<?xml version='1.0'?>
   <QE_IB_PeopleCode_Test⇒/>";
   
   &xmlDoc = CreateXmlDoc(&xmldata);
   
   &rootNode = &xmlDoc.documentelement;
   
   &descNode = &rootNode.AddElement("Description");
   &descNode.NodeValue = "Sync test of OnRouteSend.";
   
   &tempNode = &rootNode.addelement("OnRequest");
   &tempNode.NodeValue = "If you see this,
   then the On Request PCode created the response 
   message";
   
   &msg.SetXmlDoc(&xmlDoc);
   
   Return &msg;

OnNotify

Implement for inbound asynchronous service operations. This method can be used for code that does subscription processing, and for validating and loading message data.

This method is contained in the INotificationHandler application class.

The following is an example implementation of this method:

import PS_PT:Integration:INotificationHandler;

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

/* constructor */
method NotificationHandler
end-method;

method OnNotify
   /+ &_MSG as Message +/
   /+ Extends/implements PS_PT:Integration: +/
   /+ INotificationHandler.OnNotify +/
   /* Variable Declaration */
   
   Local Rowset &rs;
   
   &rs = &MSG.GetRowset();
         
   /* process data from rowset */
end-method;

OnResponse

Implement for inbound response asynchronous service operations.

This method can be used for code that does response subscription processing. This method is contained in the INotificationHandler application class.

The following is an example implementation of this method and shows how to get the request TransactionID.

import PS_PT:Integration:INotificationHandler;

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

/* constructor */
method RESPONSE_NOTIFICATION
   %Super = create PS_PT:Integration:INotificationHandler();
end-method;

method OnNotify
   /+ &MSG as Message +/
   /+ Extends/implements PS_PT:Integration:+/
   /+ INotification Handler.OnNotify +/
   
   Local Rowset &rs;
   Local boolean &Ret;
   Local string &TransactionID;
   
   &rs = &MSG.GetRowset();
   
   If &MSG.IsSourceNodeExternal Then
      
      /* if the request came from an external non 
        PeopleSoft System then you can get the 
        original TransactionID from the WSA_MessageID
        from the request message. */
      
      &TransactionID = &MSG.IBInfo.WSA_MessageID;
      
   Else
      
      /* if the request came from a PeopleSoft 
         System then get the original TransactionID 
         from the  nReplyToID */
      
      &TransactionID = &MSG.IBInfo.InReplyToID;
      
   End-If;
   
end-method;

Error-Handling Methods

Each application class contained in the Integration application subpackage contains an OnError method that you can use for custom error handling.

Custom error handling can include sending an email notification or entering data in a log when an error occurs.

For the IRequestHandler application class, the OnError function returns a string. This enables you to send back custom error messages, for example SOAP faults, to non-PeopleSoft consumers. If the message consumed was a SOAP message and the custom error message is already wrapped in SOAP, it will not be modified and is sent as-is. However, if the OnError message is not SOAP, it is wrapped as a standard SOAP fault and returned to the sender.

If the message consumer is another PeopleSoft system the message set/message ID framework applies.

If an error occurs the OnError method, if implemented, is automatically invoked. The type of exception can be viewed by using the Message object to retrieve an Exception object populated with information about the error, using the message class IBException property.

The following is an example of the OnError method implementation:

/*On Error Implementation */
method OnError
   /+ &MSG as Message +/
   /+ Returns String +/
   /+ Extends/implements PS_PT:Integration:IRequestHandler.OnError +/
   Local integer &nMsgNumber, &nMsgSetNumber;
   Local string &sText;
   
   &nMsgNumber = &MSG.IBException.MessageNumber;
   &nMsgSetNumber = &MSG.IBException.MessageSetNumber;
   rem    &sText = &exception.DefaultText;
   &sText = &MSG.IBException.ToString();
   
   
   /* ADD SPECIFIC ERROR INFO HERE */
   Return &sText;
   
end-method;

See Understanding Exception Class.

See IBException.

Messaging PeopleCode enables you to manipulate message content. The messaging PeopleCode classes you can use for this are:

Term

Definition

Message classes

Use for rowset or nonrowset-based messages.

SOAPDoc class

Use for SOAP-compliant messages.

XMLDoc classes

Use for XML messages.

Document class

Use for Document type messages.

XML and SOAP-compliant messages are nonrowset-based messages. You can use their respective classes to manipulate message content, or use the Message classes.

PeopleSoft provides a Document API for populating and retrieving document data that includes several built-in functions and classes.

The built-in functions are:

Term

Definition

CreateDocument

Use this built-in function to instantiate a Document object.

CreateDocumentKey

Use this built-in function to instantiate a Document Key object

The classes are:

  • Document class.

    Use the methods and properties in this class to populate and retrieve document data.

  • DocumentKey class.

    Use the methods and properties in this class to create document keys.

    Document keys enable you to map the document package, document name, and document version, to one string. As a result, when you populate or retrieve data from a document, you can specify the one document key, instead of specifying the document package, name, and version.

    populating or retrieving data from a document, you can use the one document key

  • Primitive class.

    Use the methods and properties in this class to populate and retrieve document data from primitive elements.

  • Compound class.

    Use the methods and properties in this class to populate and retrieve document data from compound elements.

  • Collection class.

    Use the methods and properties in this class to populate and retrieve document data from collection elements.

The Document API is discussed in the product documentation for PeopleCode API Reference.

Examples of populating and retrieving document data are provided elsewhere in this topic.