Applying Filtering, Transformation and Translation

This chapter discusses how to:

• Develop transform programs.

• Filter messages and generate errors.

• Apply transformations.

• Perform data translation.

Understanding Filtering, Transformation, and Translation

Filtering, transformation, and translation are all accomplished by applying an Application Engine transform program to an outbound or inbound message. You can use transform programs to:

• Filter a message based on its content, to determine whether to pass it through to its destination or to subsequent steps of the transform program.

• Perform transformation on a message to make its structure comply with the receiving system’s requirements.

• Perform data translation on a message so that its data is represented according to the receiving system’s conventions.

  Simple translation might be required if the two systems use different values to represent the same information for a given field.

  Complex translation might involve augmenting or replacing groups of fields with a completely different structure and encoding.

If your PeopleSoft application uses the PeopleCode XmlDoc or SoapDoc classes to generate or process a message, the message probably doesn’t adhere to the PeopleSoft rowset-based message format.

To develop a transform program, you must know the initial structure and possibly the content of the message you’re working with, as well as the structure (and content) of the result you want to achieve. Make sure that all participating nodes agree on a format or employ transformations to accommodate the variations from node to node.

The message data is made available to your transform program in a PeopleCode system variable after being extracted from the wrapper in which it was transmitted. The format of this wrapper depends on the transmission method, but is irrelevant to the transform program.

Filtering, transformation, or translation can be necessary for messages sent between two PeopleSoft Integration Broker nodes, or between an Integration Broker node and a third-party application. Any participating node with Integration Broker installed — the source, the target, or a hub — can apply a transform program to a given message.

You specify which transform program to apply within a transaction modifier, which is associated with a relationship definition.

Note. With PeopleSoft Integration Broker, the term node refers to a system or application participating in an integration, but in this chapter a node is also a structural element in an XML document. The context in which the term is used should make its meaning clear.

Transform programs cannot modify the following messaging features:

• Transmission protocols.

  You handle a given protocol by selecting an appropriate target connector for the target node's local gateway, or by directing a third-party sender to the appropriate listening connector on the default local node’s local gateway. You can select from the delivered connectors or develop new ones.

• Character set encoding.

  This is handled by the PeopleSoft globalization system.

See Also

Understanding Supported Message Structures

Administering Relationships

Selecting and Configuring Character Sets and Language Input and Output

Third-Party Considerations

When no transformation is applied, applications using PeopleSoft Integration Broker send, and expect to receive, messages containing data that conforms to a minimum XML message structure: the PeopleSoft rowset-based message format.

When exchanging messages with third-party applications, you can:

• Employ a transformation at the PeopleSoft end of each transaction to convert messages to or from the PeopleSoft rowset-based message format.

• Require third-party applications to send and receive messages that comply with the PeopleSoft rowset-based message format. Third-party applications must comply with the rowset-based message format if both of the following are true:

  • Your PeopleSoft application uses the PeopleCode Message and Rowset classes to generate and send, or receive and process messages with Integration Broker.

  • You don’t want to employ Integration Broker transformations to accommodate the third-party application.

Note. Third parties can submit messages to Integration Broker systems using any listening connector registered with the local gateway. Regardless of the message data format, the third-party system is responsible for properly constructing the wrapper that contains the message data, and using the appropriate tools and protocols to address the connector.

Developing Transform Programs

This section discusses how to:

• Define a transform program.

• Work with transform programs.

• Access message data.

• Make working data available globally.

• Preserve record and field aliases.

Defining Transform Programs

In PeopleSoft Application Designer, select File, New, App Engine Program to create a new program.

To define a transform program:

1. Open the program properties and select the Advanced tab.

2. Select a program type of Transform Only, click OK and save the program.

3. Insert sections, steps and actions as needed.

   Construct your program as you would any other Application Engine program, using actions of type XSLT and PeopleCode.

See Also

Understanding PeopleSoft Application Engine

Working with Transform Programs

PeopleSoft Integration Broker supports the use of Extensible Stylesheet Language Transformation (XSLT) code and PeopleCode, implemented in your transform program as actions of type XSLT or PeopleCode, respectively. Following are some points to keep in mind:

• Each transform program step operates on the message content that results from the previous step, so you can break your transform program into a sequence of discrete steps.

• Multiple transform actions within a step can produce unwanted effects, so insert each XSLT or PeopleCode action in its own step.

• XSLT works only on XML DOM-compliant data, so PeopleSoft Integration Broker assures that both outbound and inbound messages are in XML DOM-compliant form when transform programs are applied to them.

