Applying Filtering, Transformation and Translation

This chapter discusses how to:

• Define transform programs.

• Develop transforms programs using PeopleSoft Application Engine.

• Develop transforms programs using Oracle XSL Mapper.

• Invoke transform programs.

• Access transform message data.

• Rename or delete transform programs.

• Filter messages.

• Apply transformations.

• Perform data translation.

• Reject transformation programs.

• Terminate transformation programs.

Understanding Filtering, Transformation, and Translation

This chapter describes how to use filtering, transformations and translations for integrations. This chapter also features code examples to help illustrate how to filter, transform and translate integrations.

Note. The code examples in this chapter are for illustrative purposes only and are not intended to be used in a production environment.

Filtering, transformation, and translation are all accomplished by applying an Application Engine transform program to an outbound or inbound message. You can use these 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.

Filtering, transformation, or translation can be necessary for messages sent between two PeopleSoft Integration Broker nodes, or between a PeopleSoft Integration Broker node and a third-party application.

See Also

Understanding Supported Message Structures

Understanding Transform Programs

This section provides overview information about transform programs.

Transform Programs

A transform program is a type of PeopleSoft Application Engine program. After you create a new transform application engine program, you add steps and actions to the program, and then add code to the steps and actions that performs data transformation, filtering or translation.

To develop a transform program, you must know the initial structure and possibly the content of the message with which you are working, 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.

Any participating node with PeopleSoft 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 routing definition for a service operation.

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.

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.

Transformation Programming Languages

You can use PeopleCode or Extensible Stylesheet Language Transformation (XSLT) as programming languages for creating transformation logic.

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.

Note. When programming using XSLT, you can hand-code the XSLT or use the Oracle XSL Mapper to graphically associate records and fields. The Oracle XSL Mapper then automatically generates the XSLT code.

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

Note. Filtering must be implemented using PeopleCode

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

Each XSLT program must be enclosed in the following wrapper:

Note. When using Oracle XSL Mapper, the mapper automatically encloses the program in this 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.

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 PeopleSoft Integration Broker transformations to accommodate the third-party application.

Note. Third parties can submit messages to PeopleSoft 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.

Defining Transform Programs

This section discusses how to define transform programs.

Understanding Defining Transform Programs

This section contains information about defining transform programs

Transform Program Type

To create a transform program, in the Program Properties dialog box for the application engine program you must specify that the program type is Transform Only. After you select this option, input message name, output message name, input root element and output root element fields display.

Input and Output Message Names

When developing a transformation program, PeopleSoft Integration Broker enables you to specify the schema of the message that is going into the transform (input message and version), as well as the schema of the message that is the output of the program (output message and version).

Note. You must specify this information when using the Oracle XSL Mapper to develop transformation programs.

These fields are required when developing transformations using the Oracle XSL Mapper.

In all other cases, these fields are optional, since there may be occasions where a transformation is general in nature and used by many messages. For example, it might be a transform that changes certain fields regardless of the message shape. In cases such as these, you would not want to define a specific input or output shape, since the transform program is only changing fields.

Input and Output Root Elements

When working with nonrowset-based messages, there may be situations where the schemas for input and output messages have multiple root elements. However, Oracle XSL Mapper uses only one of the root elements on the input side as well as only one on the output side.

When using Oracle XSL Mapper to build XSLT transformations, you may specify the input and output root elements in the Program Properties dialog box. If you do not specify an input or output root element, Oracle XSL Mapper uses the first root element in the schema.

Defining a Transform Program

To define a transform program, create a new application engine object in PeopleSoft Application Designer. Then in the Program Properties dialog box you specify the program type as a transform program.

The following graphic shows the Program Properties dialog box for an application engine program. Note that the Program Type field displays Transform Only.

To define a transform program:

1. In PeopleSoft Application Designer, select File, New, App Engine Program and click the OK button.

   A new application engine program window appears.

2. On the toolbar, click the Properties button.

   The Program Properties dialog box appears.

3. Click the Advanced tab.

4. From the Program Type drop-down list box, select Transform Only.

   Additional fields relating to input messages, output messages and root elements appear.

5. Select an input message and version:

   1. From the Input Message Name drop-down list box, select the name of the message before transformation is applied.

   2. From the Input Message Version drop-down list box, select the version of the input message.

