XSLTransform policy

What

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

Inputs

The XSL policy takes the following inputs:

  • (Required) The name of an XSLT stylesheet, which contains a set of transformation rules stored in the API proxy under /resources/xsl.
  • (Required) The XML to be transformed (typically a request or response message).
  • (Optional) The name of a variable that stores the output.
  • (Optional) Parameters that match parameters in the XSL stylesheet.

Parsing processor

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

Unsupported XSL elements

The XSL policy does not support the following XSL elements:

  • <xsl:include>
  • <xsl:import>

Samples

The following samples show an XSL transformation flow:

XSL policy -->

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

Simple XSL policy. Go to the next example to see the XSLT stylesheet referenced in the policy (my_transform.xsl). The <Source> element is important. For example, if the XML you want to transform is in the response, the transformation won't occur unless you set the <Source> to response (and the policy is attached to the response flow). But in this case, the XML to be transformed is in the request.

XSLT stylesheet -->

<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. Go to the next sample to see an example of an incoming XML message.

Message -->

<?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>request</Source> element in the first sample).

Transformed message

<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 after the XSLT stylesheet from these samples is applied to the XML message.

<XSL> element

Defines an XSLTransform policy.

Default Value n/a
Required? Required
Type Complex object
Parent Element n/a
Child Elements <OutputVariable>
<Parameters>
<ResourceURL>
<Source>

The <XSL> element has the following attributes:

Attribute Description Required? Type
name Name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Apigee UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric. Required String

Child element reference

This section describes the child elements of <XSL>.

<OutputVariable>

A variable that stores the output of the transformation. You should set this element to be a custom variable, and then consume that variable.

Default Value n/a
Required? Optional
Type String
Parent Element <XSL>
Child Elements None

The value of <OutputVariable> cannot be a message type; that is, it cannot be message, request, or response.

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.

<Parameters>

Adds support for the <xsl:param> element in your stylesheets. You define each parameter as a <Parameter> child element of this element.

Default Value n/a
Required? Optional
Type Array of <Parameter> elements
Parent Element <XSL>
Child Elements <Parameter>

The <Parameters> element has the following attributes:

Attribute Description Required? Type
ignoreUnresolvedVariables Determines if the policy ignores any unresolved variable errors in the XSLT script instructions. The default value is false, which means that, by default, the policy will throw errors if it encounters unresolved variables. Optional Boolean

<Parameter>

Defines a parameter in the <Parameters> element.

Default Value n/a
Required? Optional
Type Complex object
Parent Element <Parameters>
Child Elements None

The <Parameter> element has the following attributes:

Attribute Required? Type Description
name Required String

The name of the parameter. Apigee matches the value you set here with the value of the name attribute on an <xsl:param> element in the stylesheet.

For example, if you enter a name of uid, your XSL might look something like the following:

<xsl:param name="uid" select="''"/>
ref Optional String

Points to a context variable that holds the value for the parameter. Values for the ref context variables must be set prior to the evaluation of this policy.

For example, if a uid parameter needs to get its value from a variable called authn.uid, the <Parameter> element would look like the following:

<Parameter name="uid" ref="authn.uid"/>

If you use this attribute, don't use the value attribute.

value Optional String

Specifies a hard-coded value for the parameter. For example, if a parameter named answer should have the value 42, the <Parameter> element would look like the following:

<Parameter name="answer" value="42"/>

If you use this attribute, don't use the ref attribute.

The parameter gets its value either from the ref attribute or with an explicit value.

For an example and more information, see How should the optional parameters on the XSL Transform policy be used?.

<ResourceURL>

The XSL file that Apigee uses for transforming the message. The value of this element is the name of the XSL stylesheet stored in the API proxy under /resources/xsl.

Default Value n/a
Required? Required
Type String
Parent Element <XSL>
Child Elements None

For example:

<ResourceURL>xsl://SubscriberNumbers-Request.xsl</ResourceURL>

For more information, see resource files.

<Source>

Specifies the message that is transformed. Usually this value is set to request or response, depending on whether the message to be transformed is inbound or outbound.

Default Value n/a
Required? Optional
Type String
Parent Element <XSL>
Child Elements None

The XSL file that defines the transformation is defined by the <ResourceURL>.

  • If the 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.

Error reference

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.xsl.XSLSourceMessageNotAvailable 500 This error occurs if the message or string variable specified in the <Source> element of the XSLTransform policy is either out of scope (not available in the specific flow where the policy is being executed) or can't be resolved (is not defined).
steps.xsl.XSLEvaluationFailed 500 This error occurs if the input XML payload is unavailable/malformed or the XSLTransform policy fails/is unable to transform the input XML file based on the transformation rules provided in the XSL file. There could be many different causes for the XSLTransform policy to fail. The reason for failure in the error message will provide more information on the cause.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
XSLEmptyResourceUrl If the <ResourceURL> element in the XSLTransform policy is empty, then the deployment of the API proxy fails.
XSLInvalidResourceType If the resource type specified in the <ResourceURL> element of the XSLTransform policy is not of type xsl, then the deployment of the API proxy fails.

Related topics