Evaluate Response XPath Assertion
The Evaluate Response XPath assertion is used to configure a specific XPath query pattern for outgoing XML response messages. This assertion can be used, for example, to break a policy into different paths for different types of operations and/or to provide preferential routing to special customers or high dollar value transactions.
Evaluate Response XPathassertion is used to configure a specific XPath query pattern for outgoing XML response messages. This assertion can be used, for example, to break a policy into different paths for different types of operations and/or to provide preferential routing to special customers or high dollar value transactions.
This assertion requires familiarity with XPath patterns and specifications. Be sure to place this assertion
afterthe routing assertion in a policy.
The Evaluate Response XPath assertion can be used for message validation if inclusive namespaces are not used in the messages.
Context Variables Created by This Assertion
The XPath query targets specific parts of the message, evaluating its document structure and/or XML data. When the assertion executes, it runs the XPath pattern against the response, setting six context variables according to the processing result of the query. The following table describes the default context variables set by the Evaluate Response XPath assertion.
When the Evaluate Response XPath assertion is used in a policy fragment
andyou need the context variables in the table below available to the parent policy, be sure to include the Export Variables from Fragment Assertion within the policy fragment to ensure that the variables are available to the parent policy.
Context variables created by the Evaluate Response XPath assertion returns XML in their exclusive canonicalized form. For example, one side effect could be character entities in XML such as
サポresulting in their respective special characters (??) when XPathed. For detailed information about Canonicalized XML, refer to: https://tools.ietf.org/html/rfc3076
The content of this variable depends on the match found:
Consider the following sample XML document:
responseXpath.resultvariable will be set as follows:
responseXpath.resultexcept that it contains all values matched rather than just the first one. Using the above example, the XPath expression "/test/data" will yield "hello" and "world" in the variable.
Contains the resulting text of the query. Similar to the
responseXpath.resultvariable, except this includes the entire element (including start and end tags).
This variable contains values of type String.
responseXpath.elementexcept that it contains all values matched rather than just the first one.
This variable contains values of type Element.
You cannot use
requestXpath.elementis required, as assertions that expect an 'Element' value will not work with a 'String' value.
Contains the number of nodes found, which will be >= 1 if the expression matched.
Either "true" or "false", depending on whether the XPath expression matches the response.
Assume you have the Xpath “/foo” matching against the document:
<foo>a b c <d>e f g h</d> i j k l</foo>
- The.foundsuffix returns the String value “true”.
- The.resultsuffix returns the “node value” of the first matching node as a String. This is the concatenated value of all text nodes in the element and its children, per the XPath recommendation. In this example, the result is the string “a b c e f g h i j k l”.
- The.resultssuffix creates a multi-valued context variable that includes one value corresponding to the.resultsuffix for each element that matched the XPath. In this example, because only one element was matched,.resultshas a single value matching the value of.result.
- The.elementsuffix returns the entire element as type String. For example, if it matched the <foo> element, this would be the string "<foo>a b c <d>e f g h</d> i j k l</foo>”.
- The.elementssuffix returns all matching Element values as a multi-valued context variable containing one or more values of type Element. Unlike ".resultvs..results", the types differ between.elementand.elements. The suffix.elementis a single value of type String; the suffix.elementscan be potentially multiple values of type Element.This is the reason why constructs that require the actual element context within a document (rather than just a String approximation of the element) need to use the.elementsconstruction.
The values stored in context variables can be used in a subsequent Gateway Audit Events window to view the XPath query results.
If the variables from several Evaluate Response XPath assertions need to be available simultaneously (for example, an upcoming Compare Expression Assertion is used to compare the results), then each assertion must use a different prefix. For example: You define the new variable prefix
newPrefixin the Evaluate Response XPath assertion. Now instead of the default names shown in the table above, this assertion will create variables named
newPrefix.found, and newPrefix.element.
Since a single variable namespace is shared during the entire processing of a message, the prefixes used in both the Evaluate Response XPath and Evaluate Request XPath assertions must be unique. If the same variable prefix is used in both, then one assertion will overwrite the other's variables.
If the XPath is a Boolean expression, the assertion succeeds only if the Boolean expression evaluates to "true". If the XPath selects nodes, the assertion succeeds only if the list of matching nodes is non-empty. In any other case, including an XPath error, the assertion fails.
The Evaluate Response XPath assertion supports the XPath 1.0 standard.
Using the Assertion
- Do one of the following:
- To add the assertion to the Policy Development window, see Add an Assertion.
- To change the configuration of an existing assertion, proceed to step 2 below.
- Follow the appropriate section below to complete the properties dialog:Web Service PolicyWhen using the Evaluate Response XPath assertion in a web service policy:
XML Application PolicyWhen using the Evaluate Response XPath assertion in an XML application policy:
- Select theXML message sourcefrom the drop-down list. The default is to use theDefault Responsemessage source, but you can also retrieve the message from an eligible context variable. An eligible context variable is one that meets either of the following conditions:
- Specify the XPath and select the target element to be evaluated from the code box. For detailed instructions on using the interface to build your XPath, see Selecting an XPath.
- Make sure that the variable prefix entered here is different from those used in other Evaluate Response XPath and Evaluate Request XPath assertions. See the description at the beginning of this topic for more information about variable prefixes.
- Click [OK].
- Optionally set theXML message source, if necessary.
- Enter an XPath expression corresponding to the target response element in the field.
- Optionally add namespaces to the namespace map.
- Click [OK].