XSLTransform policy

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

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.

Samples

The following samples show all the resources in 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.

Element reference

Configure an XSL Transformation policy using the following elements.

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)

Parameters support the use of XSL param in your stylesheets, where the name you add here in the policy is the name of the XSL param. For example, if you enter a name of "uid", your XSL might look something like this: <xsl:param name="uid" select="''"/>).

The param gets its value either from a reference to a context variable (identified by the ref attribute) or with an explicit value.

For an example and more information, see http://community.apigee.com/questions/1860/how-should-the-the-optional-parameters-on-the-xsl.html#answer-1864.
ref (Optional)

Specifies the reference that sources the value from a variable. For example, if a "uid" parameter needs to get its value from a variable called "authn.uid", the Parameter element would look like this: <Parameter name="uid" ref="authn.uid"/>

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

You can use this attribute to hard code the value of the parameter.

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

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 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 XSL Transform 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 XSL Transform policy is empty, then the deployment of the API proxy fails.
XSLInvalidResourceType If the resource type specified in the <ResourceURL> element of the XSL Transform policy is not of type xsl, then the deployment of the API proxy fails.

Related topics