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.
gateway90
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.
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 
Variable
Description
 
requestXpath.result
 
The content of this variable depends on the match found:
  • If the XPath expression matches an element, this variable contains the contents of the first element that matched the XPath expression.
  • If the XPath expression locates any other match, this variable contains the first match.
  • If the XPath expression does not locate a match, the assertion fails and this variable is not set.
 
Example:
 
Consider the following sample XML document:
<test>
<data>hello</data>
<data>world</data>
</test>
The 
requestXpath.result
 variable will be set as follows:
  • The XPath expression "/test/data" matches both elements "<data>hello</data>" and "<data>world</data>". In this case, the variable will contain "hello", which is the contents of the first element that was found.
  • The XPath expression "/test/data[2]/text()" does not match any element but does match "world". In this case, the variable will contain "world", which is the first match found.
 
requestXpath.results
 
Similar to 
requestXpath.result
 except 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.
 
requestXpath.element
 
Contains the resulting text of the query. Similar to the 
requestXpath.result
 variable, except this includes the entire element (including start and end tags).
This variable contains values of type String.
 The 
requestXpath.element
 variable carries the namespace of the targeted element. By comparison, the 
requestXpath.element
 
s
 
 
  variable does not.
 
requestXpath.elements
 
Similar to 
requestXpath.element
 except that it contains all values matched rather than just the first one.
This variable contains values of type Element.
 You cannot use 
requestXpath.element
 where 
requestXpath.elements
 is required, as assertions that expect an 'Element' value will not work with a "String" value. 
 
requestXpath.count
 
Contains the number of nodes found, which will be >= 1 if the expression matched.
 
requestXpath.found
 
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 Evaluate Regular Expression or Compare Expression assertions using the special 
${assertionPrefix.variableName}
syntax. If the Audit Messages in Policy assertion is encountered during message processing, then the XPath query results can be viewed in the 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 
newPrefix
 in the Evaluate Request XPath assertion. Now instead of the default names shown in the above table, this assertion will create variables named 
newPrefix.result,
 
newPrefix.count,
 
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
  1. 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.
  2. Follow the appropriate section below to complete the properties dialog.
     
    Web Service Policy
    When using the Evaluate Request XPath assertion in a web service policy:
    1. 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.
    2. Select the appropriate XPATH version from the drop down.
    3. For an explanation of the validation messages displayed, see "Context Variable Validation" in Context Variables.
    4. 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.
    5. Click [
      OK
      ].
     
    XML Application Policy
     
    When using the Evaluate Request XPath assertion in an XML application policy:
    1. Enter an XPath expression corresponding to the target request element in the field.
    2. Optionally add namespaces to the namespace map.
    3. Click [
      OK
      ].