6. In the Input Root Element field, enter the name of the input schema root element to use.

   Enter a value in this field if the input message has multiple root elements. If the input message has multiple root elements and you do not enter an input root element, the first root element in the message is used for transformation.

   This field is disabled when the input message is a rowset-based message.

7. Select an output message and version.

   1. From the Output Message Name drop-down list box, select the name of the message after transformation is applied.

   2. From the Output Message Version drop-down list box, select the version of the output message.

8. In the Output Root Element field, enter the name of the output schema root element to use.

   This field is disabled when working with rowset-based messages.

9. Click the OK button.

10. The Program Properties dialog box closes.

11. Select File, Save.

Developing Transform Programs Using PeopleSoft Application Engine

This section discusses how to:

• Insert steps and actions into transform programs.

• Work with transform programs.

• Access message data.

• Make working data available globally.

• Preserve record and field aliases.

Understanding Developing Transform Programs Using PeopleSoft Application Engine

Following are some points to keep in mind when working with transform programs:

• 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.

• XSLT is not supported by PeopleSoft on the OS/390 or z/OS operating systems. Transformations must use PeopleCode on these platforms.

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.

Inserting Steps and Actions into Transform Programs

This section describes how to insert steps and actions into transform programs.

Understanding Inserting Steps and Actions

After you define a transform program, you insert steps and actions as you would with any other application engine program to construct the transformation program.

The two types of actions you can add to steps when building a transform program are XSLT and PeopleCode.

Inserting XSLT Actions

When you select XSLT as the step action type you can develop the transform code using Oracle XSL Mapper or you can hand-code the program.

Installing, configuring and using Oracle XSL Mapper to develop transform programs is discussed elsewhere in this chapter.

See Developing Transforms Using Oracle XSL Mapper.

Note. After selecting XSLT as the action type, you must save the program before you can choose to use Oracle XSL Mapper or hand-code the program.

To insert XSLT actions:

1. From the Action Type drop-down list, select XSLT.

2. (Optional.) In the XSLT Description field, enter a description for the XSLT action.

3. Save the transform program.

   A Graphical Mapper drop-down list appears.

4. Choose how to code the XSLT action:

   • To use Oracle XSL Mapper , click the XSLT action to highlight it. Then double-click the action to launch the mapper tool.

   • To hand-code the program, from the Graphic Mapper drop-down list box, select No. Right-click the action and select View XSLT.

5. Create code for the step/action.

   • If using Oracle XSL Mapper, beginning mapping records and fields as appropriate.

   • If hand-coding using XSLT, right-click the action and select View XSLT. The programming window appears and you can begin coding.

Inserting PeopleCode Actions

To insert PeopleCode actions:

1. From the Action Type drop-down list, select PeopleCode.

2. (Optional.) In the PeopleCode Description field, enter a description for the PeopleCode action.

3. Save the program.

4. Right-click and select View PeopleCode to open the programming window.

5. Enter PeopleCode appropriate for the step and action.

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 Class Methods

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

XmlDoc Classes

Tracing Application Engine Programs

Using the PSADMIN Utility

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

Developing Transforms Using Oracle XSL Mapper

This section discusses how to develop transformations using Oracle XSL Mapper.

Understanding Oracle XSL Mapper

Oracle America has developed a tool that enables you to graphically map records and fields and that creates the underlying XSLT transformation code for you. You launch this tool directly from a PeopleSoft application engine transformation program. When you save the XSLT code in Oracle XSL Mapper, it automatically gets saved to the application database and your application engine transform program.

Note. You cannot use Oracle XSL Mapper to modify XSLT that you've hand-coded or created with any other XSLT editing tool.

Oracle XSL Mapper is an Oracle JDeveloper plug-in. Check the My Oracle Support website for information about supported versions.

See http://www.oracle.com

Development Considerations

Note the following as you develop transformations using Oracle XSL Mapper:

• When you save XSL maps that you create in the mapper, the underlying XSL code is automatically saved to the application engine program.

• The mapper does not support codesets and working storage constructs. You must add these constructs manually into the XSL code using the Source view of the mapper.

Prerequisites for Developing Transforms Using Oracle XSL Mapper

To use Oracle XSL Mapper you must:

• Install Oracle JDeveloper.

  Oracle XSL Mapper is part of Oracle JDeveloper .

  See Installing Oracle XSL Mapper.

