CA API Gateway 9.1

9.4 9.1

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.
gateway83
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.
Configuring the Evaluate Response XPath assertion requires familiarity with XPath patterns and specifications. This assertion must be placed
after
 the routing assertion in a policy.
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
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 Response XPath assertion returns XML in their 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
responseXpath.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
responseXpath.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.
responseXpath.results
Similar to
responseXpath.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.
responseXpath.element
Contains the resulting text of the query. Similar to the
responseXpath.result
 variable, except this includes the entire element (including start and end tags).
This variable contains values of type String.
responseXpath.elements
Similar to
responseXpath.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.element
s
 is required, as assertions that expect an 'Element' value will not work with a 'String' value.
responseXpath.count
Contains the number of nodes found, which will be >= 1 if the expression matched.
responseXpath.found
Either "true" or "false", depending on whether the XPath expression matches the response.
Example:
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
    .found
     suffix returns the String value “true”.
  • The
    .result
     suffix 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
    .results
     suffix creates a multi-valued context variable that includes one value corresponding to the
    .result
     suffix for each element that matched the XPath. In this example, because only one element was matched,
    .results
     has a single value matching the value of
    .result
    .
  • The
    .element
     suffix 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
    .elements
     suffix returns all matching Element values as a multi-valued context variable containing one or more values of type Element. Unlike "
    .result
     vs.
    .results
    ", the types differ between
    .element
     and
    .elements
    . The suffix
    .element
     is a single value of type String; the suffix
    .elements
     can 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
    .elements[0]
     construction.
The values stored in context variables can be used in a subsequent Evaluate Regular Expression Assertion or Compare Expression Assertion using the special
${assertionPrefix.variableName} 
syntax. If the Audit Messages in Policy Assertion is present during message processing, then you can use the 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
newPrefix
 in the Evaluate Response XPath assertion. Now instead of the default names shown in the table above, 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 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
  1. 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.
  2. Follow the appropriate section below to complete the properties dialog:
    Web Service Policy
    When using the Evaluate Response XPath assertion in a web service policy:
    1. Select the 
      XML message source
       from the drop-down list. The default is to use the 
      Default Response
       message 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:
    2. 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.
    3. 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.
    4. Click [
      OK
      ].
    XML Application Policy
    When using the Evaluate Response XPath assertion in an XML application policy:
    1. Optionally set the 
      XML message source
      , if necessary.
    2. Enter an XPath expression corresponding to the target response element in the field.
    3. Optionally add namespaces to the namespace map.
    4. Click [
      OK
      ].

Content feedback and comments