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.
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.
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 topic.
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:
From the Action Type drop-down list, select XSLT.
(Optional.) In the XSLT Description field, enter a description for the XSLT action.
Save the transform program.
A Graphical Mapper drop-down list appears.
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.
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:
From the Action Type drop-down list, select PeopleCode.
(Optional.) In the PeopleCode Description field, enter a description for the PeopleCode action.
Save the program.
Right-click and select View PeopleCode to open the programming window.
Enter PeopleCode appropriate for the step and action.
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>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");
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 8192Add the value 8192 to the TRACEAE parameter in the appropriate application server or Process Scheduler server configuration file, for example:
TRACEAE=8192