• In PeopleSoft Configuration Manager, specify the path to the Oracle JDeveloper installation location.

  See Specifying the Installation Path and Classpath for Oracle XSL Mapper.

• All messages used in the mapper must have schemas generated for them.

  For rowset-based messages, use the Message Definitions–Schema page to generate schemas. For nonrowset-based messages, use the Message Definitions–Schema page to add or import schemas for these types of messages.

  See Managing XML Message Schemas for Rowset-Based Messages, Adding XML Message Schemas to Nonrowset-Based Messages.

• You must create a Transform Only application engine program and define the program properties described earlier in this chapter.

  See Defining a Transform Program.

• If you are using Oracle JDeveloper 11g, the JDK folder and its contents must exist inside the JDeveloper home location. Therefore you must install JDK 1.6 or use an existing installation of JDK 1.6, and copy all the contents inside the <JDEV_HOME> directory. The following example shows the installation path: <JDEV11_HOME>/jdk/<jdk_copied_contents>

• If you are using Oracle 11gR2 or a later release, you must move the following folders from <Middleware_Home>\oracle_common\modules to <Middleware_Home>\jdeveloper\modules:

  • \oracle.xdk_11.1.0

  • \oracle.xmlef_11.1.1

  • \oracle.javatools_11.1.1

If you are using Oracle JDeveloper 11g, the JDK folder and its contents must exist inside the JDeveloper home location. Therefore you must install JDK 1.6 or use an existing installation of JDK 1.6, and copy all the contents inside the <JDEV_HOME> directory. The following example shows the installation path: <JDEV11_HOME>/jdk/<jdk_copied_contents>

If you are using Oracle 11gR2 or a later release, you must move the following folders from <Middleware_Home>\oracle_common\modules to <Middleware_Home>\jdeveloper\modules:

• \oracle.xdk_11.1.0

• \oracle.xmlef_11.1.1

• \oracle.javatools_11.1.1

Installing Oracle XSL Mapper

Oracle XSL Mapper is a tool that provides the ability to rapidly create XSL-based transformation maps to support integration of PeopleSoft to third-party applications deployed through Integration Broker. The Oracle XSL Mapper is a component of Oracle BPEL Designer and is included in Oracle JDeveloper. Access to this feature requires the download of Oracle JDeveloper at the location below.

See http://www.oracle.com/technology/index.html

Note. After you install Oracle XSL Mapper do not move or delete the installed jar files from the default installation location. The PeopleSoft system reads this information from the default location for proper functioning of the feature.

Specifying the Installation Path and Classpath for Oracle XSL Mapper

For Oracle XSL mapper to function, the JDeveloper installation location and classpath must be specified in the PeopleSoft system in the PeopleSoft Configuration Manager. You enter this information on the Crystal/Bus. Interlinks/JDeveloper tab shown in the following example:

To specify the path to the Oracle XSL Mapper installation location and classpath:

1. Open PeopleSoft Configuration Manager (pscfg.exe).

2. Click the Crystal/Bus. Interlink/JDeveloper tab.

3. Locate the JDeveloper Home Directory section at the bottom of the page.

4. In the JDeveloper Home field, enter the path or browse to the location where JDeveloper is installed.

5. Click the Apply button.

   If you are using JDeveloper version 10.1.3 or 10.1.2, Configuration Manager populates the JDeveloper Launch Mapper Classpath field with the appropriate variables for your version of JDeveloper.

   If you are using JDeveloper version 11.1.1 enter the following classpath in the JDeveloper Launch Mapper Classpath field:

   jdev\extensions\oracle.bpm.mapper.jar;integration\lib\bpm-ide-common.jar;
   ide\lib\javatools.jar;jdev\lib\xmleditor.jar;modules\oracle.xdk_11.1.0\
   xmlparserv2.jar;modules\oracle.xmlef_11.1.1\xmlef.jar;modules\
   oracle.javatools_11.1.1\javatools-nodeps.jar
   
   

6. Click the OK button.

Launching Oracle XSL Mapper

You launch Oracle XSL Mapper from within an application engine transform program.

The first time you launch the mapper, the Oracle JDeveloper Welcome window appears.

Note. The first time you launch Oracle XSL Mapper a Configure Tile Type Associations dialog box appears. While using the mapper you do not work with any Java files and you can disregard the dialog box.

