XSLTransform policy

Extensible policy

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

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.

This policy is an Extensible 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, see Policy types.

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

运行时错误

政策执行时可能会发生这些错误。

故障代码 HTTP 状态 原因 修复
steps.xsl.XSLSourceMessageNotAvailable 500 如果在 XSLTransform 政策的 <Source> 元素中指定的消息或字符串变量超出范围(在执行政策的特定流程中不可用)或无法解决(未定义),则会发生此错误。
steps.xsl.XSLEvaluationFailed 500 如果输入 XML 载荷不可用/格式不正确,或者 XSLTransform 政策失败/无法根据 XSL 文件提供的转换规则转换输入 XML 文件,就会出现此错误。很多不同的原因可能会导致 XSLTransform 政策失败。错误消息中的失败原因提供了有关原因的更多信息。

部署错误

在您部署包含此政策的代理时,可能会发生这些错误。

错误名称 原因 修复
XSLEmptyResourceUrl 如果 XSLTransform 政策中的 <ResourceURL> 元素为空,则 API 代理的部署将会失败。
XSLInvalidResourceType 如果在 XSLTransform 政策的 <ResourceURL> 元素中指定的资源类型不是 xsl 类型,则该 API 代理的部署将会失败。

Related topics