The Automate Expression Builder is a valuable tool used to assist in the creation and examination of expressions. An expression, in a programming, 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 Automate'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 Automate 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 Error, Trigger and Condition objects, 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 started the task, the date and time of when the trigger occurred and which machine it occurred on. When a condition is activated in the middle of a workflow (as opposed to a condition in the beginning of a workflow used to trigger a task) an AMCondition object can be used to determine key runtime elements in the same fashion as an AMTrigger object. 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 from the Task Builder's Available Actions pane.
Sections of the Expression Builder
The Expression Builder is arranged in four primary sections as shown in Figure 1-1; the Folders Pane, Contents Pane, Expression Pane and List of Operators. Each section plays an important role in the creation of an Automate expression. These sections are further detailed below:
1. Folders Pane: The Expression Builder's lower left window pane includes a variety of folders containing functions, extended function, variables, datasets, constants and system objects. This section also includes the 'Create Variable' and 'Create Array' options, which allows for the creation of variables or arrays directly from the Expression Builder interface.
2. Contents Pane: The lower right pane displays the contents of a folder selected from the lower left pane. For example, clicking the Functions folder from the lower left pane populates the lower right pane with all of the functions contained in the Functions folder.
NOTE: Help for each function can be found by selecting the desired function from the right-hand side of the Expression and pressing the F1 key, or right-clicking and selecting Help for the popup menu.
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.
Figure 1-1: Expression Builder Sections
NOTE: The variables folder 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.
Figure 1-2: Example of 'POP3 Email' action's Create and populate dataset parameter
During task construction, one may wish to view the datasets created by the 'POP3 Email' action. In order to display the created datasets from the Expression Builder interface in a subsequent step, the 'POP3 Email' action must initially be executed in order properly create those datasets. This can be accomplished by simply highlighting the 'POP3 Email' step (or any step which creates and populates a dataset) from the Task Builder interface and clicking the Run Selected button or selecting CTRL+F5 (as shown in Figure 1-3). This will run only the highlighted step.
Figure 1-3: Task Builder - Run Selected
After doing so, the datasets folder will then be populated with the proper datasets as shown in Figure 1-4.
Figure 1-4: Example of Expression Builder populated with the proper datasets
How to Access the Expression Builder
The Expression Builder interface can be accessed from the Task Builder by clicking the Insert Expression/Variable popup button 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 Insert Expression/Variable button to appear to the right of the box. Pressing this button (or the F2 key) while in an action's properties causes the Expression Builder interface to be displayed. An expression may then be visually constructed, tested and inserted into the step parameter.
The Insert Expression/Variable button does not appear unless an appropriate text box that allows expressions to be inserted is initially clicked. For example, the 'Open Web page' action contains a text box parameter in its General tab properties labeled Web page to open which allows for expressions to be inserted into. Figure 1-5 illustrates how the General tab of this action appears without an Insert Expression/Variable button (before clicking the Web page to open parameter) and how it appears with an Insert Expression/Variable button (after clicking inside the Webpage to open parameter).
Figure 1-5: How to Display the Insert Expression/Variable Button
The Expression Builder can also be accessed from the Task Builder's Tools menu by selecting Tools -> Expression Builder.
How to Build an Expression from the Expression Builder
Instructions are provided below in regards to building expressions from the Expression Builder.
1. Open the Expression Builder from an action dialog box by clicking the Insert Expression/Variable button or from the Task Builder's Tools menu by selecting Tools -> Expression Builder.
2. Add elements to the expression as follows:
• Click a folder in the bottom left Folders pane to reveal its contents in the bottom right Contents pane.
• Create variables or arrays from the left pane by selecting the 'Add Variable' or 'Add Array' options.
• If adding a function, highlight the function from the Contents pane and press the F1 key or right-click and select Help to obtain more help regarding that function.
• Double-click an element populated in the right Contents pane or right-click an element and select Add from the popup menu that appears to add it to the upper Expression pane.
• Once an element is added to the Expression pane, select and replace characters in the expression as needed.
• Click from the list of Operators below the Expression pane to add them to the expression.
3. After creating the expression, click the Test button to test it. For example, the Len function returns the number of characters in a string value. If the Expression window is populated with Len("Hello"), clicking the Test button will show the expression result as 5 (as shown in Figure 1-6). Failed test results will show a dialog similar to the one illustrated in Figure 1-7.
Figure 1-6: Example of Expression Result
Figure 1-7: Example of Failed Test Result
4. When satisfied with the expression, click the Insert button to insert it into the specified action's properties. When the expression is added, the percentage signs (%) will automatically be added to the beginning and end of the expression.
Conclusion
The Expression Builder provides lists of all supported functions, plus any defined constants and any variables or datasets contained in the associated task. Any of these elements can be selected to create complex expressions for insertion into task steps. The Expression Builder also allows users to easily view expressions created in subsequent steps of their task. Therefore, the Expression Builder is an essential Automate feature that can be used to create and view expressions, allowing task creation to be even less complicated than it already is.
Applies to: Automate 10
