Filtering Messages

This section provides an overview of message filtering and discusses how to work with a PeopleCode filtering example.

You use filtering to suppress an input message based on its content. For example, you can suppress all inbound purchase order messages that specify order quantities less than the minimum number required for a discount.

Place filtering steps early in your Application Engine transform program; each message suppressed by the filter is one less message for subsequent steps to process.

You must use PeopleCode for filtering, so it'll probably be a distinct step. Because you must use the XmlDoc and XmlNode classes in your PeopleCode transform steps, you can analyze messages in any way that those classes support.

Filtering requires the following actions in your PeopleCode program:

  1. Retrieve the message content from the %TransformData system variable.

  2. Examine your filtering criteria.

  3. If the message meets your criteria, do nothing further. It remains intact in the %TransformData system variable for the next transform program step to process.

  4. If the message fails to meet your criteria, replace the entire message content with a single node called Filter, containing the reason it failed.

    <?xml version="1.0"?>
  5. Set the TransformData Status property to 1 to indicate failure.

PeopleSoft Integration Broker examines the Status property after each step, and terminates the transform program if its value is 1. You can then view the message in Integration Broker Monitor and see the reason for the failure.

The following example of filtering presents an input message, the PeopleCode filtering program, and the resulting output message.

Input Message

This is the input to the filtering step. Notice the line item order quantities (shown in emphasis):

<?xml version="1.0"?>
      <Address>123 Vine Street</Address>
         <Name>Joe Smith</Name>
      <Delivery type="ground">
      <CreditCard cardtype="visa">9999-9999-9999-9999</CreditCard>
   <LineItems count="2">
      <Li locale="en_us" number="1">
      <Li locale="en_us" number="2"><Quantity>10</Quantity>
         <UOM>large box</UOM>

Note: Although this input message isn’t in the PeopleSoft rowset-based message format, it is valid XML.

PeopleCode Filtering Program

This filtering program examines the line item order quantities of the input message and generates the output message that follows. The key statements are in bold:

/* Get the data from the AE Runtime */
Local TransformData &tempData = %TransformData;
/* Set a temp object to contain the incoming document */
Local XmlDoc &tempDoc = &tempData.XmlDoc;

/* Find the line items quantities contained in the incoming Purchase Order */
Local array of XmlNode &quantities =
/* Temp storage of a node */
Local XmlNode &tempNode;

/* Loop through the quantities and make sure they are all above 5 */
For &i = 1 To &quantities.Len
   /* Set the temp node*/
   &tempNode = &quantities [&i];
   /* Make sure the node isn't empty*/
   If ( Not &tempNode.IsNull) Then

      /* Check the value, if not greater than 5 this does not pass filter*/
      If (Value(&tempNode.NodeValue) < 5) Then
         /* Clear out the doc and put in the "Filter" root node */If (&tempDoc.ParseXmlString("<?xml version=""1.0""?><Filter/>")) Then
            /* Get the new root node and set the value 
            /*  to be the reason for failing filter     */&rootNode = &tempDoc.DocumentElement;&rootNode.NodeValue = "Line item quantity was found that was less than 5!";
            /* Set the status of the transformation to 1 for failed filter*/&tempData.Status = 1;End-If;Break;End-If


Output Message

This is the result of applying the PeopleCode filtering program:

<?xml version="1.0"?>
<Filter>Line item quantity was found that was less than 5!</Filter>