• Transformations on outbound synchronous requests executed from within Application Engine programs (in batch) that contain one or more XSLT steps are not supported on the OS/390 and z/OS platforms, since Xalan is not available on these platforms. Xalan is an XSLT processor that transforms XML documents into HTML, text, or other XML document types.

A transformation can modify an entire message until it no longer resembles the original. So can a data translation. In a transformation, you must hard-code what you want to accomplish, whereas the data translation relies on a repository of codeset metadata that you define. This means you can establish consistent rule-based translations and reuse the same translation rules without having to reenter them.

Although you can combine transformation and data translation in a single transform step, it’s better to keep these processes in separate steps and produce a modular program that you can more easily maintain, with code you can reuse in other transform programs.

Deciding Which Language to Use

XSLT is a well-recognized standard language perfectly suited to manipulating XML structures, so it’s highly recommended for transformations. Because of its straightforward template-based approach to accessing the codeset repository, XSLT is also recommended for data translation.

However, you can't use XSLT to filter messages based on content, so filtering must be implemented in PeopleCode.

You can use both XSLT and PeopleCode steps in a single transform program.

Each XSLT program must be enclosed in the following wrapper:

<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
   your_xslt_program
</xsl:stylesheet>

Third-party XSLT development tools may generate a wrapper that specifies a different URI. Make sure the URI in your program is exactly as shown here, or your program may not work as expected.

You can find more information about XSLT at the World Wide Web Consortium (W3C) web site.

Invoking Transform Programs

Your transform program is invoked by PeopleSoft Integration Broker if you specify its name in the Transformations group Request or Response field when you edit the details of a transaction modifier.

Renaming or Deleting Transform Programs

To invoke an Application Engine transform program, you specify it as part of a transaction modifier. If you subsequently rename or delete that transform program, it still appears in the transaction modifier definition, so transactions using that modifier will fail. To prevent this, do the following:

• If you rename a transform program, make sure you reselect it by its new name in any transaction modifiers that apply it.

• If you delete a transform program, make sure you select a different program (or no program) in any transaction modifiers that apply it.

Tracing Transform Programs

For debugging purposes, you can trigger a trace of your transform program by adding a specific value to the Application Engine trace parameter, in one of the following ways:

• Specify the TRACE switch on the Application Engine command line, with the value 8192 added, for example:

  -TRACE 8192

• Add the value 8192 to the TRACEAE parameter in the appropriate application server or Process Scheduler server configuration file, for example:

  TRACEAE=8192

See Also

Configuring Relationships

Managing Transaction Modifiers

XmlDoc Class

Tracing Application Engine Programs

Using the PSADMIN Utility

http://www.w3.org/Style/XSL/

Accessing Message Data

When PeopleSoft Integration Broker invokes a transform program, it inserts the message content into a PeopleCode system variable, %TransformData, which remains in scope throughout the program. Each step can access the variable in turn and modify its content, which then becomes available to the next step.

XSLT and PeopleCode steps access %TransformData differently:

• In XSLT, the data is automatically made available to your program. The XSLT program is literally a presentation of the output structure and data, which includes xsltags that reference, process and incorporate the input data into the output structure. There’s no need to explicitly refer to %TransformData, which automatically receives the interpreted result of the XSLT.

• In PeopleCode, use the PeopleCode TransformData class to access %TransformData. You then access the XML data as a property of the TransformData object called XmlDoc, which you assign to an XmlDoc object and process normally. Because the XmlDoc object is a reference to the data portion of %TransformData, your modifications are automatically passed back to the system variable.

Using the TransformData Class

The PeopleCode TransformData class has several properties:

Note. Because transform programs can apply to both request and synchronous response messages, the node sending the message could be a synchronous transaction target node that’s sending a response back to the synchronous transaction source node, which in this case is the receiving node.

Working with Message Samples

When developing a transform program for XML message data, you might find it useful to have sample copies of the initial and resulting XML message structures as a guide. You can generate the samples from the message definitions using the Create Test Message feature of Application Designer.

After you publish a test message containing sample data, you can view its XML structure and content in Integration Broker Monitor and copy that data to a text file for reference.

Handling Non-XML Data

Because they work only with XML DOM-compliant data, neither XSLT nor PeopleCode transform steps can process non-XML data. The XML DOM provides a way to incorporate such data into an XML structure so your transform programs won’t produce errors.

