Expression Builder

The Expression Builder is a development environment for working with the Expression Language. This component can be opened when editing Expression fields in the Properties Editor and the Expression and Condition columns of the Bindings table. It contains tools for efficiently testing and building expressions throughout Iotellect.

The Expression Builder has two main views: the Expression tab, which shows the expression as text, and the Structure tab, which displays the expression as an interactive graph.

The default view of the Expression Builder is pictured below.

• The Help Text Area at the top displays summary information about the specific expression field being edited, if such information is available. The example below is from a Web dashboard binding expression.

• The Entity Selector in the left pane allows referring Iotellect Server contexts, variables, functions, events, and even specific fields and rows from their data table formats. Hovering over an item in the tree reveals buttons to copy or directly insert the absolute reference to the entity.

• The Components area is a tab in the left pane and contains an Entity Selector for finding references to dashboard component properties. This section is available only when editing dashboard binding expressions.

• Expression Text Area is the middle pane and acts as a text editor, as well as displaying the default context where the expression will be evaluated and giving the option to change to a different context.

  • Clicking the menu button under the Default Context label gives the option to choose a different default context.

  • Evaluation Mode indicates whether the expression should be evaluated on the server () or in the browser (). Evaluation in the browser can be faster, but evaluation results may differ since server-side and browser-side expression features and functions are slightly different.

  • The Evaluate button processes the entire expression in the selected context. Evaluate a portion of the expression by selecting the desired text and pressing Ctrl+Enter or clicking Evaluate.

  • The Save button will save the current text to the expression field being edited.

• The Structure tab in the center pane displays the expression as a directed acyclic graph (DAG) where each node represents an element of the expression: an operator, function call, literal value, or reference. The Structure tab supports three display modes and allows navigating into nested expression evaluations. Details are described in the Structure Tab section below.

• Function Chooser in the right pane allows searching, selecting, and inserting functions, as well as indicating the parameters and their type.

• The Events pane in the bottom center displays a list of events that have been triggered while evaluating expressions.

• The Environment panel on the right displays the evaluation environment of the current expression. It contains the following collapsible sections:

  • Default Context — the default context used to resolve relative context paths that may appear in standard references.

  • Origin — the reference identifying the location of the expression in the system, such as the binding, rule, or field the expression belongs to.

  • Default Data Table — the default data table used to resolve standard references that do not explicitly point to a variable or function of a certain context.

  • Default Row — the default row used to determine what data table row should be accessed when resolving standard references that do not explicitly specify a row.

  • Environment Variables — any environment variables that may be retrieved by using environment references inside the expression.

  • Session Variables — the set of session variables available during evaluation, such as the current user login, headers, and cookies. Populated after the expression is evaluated.

  • Relative References — the relative context paths used in the expression, resolved from the default context.

  • Reference Editor — allows editing the currently selected reference in the expression text. Any part of a reference may be changed independently. When changes are made, the expression text is updated. The Resolve button allows available values to be retrieved.

The Structure tab displays the expression as a directed acyclic graph. Arrows indicate the direction of data flow — each node depends on the nodes it points to.

At the default zoom level, nodes show abbreviated labels. Zooming in reveals the full node type for each node: Operator, Function, Reference, Literal, or Expression. Hovering over a node reveals a popup with text coordinates that link to the corresponding fragment in the Expression tab.

The Structure tab has three display modes, selectable from the toolbar:

Static () — displays the abstract syntax tree (AST) of the expression or its selected part without evaluation results. This is the default view when the expression has not been evaluated. The following color codes are supported for different node types:

• Purple — Operator

• Orange — Reference

• Green — Function

• Pink — Literal

• Blue — Expression (root of a nested expression).

Debug () — displays the result of the most recent evaluation. Nodes are color-coded:

• Green — the node was evaluated and produced a result successfully.

• Red — the root cause of an error. Only the node where the error originated is marked red; the tooltip shows the error details.

• Gray — the node was not evaluated — for example, a node was skipped due to selective execution (as in a ternary conditional operator, logical AND/OR operations, or certain functions), or a node that could not be evaluated because of an error in a node it depends on.

The tooltips for nodes shows the text coordinates in the expression.

Performance () — displays the evaluation duration for each node. The displayed time is accumulative: it includes the execution time of the node itself plus the total time of all its dependent nodes. This is why time typically grows from leaf nodes toward the root. Nodes are color-coded by duration:

• Green — fast evaluation.

• Yellowish — duration over 10 ms.

• Yellow — duration over 100 ms.

• Orange — duration over 1000 ms.

Some functions treat certain string arguments as expressions. Such expressions are called nested. One nested expression may be evaluated multiple times, producing multiple nested evaluations. The root node of each nested expression is synthetic — it does not appear in the actual AST but is preserved in the graph to show the expression text. Such functions as aggregate() and evaluate() evaluate nested expressions.

Each such node can be expanded () to inspect the nested evaluation. The sub-node graph can be opened as a separate view independent of the parent ().

If a node was evaluated multiple times — for example, once for each row of a data table — a counter appears on the node showing the total number of iterations and the index of the iteration currently being viewed. The counter is visible at sufficient zoom levels.

Each record in the Event Log captures the evaluation environment at the time of execution, including the default context, default data table, default row, and variable values. The amount of information captured depends on the Expression Evaluation setting in Server Configuration — users can opt out of including environment and session variables. Right-clicking a record in the Events table and selecting Copy Environment from the context menu loads that environment into the Environment panel on the right. The expression can then be evaluated in that environment to reproduce and investigate the behavior from that specific execution.

The Expression Builder allows you to validate the syntax of any expression. In cases where data is available in the default context, it is also possible to calculate the result that the expression will produce. This can be done since Expression Builder knows about the evaluation environment of the current expression. However, the evaluation environment is not always complete, and in some cases, it is not possible to evaluate the expression correctly from the Expression Builder. Here are some examples:

• If editing an event filter expression, there is no specific event that provides data for the expression.

• Similarly, an alert event trigger expression cannot be evaluated within the expression builder because there is no alert data until the alert is triggered.

The Expression Builder includes a toggle to select whether the expressions evaluated in the editor will be evaluated on the server () or in the browser (). Note that this toggle only affects expression evaluation in the Expression Builder. Expressions in production (for example, in a binding, or validity expression) are mostly evaluated on the server, and only in a few cases production evaluation takes place in a browser.

• Browser Evaluation can be faster, but not all functions are evaluated in the same way as on the server. Therefore, browser evaluation is principally to check that a given expression has the correct syntax to be evaluated.

• Server Evaluation is the default evaluation mode, and ensures greater accuracy by evaluating all expression functions in the same way as they will be evaluated in production. While server evaluation can be slower, it must be used when evaluating the results of expression evaluation. This mode should not be used to debug expressions that will be later evaluated in a browser.

Was this page helpful?

Tell us more

Send

Thank you!