The Oracle JDeveloper Welcome window displays only the first time you access JDeveloper. When you subsequently open Oracle XSL Mapper, the transform program appears in the Design view.

The transform program name in the mapper takes the following format:

<transform_program_name>.<section_name>.<step_name>.xsl 

To launch Oracle XSL Mapper:

1. Create a Transform Only application engine program and define the program properties described earlier in this chapter.

2. Double-click the XSLT action.

3. Access the Oracle XSL Mapper–Design view.

   When accessing the mapper for the first time, when you double-click the XSLT action and launch Oracle JDeveloper the JDeveloper Welcome window appears. To switch to the Design view, above the Source pane, click the transform file name tab or from the Window menu click the transform file name.

   In subsequent attempts to launch the mapper, double-clicking the XSLT action automatically opens the transform program in the Design view.

Accessing Oracle JDeveloper Documentation and Online Resources

This section provides information for access online Help, documentation and other resources for using Oracle XSL Mapper.

Online Help

Online Help is available via the Help menu while working with Oracle XSL Mapper.

Additional Oracle JDeveloper Documentation and Online Resources

As mentioned earlier in this section, Oracle XSL Mapper is a plug-in to Oracle JDeveloper. Documentation for the mapper is contained in the Oracle JDeveloper documentation set.

Note. The information provided in this section is current as of the publish date of this PeopleBook.

On the Developer Welcome page of the Oracle XSL Mapper there are links to documentation and online resources located on the Oracle web site.

In addition you can visit the Oracle Technology Network website to access documentation. Oracle JDeveloper documentation resources that may be helpful include:

• Oracle Application Development Framework Guidelines Manual .

• Oracle Application Development Framework Case Manual.

• Installation Guide.

• Release Notes.

• J2EE Developer Online Help (the main documentation library)

Navigating in Oracle XSL Mapper

This discusses how to:

• Navigate in the Design View.

• Navigate in the Source View.

Note. This section features a brief discussion of some of the key components and areas of the Oracle XSL Mapper development tool. The Oracle JDeveloper documentation provides in-depth details about using the Oracle XSL Mapper.

Navigating in the Design View

To access the Design view of Oracle XSL Mapper, click the Design tab at the bottom of the mapper. The following graphic shows the Oracle XSL Mapper – Design view:

Use the Design view to map records and fields.

A few of the key areas of the Design view are discussed here. For additional information on Design view features, see the Oracle XSL Mapper documentation.

Navigating in the Source View

To access the Source view of Oracle XSL Mapper, click the Source tab at the bottom or the mapper. The following graphic shows the Oracle XSL Mapper–Source view:

Use the Source view to view and edit the raw XSL code generated by the mapper.

For additional information on Source view features, see the Oracle XSL Mapper documentation.

Mapping Records and Fields

To map records and fields, you drag record names and field names from the source pane to the target pane in the mapper. The following graphic shows and example of mapping several fields:

A solid green line appears as you drag the cursor from the source pane to the target pane. When you release the cursor, the line turns blue to show the association.

To map records and fields:

1. Open the Design view of Oracle XSL Mapper.

2. Expand the contents of both the source and target panes.

   Click the plus (+) button to expand each level or section until all records and fields appear.

   Note. When working with rowset-based messages the content to map is located in the MsgData section.

3. In the source pane, click on the icon to the left of a record or field name and drag it to the name of the record or field in the target pane to which you want to map.

   Repeat this step for each record or field to map.

4. Click the Save button.

Deleting Record and Field Maps

If you have not saved the program and want to delete the last map you made, simply right click in the Design view and select Undo Link. Otherwise, follow the instructions in this section.

To delete a record or field map:

1. In the source pane, click the record or field name.

2. From the Edit menu, click Delete.

3. Save the changes.

Viewing Raw XSLT Code

After you have made all of the record and field maps for the program. Click the Source tab at the bottom of the window to generate and view the raw XSL.

Testing XSL Maps

You can test XSL maps for validity that you generate in the mapper using the Test XSL Map window shown in the following graphic:

The code created by the record and field mapping displays in the bottom portion of the window.

Note. This Oracle XSL Mapper test feature tests the validity of the XSLT map code. It does not test the transformation. To test a transformation, use the Transformation Test tool in the PeopleSoft Pure Internet Architecture.

To test XSLT code:

1. Access the Oracle XSL Mapper–Source view.

