XPath Expression Builder

You can launch the XPath Expression Builder from most property fields that support, or expect, XPath expressions as a value that can be entered into the field.

The use of the XPath Expression Builder is optional, in that it is an aid to you in developing message flow applications. The XPath Expression Builder helps you to construct message processing expressions in either XPath or ESQL. You are free to enter expressions by hand, or use the XPath Expression Builder to help construct such expressions.

The XPath Expression Builder does not support use of the $Body variable. You can use the $Body variable when you enter an expression by hand, but the XPath Expression Builder and associated validation in the IBM® Integration Toolkit do not support it. Use the $Root variable instead.

You can populate the fields, regardless of the state of the node; that is, whether the node is detached or connected, or fully, partially, or completely unconfigured.

You launch the XPath Expression Builder from a button in the following locations:
  • Table cells, located to the right of the text entry field within the cell.
  • Add or Edit dialog boxes used to construct rows in tables, located to right of the property field concerned.
  • Tabs in the property viewer for a node, to the right of a property field.

Variables (or in ESQL terminology, correlation names) provide a list of all message tree start points that are applicable to the property field from which the dialog was launched.

If a field is a read-only or a read-write path field, expressions must start with such a variable to indicate which tree in which message assembly the path expression is mapping to.

XPath variable names map to existing correlation names found in ESQL field reference expressions, but to conform to the ESQL grammar they are designated as variable references by prefixing them with the dollar ($) character.

For example:
ESQL
Root.XMLNSC.CUST_DETAILS.NAME
XPATH
$Root/XMLNSC/CUST_DETAILS/NAME
The variable indicates to which tree and where in that tree the expression is anchored.

The XPath Expression Builder dialog box supports validation, which you can turn off on the XPath preferences page by clearing the Validate when creating XPath expressions check box.

If you select the $Root or $Body variables and create an expression that refers to the body of the message, the XPath expression contains the message element. This expression is correct for message bodies owned by the XMLNSC, XMLNS, XML, and DataObject domains.

For message bodies that are owned by the SOAP, MIME, MRM, and IDOC domains, you must remove the message element from the expression.

For example, the XPath expression $Body/my_message/my_field is correct for XMLNSC, but must be changed to $Body/my_field to be correct for MRM.

Views

There are three main views when functions are supported.

Whether a view is displayed, and what is displayed in it, depends on what type of property editor you have used to launch the dialog, and its tailored settings; for example, for path type fields you do not see a functions pane. The operators that are supported can change as can the list of applicable variables.
Data Types Viewer
This view shows the different schema types, elements, and attributes that you can use within the XPath expression that you are creating, as well as the allowable variable references.
XPath Function
This view shows four main top level categories, which are:
String
This category corresponds to the description in the XPath 1.0 specification of section-String-Functions.
Boolean
This category corresponds to the description in the XPath 1.0 specification of section-Boolean-Functions.
Numeric
This category corresponds to the description in the XPath 1.0 specification of section-Number-Functions.
Nodeset
This category corresponds to the description in the XPath 1.0 specification of section-Node-Set-Functions.
For information on the format of XPath 1.0 expressions see the W3C XPath 1.0 Specification.
Operators
This view shows a list of all of the available operators that you can use within the given XPath expression.

Namespace settings

If you expand Namespace settings in the XPath Expression Builder dialog you see a table of Prefix and Namespace pair strings. This table is automatically updated when XPath expressions are created. If the default prefix generated is not what you want, you can change it by clicking Change Prefix.

To add a prefix and namespace map entry click Add and complete the fields in the dialog.

To edit or delete an entry in the table, select the item and click Edit or Delete respectively.

Edit opens another field dialog allowing you to change the prefix and namespace.

For information about the preferences supplied with the XPath editor, see XPath editor preferences.