Was this helpful?

Extensible stylesheet language transformations (XSLT) is a language for converting documents from one XML format to another XML format. It is often used to integrate applications that support XML, but that require different XML-formats for the same data.

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

The XSL policy type enables XSLT to execute as a processing step in an API proxy flow. The XSLT is implemented in a stand-alone .xslt file, which is stored in the API proxy under /resources/xsl. The XSL policy merely references the XSL file.

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)


A simple XSL policy is:

<XSL name="TransformXML">

There are many tools and resources on the Internet implementing XSLT. For reference, below are some XSLT examples with sample request messages and transformed messages.

XSLT file

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
  <xsl:output method="text"/>
  <xsl:variable name="newline">
  <xsl:template match="/">
    <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"/>

Request Message

<?xml version="1.0"?>
  <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>

Transformed message

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

Configuring an XSL Transformation policy

Configure an XSL Transformation policy using the following elements.

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

Field Name Description
Name (Mandatory) Name of the policy.
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.
Or, leave the element blank. When the OutputVariable is not specified, the message content is replaced with the output of the transformation, which is typically the desired behavior.
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.
In the XSL example below, if request.header.greeting is null, ignoreUnresolvedVariables responds in one of two ways:
  • If ignoreUnresolvedVariables is false, an exception is raised.
  • If ignoreUnresolvedVariables is true, the p2 parameter is not passed to the XSL processor.
value (Optional) Value of the parameter.

Policy-specific 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}

Policy schema

Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.

Add new comment

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.