Evaluate Request XPath Assertion
The Evaluate Request XPath assertion is used to configure a specific XPath query pattern for incoming XML request 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 Request XPathassertion is used to configure a specific XPath query pattern for incoming XML request 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.
The Evaluate Request 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 request, setting six context variables according to the processing result of the query. The following table describes the default context variables set by the Evaluate Request XPath assertion.
When the Evaluate Request XPath assertion is used in a policy fragment and you 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 Request 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:
requestXpath.resultvariable will be set as follows:
requestXpath.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
requestXpath.resultvariable, except this includes the entire element (including start and end tags).
This variable contains values of type String.
requestXpath.elementvariable carries the namespace of the targeted element. By comparison, the
requestXpath.elementvariable does not.
requestXpath.elementexcept that it contains all values matched rather than just the first one.
This variable contains values of type Element.
You cannot use
requestXpath.elementsis 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 request.
The values stored in the context variables can be used in subsequent Gateway Audit Events window.
If the variables from several Evaluate Request XPath assertions need to be available simultaneously (for example, an upcoming Compare Expression Assertion will be used to compare the results), then each assertion must use a different prefix. For example, you define the new variable prefix
newPrefixin the Evaluate Request XPath assertion. Now instead of the default names shown in the above table, 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 Request XPath and Evaluate Response 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 Request 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 Adding 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 Request XPath assertion in a web service policy:
XML Application PolicyWhen using the Evaluate Request XPath assertion in an XML application policy:
- 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.
- Select the appropriate XPATH version from the drop down.
- For an explanation of the validation messages displayed, see "Context Variable Validation" in Context Variables.
- Make sure that the variable prefix entered here is different from those used in other Evaluate Request XPath and Evaluate Response XPath assertions. See the description at the beginning of this topic for more information about variable prefixes.
- Click [OK].
- Enter an XPath expression corresponding to the target request element in the field.
- Optionally add namespaces to the namespace map.
- Click [OK].