If you’re generating a non-XML outbound message in your PeopleSoft application, it’s up to you to insert your message content into a special element containing a CDATA tag, as follows:

<any_tag psnonxml="yes">
   <![CDATA[your_nonXML_message_content]]>
</any_tag>

Note. Any_tag can be any tag you want to use.

The following restrictions apply to the content of inbound non-XML messages, such as those in CSV or PDF format, sent by third-party applications:

• Inbound non-XML text messages must be encoded as UTF-8-compliant characters.

• Inbound non-text, or binary, messages must be encoded in base64 format.

See Also

Generating Test Messages

Making Working Storage Data Available Globally

XSLT transform steps can’t access external data, but PeopleCode can. XSLT also has no global variables. However, the message itself is global, and can be used to pass working or external data to all steps in the transform program. During a PeopleCode step, you can add a special node to the message to contain the data, which is then available to subsequent transform steps.

Following is an example of a minimal input message:

<?xml version="1.0"?>
<Header>
  <LANGUAGE_CODE>en_us</LANGUAGE_CODE>
  <STATUS_CODE>1000</STATUS_CODE>
</Header>

The following PeopleCode inserts a node in the message to contain working data, by convention called psft_workingstorage. Then the PeopleCode inserts the current system date into that node:

/* Get the data from the AE Runtime */
Local TransformData &incomingData = %TransformData;
/* Set a temp object to contain the incoming document */
Local XmlDoc &inputDoc = &incomingData.XmlDoc;
/* Add a working storage node*/
Local XmlNode &wrkStorageNode =
 &inputDoc.DocumentElement.AddElement("psft_workingstorage");
/* Add the current system date to the working storage*/
Local XmlNode &sysDateNode = &wrkStorageNode.AddElement("sysdate");
&sysDateNode.NodeValue = String(%Date);

Following is the resulting output message:

<?xml version="1.0"?>
<Header>
  <LANGUAGE_CODE>en_us</LANGUAGE_CODE>
  <STATUS_CODE>0</STATUS_CODE>
  <psft_workingstorage>
    <sysdate>2002-01-24</sysdate>
  </psft_workingstorage>
</Header>

Any subsequent transform step now has access to the current system date. Make sure the last step that uses the psft_workingstorage node removes it from the final output, as with this XSLT fragment:

<xsl:template match="psft_workingstorage">
   <!-- Do not copy this node -->
</xsl:template>

Preserving Record and Field Aliases

When you apply a transform program to a rowset-based message, Integration Broker submits the message to the program in its final XML DOM compliant form, with any aliases you defined in place of the corresponding original record and field names.

In a PeopleCode transformation, the message is initially available as an XmlDoc object. However, you may want to transform the message using the PeopleCode Rowset class. Because XmlDoc object structure is compatible with Rowset object structure, you can copy the XML data to a rowset using the XmlDoc class CopyToRowset method.

Because the rowset to which you copy the data must be based on a message object instantiated from your original message, the rowset uses the message’s original record and field names. If you defined aliases for any of the message records or fields, you must ensure that the rowset uses those aliases instead, or the XmlDoc data won’t copy successfully.

The following set of conditions summarizes this situation:

• The message definition includes at least one record or field alias.

• You’re applying a transform program to the message.

• Your transform program includes a PeopleCode step.

• The PeopleCode step uses a Rowset object to hold the message data.

Using Optional CopyToRowset Parameters

To make sure the rowset object uses the record and field aliases that exist in the XML data, you must specify two optional string parameters in the CopyToRowset method, which convey the message name and version:

CopyToRowset(&Rowset, Message_Name, Version)

The integration engine uses any aliases it finds in the specified message definition to rename the appropriate records and fields in the rowset object before copying the data. Following is an example of a rowset-based transform step that preserves aliases:

Local Message &TempMSG;
Local Rowset &TempRS;

/* 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;

/* Create a working rowset (no aliases used) */
&TempMSG = CreateMessage(Message.MyMsgName);
&TempRS = &TempMSG.GetRowset();

/* Copy message data to rowset (restoring aliases) */
&OK = &tempDoc.CopyToRowset(&TempRS, "MY_MSG_NAME", "MY_MSG_VERSION");

   /* . . .Transform rowset data. . . */

/* Copy transformed rowset back to XmlDoc object */
&OK = &tempDoc.CopyRowset(&TempRS, "MY_MSG_NAME", "MY_MSG_VERSION");

See Also

XmlDoc Methods

Filtering Messages

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

