XSLTransform policy
This pageapplies toApigee andApigee hybrid.
View Apigee Edge documentation.
The XSLTransform policy applies customExtensible 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.
This policy is anExtensible policy and use of this policy might have cost or utilization implications, depending on your Apigee license. For information on policy types and usage implications, seePolicy types.
Note: This policy transforms XML only if theContent-Type header on the message to be transformed is set to XML. For example,text/xml orapplication/xml.Note:The XSL Transform policy does not support reading, loading, or manipulating XML external entities (XXEs).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 theSaxon 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> toresponse (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:stylesheetxmlns:xsl="http://www.w3.org/1999/XSL/Transform"version="1.0"><xsl:outputmethod="text"/><xsl:variablename="newline"><xsl:text></xsl:text></xsl:variable><xsl:templatematch="/"><xsl:text><Life></xsl:text><xsl:value-ofselect="$newline"/><xsl:text>Herearetheodd-numbereditemsfromthelist:</xsl:text><xsl:value-ofselect="$newline"/><xsl:for-eachselect="list/listitem"><xsl:iftest="(position() mod 2) = 1"><xsl:numberformat="1. "/><xsl:value-ofselect="."/><xsl:value-ofselect="$newline"/></xsl:if></xsl:for-each><xsl:text></Life></xsl:text></xsl:template></xsl:stylesheet>
Themy_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 Supreme3. Here Come the Warm Jets5. London Calling7. The Joshua Tree</Life>
The transformed message after the XSLT stylesheet from these samples is applied to the XML message.
<XSL> element
Defines anXSLTransform policy.
| Default Value | n/a |
| Required? | Required |
| Type | Complex object |
| Parent Element | n/a |
| Child Elements | <OutputVariable><Parameters><ResourceURL><Source> |
<xsl:include> and<xsl:import> are not supported.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, theApigee 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 amessage type; that is, it cannot bemessage,request, orresponse.
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 isfalse, 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 For example, if you enter a name of <xsl:paramname="uid"select="''"/> |
ref | Optional | String | Points to a context variable that holds the value for the parameter. Values for the For example, if a <Parameter name="uid"ref="authn.uid"/> If you use this attribute, don't use the |
value | Optional | String | Specifies a hard-coded value for the parameter. For example, if a parameter named <Parameter name="answer"value="42"/> If you use this attribute, don't use the |
The parameter gets its value either from theref attribute or with an explicitvalue.
For an example and more information, seeHow 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, seeresource files.
<Source>
Specifies the message that is transformed. Usually this value is set torequest orresponse, 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 theXSLTransform 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). | build |
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. | build |
Deployment errors
These errors can occur when you deploy a proxy containing this policy.
Need help resolving an error? Clickbuild next to the error's cause description to visit the troubleshooting page.| Error name | Cause | Fix |
|---|---|---|
XSLEmptyResourceUrl | If the<ResourceURL> element in theXSLTransform policy is empty, then thedeployment of the API proxy fails. | build |
XSLInvalidResourceType | If the resource type specified in the<ResourceURL> element of theXSLTransform policy is not of typexsl, then the deployment of the API proxy fails. | build |
Related topics
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-17 UTC.