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 Apache Website.

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

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.

Property

Description

ig.isGatewayTransformationEnabled

Specify whether transformation is enabled for this gateway. Valid values are:

  • TRUE. Transformation is enabled.

  • FALSE. Transformation is disabled — the integration gateway will ignore the other transformation properties. This is the default value.

ig.DefaultServer.LocalNode

Enter the name of the node definition that will be used as the source or destination node for a given transformation if either of those values isn’t identified; for example you must specify:

ig.DefaultServer.LocalNode=DEF_NODE

All transformations require that you specify both a source node and a destination node. This property applies if either the ig.transformN.SourceNode property or the ig.transformN.DestinationNode property is empty or invalid, or if the IBRequest doesn’t specify either RequestingNode or DestinationNode.

ig.transforms

Specify the number of transformations configured in the integrationGateway.properties file; for example:

ig.transforms=7

ig.transformN.XSL

Enter the full path and filename of transformation program N.

Your path specification must use either double back slashes or single forward slashes as separators; for example:

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

ig.transformN.MessageName

Enter the name of the message to be transformed by transformation program N; for example: 

ig.transform4.MessageName=MY_MSG_A

ig.transformN.SourceNode

Enter the name of the source node from which the original message is being sent, or enter the value ANY; for example:

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

If this value is ANY, the value of the ig.DefaultServer.LocalNode property will be used instead.

ig.transformN.DestinationNode

Enter the name of the target node to which the transformed message is being sent, or enter the value ANY; for example:

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

If this value is ANY, the value of the ig.DefaultServer.LocalNode property will be used instead.

ig.transformN.DestinationMessageName

(Optional.) Enter the name that the target node uses for the transformed version of the message, if it’s different from the original message name; for example:

ig.transform4.DestinationMessageName=MY_MSG_B

This enables the gateway to rename the message before sending it, so the target node will recognize and accept it.

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.