Understanding Message Filtering

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"?>
   <Filter>reason_for_failure</Filter>

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.

PeopleCode Filtering Example

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 emphasized):

<?xml version="1.0"?>
<PurchaseOrder>
   <Destination>
      <Address>123 Vine Street</Address>
      <Contact>
         <Name>Joe Smith</Name>
      </Contact>
      <Delivery type="ground">
         <Business>FedEx</Business>
      </Delivery>
   </Destination>
   <Payment>
      <CreditCard cardtype="visa">9999-9999-9999-9999</CreditCard>
   </Payment>
   <LineItems count="2">
      <Li locale="en_us" number="1">
         <Quantity>4</Quantity>
         <ProductName>pencil</ProductName>
         <UOM>box</UOM>
      </Li>
      <Li locale="en_us" number="2">
         <Quantity>10</Quantity>
         <ProductName>paper</ProductName>
         <UOM>large box</UOM>
      </Li>
   </LineItems>
</PurchaseOrder>

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 =
 &tempDoc.DocumentElement.FindNodes("LineItems/Li/Quantity");
/* 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

   End-If
End-For;

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>

Applying Transformations

This section provides an overview of transformation and discusses using XSLT for transformation.

Understanding Transformation

Use a transformation when one node sends a request or response message with a data structure different from the structure required by the other node. One or both of the participating nodes can be PeopleSoft applications. At either end of the transaction, any of the following structure types may be required:

• The PeopleSoft rowset-based message format.

• An XML DOM-compliant non-rowset-based structure. This is generic XML data.

• A SOAP-compliant XML structure. This is also XML DOM-compliant.

• A non-XML structure. Third-party applications are more likely than PeopleSoft applications to require this type.

Your transformation can be between different structure types or between different structures of the same type.

See Also

Understanding Supported Message Structures

Using XSLT for Transformation

An XSLT transformation simulates the original message structure, then specifies how to treat nodes within that structure. You can:

• Copy the original content of a node without changing anything.

• Define and insert a new version of a node.

• Enter any structure or content directly.

• Eliminate a node by omitting reference to it, or by not inserting anything new in its place.

XSLT Transformation Example

The XSLT wrapper is required.

<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">

The primary node tag matches the original message structure by matching its top level content tag, the message name (QE_SYNC_MSG). Between the message template tags, you can insert any structure or content you want. PeopleSoft Integration Broker replaces each xsl tag with the data it references, producing a transformed message as the output of the step.

   <xsl:template match="QE_SYNC_MSG">
      <QE_SYNC_MSG>
         <xsl:copy-of select="FieldTypes"/>
         <MsgData>
            <Transaction>
               <xsl:apply-templates select="MsgData/Transaction/QE_SALES_ORDER"/>
               <xsl:copy-of select="MsgData/Transaction/PSCAMA"/>
            </Transaction>
         </MsgData>
      </QE_SYNC_MSG>
   </xsl:template>

The following node example is defined to match a record in the input message by its top level content tag, the record name (QE_SALES_ORDER). This template is applied by the xsl:apply-templates tag of the preceding node (shown emphasized).

Between the record template tags, you can insert any structure or content you want. In this example, 90 is prepended to the QE_ACCT_ID value, and the QE_ACCOUNT_NAME field is renamed to QE_ACCOUNT (shown emphasized). Also, any existing value in the DESCRLONG field is removed, and the remaining fields are passed through with their original values.

   <xsl:template match="QE_SALES_ORDER">
      <QE_SALES_ORDER><xsl:attribute name="class">
      <xsl:value-of select="@class"/></xsl:attribute>
         <xsl:variable name="temp" select="QE_ACCT_ID"/>
         <QE_ACCT_ID><xsl:value-of select="concat(90,$temp)"/></QE_ACCT_ID>
         <QE_ACCOUNT><xsl:value-of select="QE_ACCOUNT_NAME"/></QE_ACCOUNT>
         <QE_ADDRESS><xsl:value-of select="QE_ADDRESS"/></QE_ADDRESS>
         <QE_PHONE><xsl:value-of select="QE_PHONE"/></QE_PHONE>
         <QE_FROMROWSET/>
         <QE_TOROWSET/>
         <QE_SEND_SOA_BTN/>
         <QE_SEND_SOS_BTN/>
         <DESCRLONG></DESCRLONG>
      </QE_SALES_ORDER>
   </xsl:template>

Finally, you need the closing wrapper tag:

</xsl:stylesheet>

Note. You can find more information about XSLT at the World Wide Web Consortium (W3C) web site.

Note. A working transformation example using XSLT is provided in the PeopleTools SDK. The location of the example is <PS_HOME> \sdk\pstransform\samples\TRANSFORMTST.xml.

See Also

http://www.w3.org/Style/XSL/

Performing Data Translation

This section provides an overview of data translation and discusses how to:

• Define codeset groups.

• Define codesets.

• Define codeset values.

• Import and export codesets between databases.

• Delete codesets.

• Use XSLT for data translation.

• Work with an XSLT translation example.

• Work with a PeopleCode translation example.

Understanding Data Translation

Use data translation to modify message content rather than structure, although you can also make local structural changes. It’s most appropriate when the sending and receiving systems use different field values, or different combinations of fields and their values, to represent the same information.

Following is a sample scenario:

• Application A transmits customer names in four fields: Title, First, Middle, and Last.

• Application B uses two fields: Last and First. It doesn’t use a title, but includes the middle name as part of the First field.

• Application C uses only one field: AccountID.

Clearly the representation used by one application won’t be understood by either of the other two. PeopleSoft Integration Broker can apply a transform program to translate each of these representations into a version appropriate to the receiving application.

One Integration Broker node can store in its codeset repository the equivalent fields and values used by another node. When it receives a message from the other node containing a customer name, it can use its codeset repository to translate the information into the form it prefers. It can likewise reverse the process for messages outbound to the other node.

For a given integration, you can allocate the responsibility for performing data translation in different ways. You can distribute the translation activity among the participating nodes, or you can designate one Integration Broker node to do all the data translation as a hub, whether the messages are inbound, outbound, or being redirected between the other nodes. Using a single node, if possible, can reduce the need for duplicating repository data.

Data Translation Elements

The following elements constitute the codeset repository, managed as PeopleSoft Pure Internet Architecture components:

The other key element of data translation is your translation program, which invokes the codesets and codeset values you’ve defined.

Data Translation Development Sequence

You must initially define these elements in a particular order:

1. Two codeset groups.

2. A codeset based on one of the codeset groups.

3. A set of codeset values.

4. A data translation program, in XSLT or PeopleCode.

However, it’s unlikely that you’ll be able to fully define any of these elements without some trial and error. You may find you’ll have to modify and extend each element in turn as you develop your data translation program.

Defining Codeset Groups

Use the Codeset Groups page in the Codeset Groups component (IB_CODESETGROUP) to define codeset groups. To access the Codeset Groups page, select PeopleTools, Integration Broker, Integration Setup, Codesets, Codeset Groups.

To define a codeset group:

1. Add a new value, enter a codeset group name, and click Add.

   Enter a name that reflects a common quality of the nodes you plan to assign to this group; for example, the name of the software they all use to manage shipping.

   The Codeset Group page appears.

2. Add a new row.

3. Enter a match name.

   This is the name of a data field that might be part of a message sent by a node belonging to this codeset group. You don’t have to create an entry for every field, just the ones that you’ll need to translate or use for reference in a translation.

4. Enter a match value.

   This is one of the possible values of the data field represented by the match name.

5. Repeat steps 2 through 4 for each significant name/value pair that you expect to appear in a message.

   This doesn’t need to be all possible values of all of the message fields, just the names and values you expect to require translation.

6. Assign one or more nodes to this codeset group.

   Every initial and result node involved in a data translation must belong to a codeset group. You must assign each participating node to an appropriate codeset group by an entry in its node properties.

   Note. The assignment for each node is required only in the database of the node performing the data translation. This translating node needn’t be either the source or the target. Multiple nodes that represent data the same way may be assigned to the same codeset group.

See Also

Configuring Nodes

Defining Codesets

Use the Codesets page in the Codesets component (IB_CODESET). Select PeopleTools, Integration Broker, Integration Setup, Codesets, Codesets to access the Codeset page.

To define a codeset:

1. Add a new value and enter a codeset group name on which to base this codeset.

2. Enter a codeset name and click Add.

   Enter a name that reflects the purpose of this codeset; for example, SAP_SHIP_METHOD, to translate the representation of a shipping method in a message. The Codesets page appears.

3. Add a new row.

4. Select a match name from the set defined for the associated codeset group.

5. Select a match value from the set defined for the selected match name.

   Note. You can leave the value blank. If so, you should do the same for each match name in this codeset, in addition to any other values you select for them. A combination consisting of all blank values is treated as a wild card by PeopleSoft Integration Broker, which enables it to respond to unanticipated values specified in your translation program with default behavior that you define.

6. Repeat steps 3 through 5 to enter all the name/value pairs that may need to be matched.

   The name/value pairs you select should encompass only the possible value combinations that your translation program needs to match for a single translation. You define a different codeset for each translation based on this codeset group.

Defining Codeset Values

Use the Codeset Values page in the Codeset Values component (IB_CODESETVAL). Select PeopleTools, Integration Broker, Integration Setup, Codesets, Codeset Values to access the Codeset Values page.

To define codeset values:

1. Add a new value and select a codeset group name for the From group.

   This is the codeset group to which the initial node belongs.

2. Select a codeset name from the codesets based on the group you selected.

   This is the codeset whose match name/match value permutations you wish to match.

3. Select a codeset group name for the To group.

   This is the codeset group to which the result node belongs.

4. Click Add.

   The Codeset Values page appears. The upper grid contains the selected codeset’s match name/match value pairs, and the lower grid contains the return values you specify. Each permutation that you define has its own Description field, which can help you distinguish between permutations that may be subtly different from each other.

   Note. To configure an existing codeset values definition, enter its From group, codeset name and To group on the search page.

5. Select check boxes to define a permutation of match name/match value pairs.

   For each match name, you can select at most one match value.

   A permutation consisting of all blank values serves as a wild card; it matches any input value combination that isn’t matched by any other permutation. However, a permutation with some blank and some non-blank values works differently; it requires the names with blank values to actually match blank field values in the input data.

   Note. You’ll generally define only permutations that you expect the input data to contain, but make sure you allow for unforeseen match values by including permutations with all blank values. You can then specify default return values for those permutations. With a large number of match names in the codeset, you can make sure to catch all unforeseen combinations by defining a permutation with all blank match values.

6. In the Code Set Values grid, enter a return name, and a return value for that name.

   You can use any return name you want, because only your codeset translation program refers to it. Your translation program can use the return value as a field value or as a node name in the output data.

   Important! The set of return names you define must be identical for all of the permutations of match name/match value pairs for the current codeset in this definition. Your translation program invokes the codeset and applies the return names from this definition, but it can’t anticipate which permutations will be matched, or which actual return values it’s applying — just the return names.

7. (Optional.) In the Code Set Values grid, add a new row and repeat step 6.

   Add as many return name/return value pairs as you need for your output based on the current permutation. If the permutation is matched in the input data, the code set values you define for that permutation become available for you to call and insert in the output data.

8. (Optional.) At the top level of this page, add a new row and repeat steps 5 through 7.

   This inserts a new permutation row, in which you can define a different permutation of match name/match value pairs that you expect for the current codeset. For each permutation, you’ll define a separate, independent set of codeset values.

Importing and Exporting Codesets Between Databases

PeopleSoft provides two Data Mover scripts that you can use to import and export codesets between databases:

• CODESET_DELETE_IMPORT.DMS

  Use this script to purge and then import codeset data into a target database.

• CODESET_EXPORT.DMS

  Use this script to export codeset data from a source database to a target database.

Deleting Codesets

Before you delete a codeset, you must delete any codeset values associated with it.

Deleting Codeset Values

To delete codeset values for a codeset:

1. Select PeopleTools, Integration Broker, Integration Setup, Codesets, Codeset Values. The Codeset Values page displays.

2. In the Find an Existing Value tab, in the Codeset Name field, enter the name of the code set you want to delete, or use the Lookup button to locate it.

3. In the Codeset Values section, clear the Select box for each match name corresponding to the code set match name you want to delete, or click the minus (-) button to delete the entire code set scroll area.

   Repeat this process for as many codeset match names that are used.

4. Click the Save button.

Deleting Codesets

To delete a codeset:

1. Select PeopleTools, Integration Broker, Integration Setup, Codesets, Codeset.

2. Select the codeset to delete. The Codeset page displays.

3. Locate the row that contains the codeset you want to delete, and click the minus (-) button on that row.

4. Click the Save button.

Using XSLT for Data Translation

Once you’ve defined the match name/match value permutations for a given codeset and defined the return values for those permutations, you can write an XSLT translation program that invokes the codeset and applies the return values.

An XSLT translation is based on XSLT transformation structure. However, although you could combine both tasks into a single program, it’s better to keep them separate for easier understanding and maintenance.

Psft_function Nodes

To implement data translation capability, PeopleSoft Integration Broker provides a custom XSLT tag called psft_function. Each psft_function node in your program comprises a single instance of data translation that invokes a particular codeset and applies a specified set of codeset values.

Note. You can insert a psft_function node anywhere inside the XSLT template containing the fields you want to translate. However, you’ll find it easiest to place it at or near the point in the template where the return values will go, to avoid having to specify a complex path to that location.

The psft_function tag has the following attributes:

Note. The source and dest attributes don’t change the initial and result nodes specified in the transaction modifier; they just invoke the codeset groups to which those nodes belong.

Following is an example of psft_function using all of its attributes:

<psft_function name="codeset" codesetname="PS_SAP_PO_01"
 source="SAP_02" dest="PSFT_03">...</psft_function>

Parm and Value Nodes

The psft_function node can contain two tags, parm and value:

• Use the parm tag to specify a match name from the codeset values definition that you specified for this translation. You do this with the tag’s only attribute: name. Set this to a match name from the codeset values definition.

  The parm node should contain a match value, usually specified as an xsl:value-of tag that identifies where the value resides in the input data. Use one parm node for each distinct match name in the codeset values definition.

• Use the value tag to specify a return name from the codeset values definition that you specified for this translation. Also use the value tag to identify where to place the return value assigned to that return name for the matched permutation and how to apply that value.

  Use one value node for each return name in the codeset values definition that you want in your output.

Value Tag Attributes

The value tag has the following attributes:

Following is an example of a value node:

<value name="PS_RET_01" select="." createNodeFromValue="yes"><xsl:value-of
 select="CreditCard"/></value>

See Also

Using XSLT for Transformation

http://www.w3.org/Style/XSL/

XSLT Translation Example

The following example of XSLT data translation presents an example input message, the XSLT translation program, and the resulting output message.

Input Message

This is the input to the XSLT translation:

<PurchaseOrder>
   <Destination>
      <Address>123 Vine Street</Address>
      <Contact>
         <Name>Joe Smith</Name>
      </Contact>
      <Delivery type="ground">
         <Business>FedEx</Business>
      </Delivery>
   </Destination>
   <Payment>
      <CreditCard cardtype="visa">9999-9999-9999-9999</CreditCard>
   </Payment>
   <LineItems count="2">
      <Li locale="en_us" number="1">
         <Quantity>15</Quantity>
         <ProductName>pencil</ProductName>
         <UOM>box</UOM>
      </Li>
      <Li locale="en_us" number="2">
         <Quantity>10</Quantity>
         <ProductName>paper</ProductName>
         <UOM>large box</UOM>
      </Li>
   </LineItems>
</PurchaseOrder>

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

XSLT Data Translation Program

This translation program processes the input message in this example and generates the output message that follows. The statements shown emphasized demonstrate some uses of the psft_function node:

<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
   <xsl:template match="PurchaseOrder">
      <po>
         <xsl:apply-templates/>
      </po>
   </xsl:template>
 
   <xsl:template match="Destination">
      <dest>
         <address><xsl:value-of select="Address"/></address>
         <name><xsl:value-of select="Contact/Name"/></name>
         <delivery>
            <type>
               <psft_function name="codeset" codesetname="PS_SAP_PO_03" 
               dest="PSFT_03">
                  <parm name="type"><xsl:value-of select="Delivery/@type"/>
                  </parm>
                  <value name="PS_RET_01" select="."/>
               </psft_function>
            </type>
            <carrier>
               <psft_function name="codeset" codesetname="PS_SAP_PO_03"
               source="SAP_03">
                  <parm name="Business"><xsl:value-of select="Delivery/
                  Business"/></parm>
                  <value name="PS_RET_01" select="."/>
               </psft_function>
            </carrier>
         </delivery>
      </dest>
   </xsl:template>
 
   <xsl:template match="Payment">
      <payment>
         <psft_function name="codeset" codesetname="PS_SAP_PO_02">
             <parm name="cardtype"><xsl:value-of select="CreditCard/
             @cardtype"/></parm>
             <value name="PS_RET_01" select="."
             createNodeFromValue="yes"><xsl:value-of select="CreditCard"/>
             </value>
         </psft_function>
      </payment>
   </xsl:template>
 
   <xsl:template match="Li">
      <li><xsl:attribute name="id"><xsl:value-of select="@number"/></xsl:attribute>
         <name><xsl:value-of select="ProductName"/></name>
         <qty><xsl:value-of select="Quantity"/></qty>
         <uom>
            <psft_function name="codeset" codesetname="PS_SAP_PO_01">
                <parm name="locale"><xsl:value-of select="@locale"/></parm>
                <parm name="uom"><xsl:value-of select="UOM"/></parm>
                <value name="PS_RET_01" select="."/>
                <value name="PS_RET_02" select="../type" createIfDNE="yes"/>
            </psft_function>
         </uom>
      </li>
   </xsl:template>
</xsl:stylesheet>

Output Message

This is the result of applying the XSLT translation:

<po>
   <li id="1">
      <name>pencil</name>
      <qty>15</qty>
      <uom>Carton</uom>
      <type>Bic</type>
   </li>
   <li id="2">
      <name>paper</name>
      <qty>10</qty>
      <uom>Box</uom>
      <type>Bic</type>
   </li>
   <dest>
      <address>123 Vine Street</address>
      <name>Joe Smith</name>
      <delivery>
         <type>Ground</type>
         <carrier>Federal Express</carrier>
      </delivery>
   </dest>
   <payment>
      <VISA>4024-9920-9892-8982</VISA>
   </payment>
</po>

PeopleCode Translation Example

Although XSLT is the recommended language for using the codeset repository to translate message data, you can use PeopleCode for this purpose as well. Because XSLT works only with XML DOM-compliant message data, you must use PeopleCode if the message you’re translating contains non-XML data, including formats like comma separated values (CSV).

Once you’ve defined the match name/match value permutations for a codeset with respect to a given target codeset group and defined the return values for those permutations, you can write a PeopleCode translation program that invokes that codeset and applies the return values.

FindCodeSetValues Built-in Function

To implement data translation capability, Integration Broker provides a PeopleCode built-in function called FindCodeSetValues, which takes four parameters and returns a two dimensional array.

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

Input Message

This is the input to the PeopleCode translation:

<?xml version="1.0"?>
<Header>
  <LANGUAGE_CODE>en_us</LANGUAGE_CODE>
  <STATUS_CODE>0</STATUS_CODE>
</Header>

PeopleCode Data Translation Program

This translation program processes the input message in this example, and generates the output message that follows. The statement shown emphasized demonstrates the use of the FindCodeSetValues function:

/* Get the data from the AE Runtime */
Local TransformData &incomingData = %TransformData;