2. Right-click anywhere in the code area and select Test.

   The Test XSL Map window appears.

3. In the XSL Map section of the window, click the Validate button.

   A validation success or error message displays.

See Also

Using the Transformation Test Utility

Adding and Modifying XSL Map Code

If you add code to XSLT that you create using Oracle XSL Mapper that contains any PeopleSoft-related elements it will not compile successfully, unless you create a configuration file of PeopleSoft elements that the mapper should ignore. After you create this file specify the file location and name in the Oracle XSL Mapper Preferences.

Creating Elements to Ignore Configuration Files

For example, you could add code that contains the following elements:

<element name = "psft_function">
<element name = "psft_workingstorage">

You would create a file using the following format, which tells Oracle XSL Mapper to ignore those elements:

<?XML version='1.0' encoding='windows-1252'?>
<elements-to-ignore>
     <element name = "psft_function"/>
     <element name = "psft_workingstorage"/>
</elements-to-ignore>

Specifying Elements to Ignore Configuration Files in Oracle XSL Mapper Preferences

Once you create the file of PeopleSoft elements to ignore, enter the file location and name in the mapper Preferences dialog box. The following graphic shows the Preferences dialog box:

To specify an elements to ignore configuration file in Oracle XSL Mapper preferences:

1. In Oracle XSL Mapper, from the Tools menu, select Preferences.

   The Preferences dialog appears.

2. In the list on the left-side of the window, click XSL Maps.

3. In the Elements to Ignore Conf. File (Requires Restart) field, enter or browse to the location of the elements to ignore configuration file that you created.

4. Click the OK button.

You must restart Oracle JDeveloper for the system to recognize the configuration file.

Invoking Transform Programs

Your transform program is invoked by PeopleSoft Integration Broker if you specify its name in the a routing definition for a service operation.

Accessing Transform 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.

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.

Renaming or Deleting Transform Programs

To invoke a transform program, you specify it as part of a routing definition. If you subsequently rename or delete that transform program, it still appears in the routing definition, so service operations 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 routing definitions that apply it.

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

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 in emphasis):

<?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/

Applying Message Transformations at the Integration Gateway

Typically, you apply filtering, transformation, and data translation to a message at the node level on the application server by using a transaction modifier to invoke an Application Engine transform program. However, on systems with high transaction volumes, Application Engine transformations can constrict message throughput. To improve performance, you can apply XSLT transformation programs at an integration gateway.

Note. While you may apply transformations at the integration gateway level, PeopleSoft strongly recommends that you apply them at the application server level due to a more robust infrastructure to support them.

See http://www.apache.com

Understanding Applying Message Transformations at the Integration Gateway

Only XSLT transformations can be applied at the gateway. Message filtering, data translation, and PeopleCode transformations must still be applied at the node using an Application Engine transform program, and can be applied in addition to gateway-based transformations.

You can apply XSLT transformations at any gateway that handles the message you want to transform.

When a gateway with transformation enabled processes an IBRequest, it examines the transformation properties in the integrationGateway.properties file to determine if they specify a transformation for the same message with the same source and target nodes as the IBRequest. If these values match, the gateway compiles the specified XSLT transformation program and applies it to the message, then sends the transformed message to the target node.

Note. The IBRequest can specify only a RequestingNode or only a DestinationNode, but it must specify at least one of these values—ig.DefaultServer.LocalNode supplies the other one.

With synchronous transactions, the gateway applies transformations only to the request message, not to the response message. If the original message is compressed and base64 encoded, the gateway decompresses and decodes it before applying the transformation, then compresses and encodes it again before sending.

Note. The integration gateway retains all compiled XSLT transformation programs in a memory cache to improve performance during subsequent transformations. If you edit the code of a transformation program that’s been used before, you must purge the compiled programs from the cache so the new version will be recompiled. To do this, click the Refresh button on the gateway definition.

Developing and Implementing Gateway-Based Transformation Programs

Developing and implementing gateway-based transform programs requires the following activities:

1. Determine if the message you want to transform qualifies for gateway-based transformation:

   • The message content must be XML-DOM compliant.

   • The message must not have nonrepudiation activated.

2. Develop the XSLT transformation program.

   See Applying Transformations.

   You can develop, test and debug the program within Application Engine, but you must save the program code as an external text file. Place the file in any location that can be accessed from the integration gateway machine, for example:

   C:\XSLProgs\MyTransform.xsl

