Expression Navigator

The Expression Navigator is a visual tool for building ESQL expressions by selecting fields from message trees. It simplifies the creation of data location expressions in message flow node properties.

Overview

The Expression Navigator provides a visual interface for building ESQL expressions. When you edit certain node properties that require data location expressions, the Expression Navigator opens automatically, displaying a tree view of available message structures. You can navigate the tree and double-click fields to generate ESQL expressions automatically. The Expression Navigator window showing the context tree, filter field, expression field, and collapsed Advanced Options section.

The Expression Navigator is the default expression builder for read-only fields in node properties. It generates ESQL-style expressions using dot notation, such as Root.BLOB.data or CONTEXTREFERENCE('NodeName').Payload.Data.field.

Key features

The Expression Navigator provides the following features:

Visual tree navigation: Navigate through the context tree, Root tree, and LocalEnvironment tree using an expandable tree view. The context tree is displayed by default and shows nodes that are connected to the current node in your message flow.
Double-click selection: Select fields by double-clicking them in the tree. The Expression Navigator automatically generates the correct ESQL expression and inserts it into the expression field.
Field filtering: Use the filter field to quickly find fields by name. Type text in the filter field and the tree updates to show only fields that contain the filter text.
Intelligent payload display: The payload section for each node displays fields based on the node's domain setting. If a node has a specific domain configured (such as JSON or XMLNSC), only that domain's fields are shown. If no domain is configured, all possible domains are displayed.
Optional tree display: By default, the Expression Navigator shows the context tree. You can optionally display the Root tree and LocalEnvironment tree by expanding the Advanced Options section and selecting the appropriate checkboxes.
Namespace configuration: For XSD schemas that use namespaces, you can view and manage namespace prefix-to-URI mappings in the Advanced Options section.
Smart defaults: The Expression Navigator automatically displays relevant trees based on your existing expression. For example, if your expression starts with Root, the Root tree is automatically displayed.

When to use the Expression Navigator

The Expression Navigator opens automatically when you edit read-only fields in node properties that require data location expressions. Common scenarios include:

Configuring the Directory property in a FileOutput node
Setting data location references in a Compute node
Defining filter expressions in a Filter node
Specifying data locations in a Database node

You can also use the Expression Navigator whenever you need to build an ESQL expression that references fields from the context tree, Root tree, or LocalEnvironment tree.

Expression format

The Expression Navigator generates ESQL expressions using dot notation. This differs from XPath expressions, which use slash notation and dollar sign prefixes.

Examples of ESQL expressions generated by the Expression Navigator:

Context tree reference: Context.Nodes."FileInput1".Payload.Data.customer.firstName
Root tree reference: Root.XMLNSC.Data.customer.firstName
LocalEnvironment reference: LocalEnvironment.File.Directory
Array element reference: Root.JSON.Data.customers[0].firstName

In contrast, XPath expressions use the following format:

$Root/BLOB/data/customer/firstName
$LocalEnvironment/File/Directory

Note: Most users will use the visual selection method (double-clicking fields) rather than manually typing expressions. The Expression Navigator automatically generates the correct syntax when you double-click a field.

Relationship to context trees

The Expression Navigator provides visual access to context tree functionality. The context tree is part of the set of logical trees (message assembly) in which information about the message flow is captured, including information about how the flow was invoked and the messages from each node in the flow.

The context tree displayed in the Expression Navigator shows only nodes from the current flow or subflow. It does not show nodes from parent flows or nested subflows. This scoping ensures that you see only the nodes that are relevant to the current context.

For more information about context trees, see Context tree.

Relationship to XPath Expression Builder

The Expression Navigator complements the XPath Expression Builder. Both tools help you build expressions for node properties, but they generate different expression formats:

Expression Navigator: Generates ESQL expressions using dot notation (for example, Root.BLOB.data). This is the default expression builder for read-only fields.
XPath Expression Builder: Generates XPath expressions using slash notation and dollar sign prefixes (for example, $Root/BLOB/data). This tool is available by clicking Open XPath Expression Builder at the bottom of the Expression Navigator window.

You can switch between the two expression builders as needed. However, when you switch from the Expression Navigator to the XPath Expression Builder, the Expression Navigator state is not preserved.

Main components

The Expression Navigator window contains the following main components:

Tree view

Displays the context tree by default, showing nodes that are connected to the current node in your message flow. You can expand nodes to view their payload, headers, and metadata. The tree view also displays the Root tree and LocalEnvironment tree when you enable them in the Advanced Options section.

Filter field

Allows you to filter the tree by field name. Type text in the filter field and the tree updates to show only fields that contain the filter text. The filter searches by field name only, not by full path.

Expression field

Displays the generated ESQL expression. When you double-click a field in the tree, the expression field updates automatically. You can also edit the expression field directly if needed.

Advanced Options section

Contains advanced options, including checkboxes to show the Root tree and LocalEnvironment tree, and a namespace configuration section for managing XSD namespace prefixes. The Advanced Options section is collapsed by default.

Buttons

The Expression Navigator provides the following buttons:

Open XPath Expression Builder: Switches to the XPath Expression Builder
OK: Inserts the expression and closes the window
Cancel: Closes the window without inserting the expression

Smart defaults

The Expression Navigator uses smart defaults to display relevant trees based on your existing expression:

If your expression starts with Root (without a dollar sign), the Show Root tree checkbox is automatically selected and the Root tree is displayed.
If your expression starts with LocalEnvironment (without a dollar sign), the Show LocalEnvironment tree checkbox is automatically selected and the LocalEnvironment tree is displayed.
If your expression is empty or contains an unrecognized format, the context tree is displayed by default.
If your expression uses XPath format (with a dollar sign and slashes), the context tree is displayed by default. The Expression Navigator does not attempt to parse or locate XPath expressions in the tree.

These smart defaults help you quickly navigate to the relevant part of the message tree structure when editing existing expressions.

Validation

The Expression Navigator does not perform real-time validation of expressions. You can type any text in the expression field, and the Expression Navigator will accept it. Validation occurs at deployment time or runtime, not in the Expression Navigator itself.

This approach allows you to create complex expressions that may include operators, functions, or other ESQL constructs that are difficult to validate in a visual editor. However, it also means that you may enter invalid expressions that will cause errors later.

To minimize the risk of errors, use the double-click selection method to build expressions rather than typing them manually. When you double-click a field in the tree, the Expression Navigator generates syntactically correct ESQL expressions.