—Rate this article—
 

XSL Transform policy

 XSL Transform policy

About | Samples | Element reference | Usage notes | Error codes | Related topics

What

The XSL Transform policy applies custom Extensible stylesheet language transformations (XSLT) to XML messages, letting you transform them from XML to another format, such as XML, HTML, or plain text. The policy is often used to integrate applications that support XML, but that require different XML-formats for the same data.

Where

This policy can be attached in the following locations, but see the notes following the table for specific guidance.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    Response
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

Samples

<XSL name="TransformXML">
  <ResourceURL>xsl://my_transform.xsl</ResourceURL>
  <Source>request</Source>
</XSL>

Simple XSL policy

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
  <xsl:output method="text"/>
  <xsl:variable name="newline">
  <xsl:text>
  </xsl:text>
  </xsl:variable>
  <xsl:template match="/">
  <xsl:text>&lt;Life&gt;</xsl:text>
    <xsl:value-of select="$newline"/>
    <xsl:text>Here are the odd-numbered items from the list:</xsl:text>
    <xsl:value-of select="$newline"/>
    <xsl:for-each select="list/listitem">
      <xsl:if test="(position() mod 2) = 1">
        <xsl:number format="1. "/>
        <xsl:value-of select="."/>
        <xsl:value-of select="$newline"/>
      </xsl:if>
    </xsl:for-each>
  <xsl:text>&lt;/Life&gt;</xsl:text>
</xsl:template>
</xsl:stylesheet>

The my_transform.xsl stylesheet referenced in the policy

<?xml version="1.0"?>
<list>
  <title>A few of my favorite albums</title>
  <listitem>A Love Supreme</listitem>
  <listitem>Beat Crazy</listitem>
  <listitem>Here Come the Warm Jets</listitem>
  <listitem>Kind of Blue</listitem>
  <listitem>London Calling</listitem>
  <listitem>Remain in Light</listitem>
  <listitem>The Joshua Tree</listitem>
  <listitem>The Indestructible Beat of Soweto</listitem>
</list>

Sample message in the request (indicated in the policy's <Source> element)

<Life>
Here are the odd-numbered items from the list:
1. A Love Supreme
3. Here Come the Warm Jets
5. London Calling
7. The Joshua Tree
</Life>

The transformed message


Element reference

Configure an XSL Transformation policy using the following elements.

<xsl:include> and <xsl:import> are not supported.

Field Name Description
Name (Mandatory) Name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

 

Source (Optional) Contains the message from which information needs to be extracted. Usually this value is set to request or response, depending on whether the message to be transformed is inbound or outbound.
  • If source is missing, it is treated as a simple message. For example, <Source>message</Source>
  • If the source variable cannot be resolved, or resolves to a non-message type, the transformation step fails.
OutputVariable (Optional)

A variable that stores the output of the transformation. The OutputVariable cannot be of Message type, that is, it cannot be 'message', 'request', or 'response'. You should set this element to be a custom variable, and then consume that variable.

To replace the message content with the output of the transformation, delete this element. For example, if you're transforming a message to HTML, don't include this element.

ResourceURL (Mandatory) The XSLT file to be used for transforming the message.
Parameters (Optional) ignoreUnresolvedVariables (Optional)
Ignores any unresolved variable errors in the XSLT script instructions.
Valid values: true/false
Default value: false
Parameter (Optional) name (Mandatory) Name of a custom parameter. Note that with name you can only use one of the optional parameters listed below.
ref (Optional)
Specifies the reference that sources the value from a variable.
value (Optional) Value of the parameter.

See our GitHub repository samples for the most recent schemas.


Usage notes

The XSLT is implemented in a stand-alone .xsl file, which is stored in the API proxy under /resources/xsl. The XSL policy merely references the XSL file. See Resource files for more.

The XSL policy requires two inputs:

  • The name of an XSLT stylesheet, which contains a set of transformation rules) stored in the API proxy under /resources/xsl
  • The source of the XML to be transformed (typically a request or response message)

<xsl:include> and <xsl:import> are not supported.

Apigee Edge relies on the Saxon XSLT processor, and supports XSLT 1.0 and 2.0.


Error codes

The default format for error codes returned by Policies is:

{
  "code" : " {ErrorCode} ",
  "message" : " {Error message} ",
  "contexts" : [ ]
}

The XSLT policy type defines the following error codes:

Error Code Message
XSLSourceMessageNotAvailable {0} message is not available for XSL: {1}
XSLEvaluationFailed Evaluation of XSL {0} failed with reason: "{1}"
XSLVariableResolutionFailed Failed to resolve variable {0}
XSLInvalidResourceType XSL {0}: Resource type must be xsl. Context {1}
XSLEmptyResourceUrl Resource Url cannot be empty in XSL {0}

Related topics

For working samples of API proxies that use this policy, see the Samples reference. Or just go straight to Github:

 

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)