Apply XSL Transformation Assertion

The Apply XSL Transformation assertion lets you define or specify an XSL stylesheet using the XSL Transformations (XSLT) language. You can define a stylesheet any of the following ways:
gateway83
The
Apply XSL Transformation
assertion lets you define or specify an XSL stylesheet using the XSL Transformations (XSLT) language. You can define a stylesheet any of the following ways:
  • Configured in advance:
    Hard code a stylesheet in this assertion; this is embedded within the policy and is always used for transformations
  • Monitor a URL:
    Policy Manager will monitor a specific URL and download the latest stylesheet
  • Fetch URL during process:
    The stylesheet will be fetched from a URL within a message.
The XSLT stylesheet specified in this assertion is applied to the message when the policy is run. The transformed message is the one that is processed by subsequent policy assertions and is eventually forwarded to the requestor (response) or service (request).
A policy can contain an Apply XSL Transformation assertion for both request and response messages. If the assertion is for a
Request,
position it
before
the routing assertion; if it is for a
Response,
position it
after
the routing assertion.
To learn about selecting the target message for this assertion, see Select a Target Message.
(1) For security reasons, the Apply XSL Transformation assertion does not support XSL stylesheets or documents originating from external URIs (it ignores calls using the
import
or
include
elements or the
document()
function). For more information about these elements, please refer to http://www.w3.org/TR/xslt. (2) The Apply XSL Transformation assertion will use the encoding of the current message for transformations; the XSL output encoding is ignored. (3) To reference a context variable from this assertion, that variable must be defined in an
<xsl:param>
element near the top of the stylesheet, within the
<XSL:stylesheet>
element.
Context Variables Created by This Assertion
The Apply XSL Transformation assertion sets information about the
<xsl:message>
element in the following context variables:
<prefix>.
messages
<prefix>
.
messages.first
<prefix>
.
messages.last
Where:
  • <prefix>
    is defined in the assertion properties (default:
    xslt
    )
  • messages
    returns all the message elements in a multivalued context variable; individual elements are available using indexing
  • messages.first
    returns the first message element (this is a "shortcut" variable that is equivalent to
    ${<prefix>.messages[0]})
  • messages.last
    returns the last message element (this is a shortcut variable that is equivalent to
    ${<prefix>.messages[n]}
    , where 'n' is the index of the last item, if known ahead of time}
Using the Assertion
  1. Do one of the following:
    • To add the assertion to the Policy Development window, see Add an Assertion.
    • To change the configuration of an existing assertion, proceed to step 2 below.
  2. When adding the assertion, the XSL Transformation Properties automatically appear; when modifying the assertion, right-click
    <target>:
    Apply XSL Transformation
    in the policy window and choose
    XSL Transformation Properties
    or double-click the assertion in the policy window. The assertion properties are displayed.
  3. Choose the target of the transformation:
    • Request:
      Transformation will be applied to the request message.
    • Response:
      Transformation will be applied to the response message.
    • Other Context Variable:
      Transformation will be applied to the specified context variable. This context variable must be of type "message" and must be predefined or has been set in the policy prior to the Apply XSL Transformation assertion. For more information on Message variables, see "Context Variable Data Types" under Context Variables.
      The message target can also be set outside of the assertion properties. For more information, see Select a Target Message.
  4. Indicate which part of the request will be affected by the transformation under the
    Apply to MIME part
    setting:
    • Enter 
      0
       to transform the SOAP message only
    • Enter 
      1
       to transform the first attachment to the message only
    • Enter higher values to transform the 
      N
      th attachment to a message (2 = transform second attachment, 3 = transform third attachment, etc.)
      The Apply XSL Transformation assertion transforms only one MIME part at a time. You can add multiple assertions to the policy if there are several MIME parts to transform.
  5. From the Stylesheet Location drop-down list, specify where the stylesheet is coming from:
    Stylesheet Location
    Description
    Configured in advance
     
    Choose this option to define an XSLT stylesheet that will be embedded in the policy and used for all transformations.
    1. Specify the transformation using any of the following methods:
      • Manually type the code into the
        XSLT Stylesheet
        box or copy and paste the code from another source.
      • Load the transformation from a URL by clicking [
        Fetch URL
        ] and then typing in the URL.
        Tip:
        To configure options for the URL (for example, to specify the credentials, SSL, or proxy options), click [HTTP Options] to open the Manage HTTP Options dialog.
      • Load the transformation from a local file by clicking [Read File] and then browsing to the appropriate file.
        The XSLT stylesheet maximum size is controlled by the
        xslDownload.maxSize
        cluster property.
    2. Review the content of the
      XSL Stylesheet
      box and edit if necessary. You can right-click within the box for some useful tools to help you edit. For more information, see Use the XML Editor.
      You can use context variables in this assertion by inserting xsl:param statements into the
      XSL Stylesheet
      box. The values of the matching context variables will be passed to the compiled stylesheet. For example, to use the variable ${foo} inside a stylesheet, use this syntax:
      <xsl:param name="foo" select="''"/>
      <xsl:variable name="bar" select="$foo"/>
    3. Optionally enter a name for the transformation in the Stylesheet Name field. This name will appear next to the assertion name in the policy development window. This will help you recognize the transformations more easily.
    Monitor URL for latest value
     
    Choose this option to continuously monitor a location to ensure the latest stylesheet is used. Type the address in the URL to monitor field. The URL may contain context variables that will be resolved at run time. By default, Gateway will download the stylesheet from this address every 5 minutes.
    (1) To configure options for the URL (for example, to specify the credentials, SSL, or proxy options), click [HTTP Options] to open the Manage HTTP Options dialog. (2) The XSLT stylesheet maximum size is controlled by the  
    xslDownload.maxSize
    cluster property.
    Fetch from URL in processing instruction
    (applicable only to non-SOAP messages)
    Choose this option to have Gateway retrieve the stylesheet from a recognizable URL within a non-SOAP message.
    1. Define a list of regular expressions ("Regex") to ensure that stylesheets are retrieved from only legitimate URLs:
      • To add an expression, click [
        Add
        ] and then enter a regular expression
      • To modify an expression, choose the expression and then click [
        Edit
        ]
      • To remove an expression, choose the expression and then click [
        Remove
        ].
         You can add multiple expressions if necessary. You must define at least one expression.
        Example
        You can enter an explicit URL, such as
        http://somedomain.com/xsl/stylesheet.xsl
        or you can enter a regex expression such as http[s]?://.*?/.*t\.xsl
        This expression will allow:
        http://hugh.l7tech.com/xsl/OrderProduct-request.xsl
        But it will disallow:
        http://hugh.l7tech.com/xsl/harmless.xsl
        To learn about regular expressions, visit http://www.regular-expressions.info/
    2. In the Allow messages with no stylesheet declaration check box, indicate whether stylesheet references are mandatory.
      • Select this check box to permit SOAP messages to have no stylesheet declarations
      • Clear this check box to enforce that every SOAP message must have a URL pointing to an XSLT stylesheet to transform the message. If none if found, a SOAP fault is generated.
  6. Select the appropriate XSLT version from the drop down.
  7. Enter a prefix that will be added to the context variables created by this assertion. This prefix will ensure uniqueness and will prevent the variables from overwriting each other when multiple instances of this assertion appear in a policy.The default variable prefix is
    xslt
    . For an explanation of the validation messages displayed, see "Context Variable Validation" in Context Variables.
  8. Click [
    OK
    ].