/* Set a temp object to contain the incoming document */
Local XmlDoc &tempDoc = &incomingData.XmlDoc;

/* Find the Language and status codes value*/
Local string &langCode = &tempDoc.DocumentElement.FindNode("LANGUAGE_CODE").NodeValue;
Local string &statusCode = &tempDoc.DocumentElement.FindNode("STATUS_CODE").NodeValue;

/* Create an array to hold the name value pairs */
Local array of array of string &inNameValuePairsAry;

/* Load the array with some values */
&inNameValuePairsAry = CreateArray(CreateArray("LANG", &langCode),
 CreateArray("STATUS", &statusCode));

/* Find the codeset values */
&outAry = FindCodeSetValues("STATUS_CHANGE", &inNameValuePairsAry,
 &incomingData.SourceNode, &incomingData.DestNode);

/* Create the new output doc */
If &tempDoc.ParseXmlString("<?xml version=""1.0""?><NewHeader/>") Then

   /* Make sure something was returned */
   If &outAry.Len > 0 Then

      /* Create the new Status Code Node */
      Local XmlNode &statusNode = &tempDoc.DocumentElement.AddElement("STATUS");

      /* Since this is a 2D array, get the Return Value*/
      &statusNode.NodeValue = &outAry [1][2];
   End-If;
End-If;

Output Message

This is the result of applying the PeopleCode translation:

<?xml version="1.0"?>
<NewHeader>
   <STATUS>Open</STATUS>
</NewHeader>

See Also

FindCodeSetValues

Terminating Transformation Programs

If you need to terminate a transform program for reasons that aren’t considered error conditions by PeopleSoft Integration Broker, you can use a PeopleCode step to force the transform program to terminate and generate a readable error message as well.

To generate an error:

1. Replace the entire message content with a single node called Error, containing the reason for the error.

   <?xml version="1.0"?>
   <Error>reason_for_error</Error>

2. Set the TransformData Status property to 2 to indicate error status.

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

Note. If an XSLT or PeopleCode step fails for reasons that you haven’t taken into account, Integration Broker automatically sets the Status property to 2 and aborts the transform program, but you can’t provide your own error message.

See Also

Monitoring Messaging System Information