Using the Expression Builder

The Expression Builder is a valuable tool used to assist in the creation and examination of expressions. In programming, an expression is a combination of variables, constants, functions, and operators that represents a particular value. Many procedures or actions that one might want to perform with expressions are already contained in AWE's list of available actions. However, expressions can be used to further expand the capabilities of an action or add more intelligence to a task due to its ability to resolve dynamic data during task execution. The Expression Builder essentially incorporates all of the elements needed in order to create a properly formatted expression for use in any step of an AWE task.

The Expression Builder provides a hierarchical view of all supported functions, constants, datasets, variables, and arrays. It also provides a list of system objects, such as AMError, which can be used to determine a variety of key elements that occur during runtime. For instance, when a task is triggered, it automatically creates an AMTrigger object which can be used to determine the name of the event or condition that initially triggered the task, the date and time of when the trigger occurred and which machine it occurred on. If an error occurs, an AMError object can be used to determine detailed information about the error that occurred, such as corresponding error code. Additionally, if a task generates an error, the Error object can be used to acquire a description of the error that occurred, which step it occurred on and which task generated the error.

The Expression Builder also allows for the creation of arrays and variables directly from its UI (User Interface). Double-clicking the Add Variable or Add Array option located in the bottom part of the Expression Builder's left window pane will open the Create Variable or Create Array properties dialog. These are identical dialog boxes that normally appear when selecting the Create Variable or Create Array action In the Available Actions pane.

Accessing Expression Builder

The Expression Builder interface can be accessed In the Task Builder by clicking the percent sign which is available while editing the steps of a task. In the Properties dialog box of any action, clicking inside any text box that accepts an expression will allow the percent sign to appear to the right of the box. Click the icon (or the F2 key) while in an action’s properties to open the Expression Builder interface. An expression may then be visually constructed and inserted into the step parameter.

The Expression Builder can also be accessed from the Task Builder ribbon by pressing the Application Button and navigating to Tools > Expression Builder.

Sections of the Expression Builder

The Expression Builder is arranged in four primary sections as illustrated above. Each section plays an important role in the creation of an expression. Each section is described in further detail below:

  1. Folders Pane: The lower left window pane includes folders containing all available functions, extended function, variables, datasets, constants, etc. This section also includes the ‘Create Variable’ and ‘Create Array’ options, which allows for the creation of variables and arrays directly from the Expression Builder interface.
  2. Contents Pane: The lower right window pane displays the contents of a folder selected from the lower left Folders pane. Help for each function can be found by selecting the desired function from this window pane and pressing the F1 key, or by right-clicking and selecting Help from the popup menu that appears.

  3. Expression Pane: When double-clicking an item from the Contents pane, the expression is displayed in the upper Expression pane. Help can also be found for a function from this pane by placing the insertion cursor inside a function name and pressing F1.

  4. List of Operators: Operators which can be added to the expression are shown just below the Expression pane.

Help for each function can be found by selecting the desired function from the right-hand side of the window and pressing the F1 key, or by right-clicking and selecting Help. Help can also be found for a function by placing the insertion cursor inside a function name in the upper expression pane and pressing F1.

Viewing Expressions

The Expression Builder can be used to view specific objects that are created as a result of specific events. The Variables folder located in the Folders pane of the Expression Builder becomes populated if a Create Variable action is used to create the specified variable(s) in an earlier step. Additionally, the datasets folder becomes populated when the specified datasets are initially created by running the step that creates and populates a dataset names and its contents, however, the dataset name itself is available in the Expression Builder if a step that creates the dataset appears in the task.

For example, imagine creating a task that includes a 'POP3 Email' action as the first step to retrieve email messages from a POP3 mail box. The General tab of this action contains a parameter labeled Create and populate dataset with which specifies the name of the dataset that should be created and populated with the mail message data upon execution as shown in Figure 1-2.

During task construction, one may want to view the variables or datasets created by the Get Email action. In order to display the created datasets from the Expression Builder interface in a subsequent step, the Get Email action must initially be executed in order properly create those datasets. This can be accomplished by highlighting the Get Email step (or any step which creates and populates a dataset) In the Task Builder Steps pane and clicking Run or hitting CTRL+F5. This will run only the highlighted step.

Building Expressions

To build an expression via the Expression Builder:

  1. Open Expression Builder from an action dialog box by clicking the percent icon .

  2. Add elements to your expression as follows:

  3. When satisfied with the expression, click Insert to insert it into the specified action’s properties. When the expression is added to the action parameter, the percentage signs (%) will automatically be added to the beginning and end of the expression.