3. Configure the appropriate gateway property settings in the integrationGateway.properties file to enable the transformation.

   See Setting Integration Gateway Properties for Gateway-Based Transformations.

4. Refresh the gateway properties.

Setting Integration Gateway Properties for Gateway-Based Transformations

To apply gateway-based transformations, set the following properties in the integrationGateway.properties file.

For each message you want to transform, you must create a set of property entries using the same number, which associate a given transformation program with that message. However, you can specify the same transformation program for multiple messages.

When entering these settings, each transformation must be numbered for identification, using the convention ig.transform1, ig.transform2, ig.transform3, and so on.

ig.DefaultServer.LocalNode=DEF_NODE

ig.transforms=7

ig.transform4.XSL=C:\\XSLProgs\\MyTransform.xsl
                
ig.transform4.XSL=C:/XSLProgs/MyTransform.xsl
                
ig.transform4.XSL=/usr/xsls/MyTransform.xsl

ig.transform4.MessageName=MY_MSG_A

ig.transform4.SourceNode=NODE_Aig.transform4.
SourceNode=ANY

ig.transform4.DestinationNode=NODE_Big.transform4.
DestinationNode=ANY

ig.transform4.DestinationMessageName=MY_MSG_B

Understanding Logged Errors

If an error occurs when you refresh the gateway properties or during a transformation, it’s entered in the gateway’s error log file.

Integration Gateway Refresh Errors

After you specify integration gateway properties and refresh the gateway, errors can be generated for the following reasons:

• No value is specified for ig.transformN.XSL.

• No value is specified for ig.transformN.MessageName.

• No value is specified for both ig.DefaultServer.LocalNode and ig.transformN.SourceNode.

• No value is specified for both ig.DefaultServer.LocalNode and ig.transformN.DestinationNode.

• The gateway is in the process of loading, compiling or caching a transformation program.

Runtime Transformation Errors

Errors are generated for the following reasons when the gateway attempts to apply a transformation:

• Nonrepudiation is enabled for the message.

• The integration gateway is unable to transform the message.

• The integration gateway is unable to decompress and decode the message.

• The integration gateway is unable to compress and encode the message.

• The IBRequest does not specify a RequestingNode and no value is specified for ig.DefaultServer.LocalNode.

• The IBRequest does not specify a DestinationNode and no value is specified for ig.DefaultServer.LocalNode.

• The IBRequest specifies neither a RequestingNode nor a DestinationNode.

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 (IB_CODESETGRPVAL) 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 (IB_CODESET) 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 (IB_CODESETVAL) 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.

Runtime invocation of codesets in XSLT is a two part process: first the input document is transformed and then all instances of psft_function are resolved in the output document.

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 routing; 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:

<?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>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="">
      <name>pencil</name>
      <qty>15</qty>
      <uom>Carton</uom>
      <type>Bic</type>
   </li>
   <li id="">
      <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").
   Node Value;
Local string &statusCode = &tempDoc.DocumentElement.FindNode("STATUS_CODE").
   Node Value;

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

Rejecting Transformation Programs

Situations may arise when you may want to terminate a transaction. For example, you may not want a transaction published to a specific node.

Using the %TransformData.rejectTransform property and the %IB_Transform_Rejected built-in function, you can terminate asynchronous transactions based on content data.

You set this property in a PeopleSoft Application Engine transform program as follows:

%TransformData.rejectTransform = %IB_Transform_Rejected;

If you set the %TransformData.rejectTransform property within a transform of an inbound asynchronous transaction, the system will not create a subscription contract and the data is not sent. If you view such a transaction in the Service Operations Monitor, the Operation Instances page displays a status of Done. If you open the Asynchronous Details page in the monitor, an Error link displays. If you click the link an informational message appears that indicates that the transaction was terminated.

If you set this property for an outbound asynchronous transaction, the Publication Contracts page in the Service Operations Monitor will show a contract status of Done for the transaction. However, the system does not send the message and, as with the inbound scenario, the Asynchronous Details page for the transaction will display an Error link. If you click the link an informational message appears that indicates that the transaction was terminated.

See Also

Asynchronous Service Operation Statuses

Monitoring Asynchronous Service Operation Instances

Viewing Asynchronous Service Operation Details

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.

PeopleSoft 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 Service Operations 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.