Expression Builder

The Expression Builder provides the ability to create expressions that are used to calculate some type of value, using functions, variables, and other values. The expression builder determines which rule actions will be executed, in what order, and under what conditions when the rule is executed.

The Expression Builder can be launched from the Processing Options window when creating a source data identifier or by clicking the Build button in the Rule Logic section of the Rules tab.

Expression Builder Editing Features

The expression is created in a free-form edit box in which you can enter content that defines the expression statement. The content created must be a valid expression statement that evaluates to a proper value. The Expression Builder includes the following features:

Colors are used to indicate various parts of an expression, such as variables, functions, operators, keywords, functions, etc.
Line numbers are shown down the left edge of the edit box.
Undo (Ctrl+Z) and Redo (Ctrl+Y) are available from the keyboard and via right-click menu. Key bindings can be customized in Windows > Preferences > General > Keys.
Find/Replace (Ctrl+F) is available. Key bindings can be customized in Windows > Preferences > General > Keys, with options for dialogs (affecting the Expression Builder) and windows (affecting the Rule Logic preview).
Visual matching of brackets makes it easier to identify corresponding opening and closing brackets:
- Click on a bracket such as {, [, (, }, ], or ) to select it, then hover over it to display a tooltip showing the lines between that bracket and its corresponding opening or closing bracket. The tooltip code excerpt may be truncated, depending on its length.
- Double-click on a bracket to select the lines contained between that bracket and its corresponding opening or closing bracket. Hover over either bracket to display a tooltip showing the lines between that pair of opening and closing brackets.
Real-time grammar and validation checking identifies errors in the edit box. Grammar is checked first, looking for conditions such as certain tokens not being interpreted correctly by the parser/compiler. Validation is checked next, looking for correct types for function arguments and values, etc. Errors are indicated by a squiggly line under the first token in the expression containing the error. Hover over the error indicator to display a tooltip with a brief description of the error.
Enhanced drag-and-drop from the left part of the window into the edit box automatically creates temporary placeholders for conditions, function arguments, etc. Drag and drop a new item onto a placeholder to automatically replace it with the desired value.
You can add comments to your expression if desired. To add a comment that uses just one line of text, begin the line with two slashes. For example:

// This line is a comment.

If your comment will span more than one line, it should start with a /* and end with */. For example:

/* This comment covers more than
one line */

Expression Builder Tabs

In the Expression Builder, there are three tabs at the bottom left portion of the window: Logic, Functions, and Resources.

Important

You can drag objects into the Expression box. In addition, you can place the cursor in the desired position and right-click and select Insert. From the list you can select logic statements and any of the functions or resource objects. They will be placed at the cursor position.

Logic Tab

The Logic tab contains the statements you can use in your expression including:

if
else if
else
return
while

The Expression Builder can include logic such as the following where each statement could be a rule action.

IF <condition>
<statement>
ELSE
<statement>
<statement>
END IF

Functions Tab

The Functions tab contains these types of functions:

String Functions
Date Functions
Data Privacy Functions
Normalization Functions
Important
The Normalization Functions category only appears when you access the Expression Builder during data element creation and you choose a processing type of CUSTOM. Click Edit for Custom Adapter inbound or outbound expression and the Normalization Functions appear in the Functions list. Normalization Functions are not available when you access the Expression Builder during rule creation using Rule Logic.
Custom Functions
Important
The Custom Function category only appears in the list if you have already created custom functions.

In addition this is where the available operators and selection criteria operators are made available.

Resources Tab

The Resources tab provides a list of the data elements, data items, rule actions, variables, and files that you have created for this project, making them available for use in your expression.

To use any of these statements, functions, operators, data elements, variables, or rule actions, you can drag them to the desired position in the Expression box. After they have been placed in the expression box, they can still be modified.

For data elements, you can drag the following methods:

getFieldLength – returns the field length of the field identified by this data element.
getFieldName – returns the field name of the field identified by this data element.
getFieldType – returns the field type of the field identified by this data element.
getFullyQualifiedFieldName – returns the fully qualified field name of the field identified by this data element.
getOriginalValue – provides the original source value of the data element.
getScale – returns either the scale of the field identified by this data element, or 0 if not applicable.
getValue – provides the current source value of the data element.
setValue – sets the current source value of the data element to whatever value is provided. The replacement value can be another data element, a variable, a constant, or an expression.

For string list and number list variables, you can drag the following functions:

add – appends an element to the list.
addAll – appends a list passed as parameter to the list.
clear – removes all elements from the list.
contains – returns "true" if the list contains the element passed as parameter, and returns "false" otherwise.
getAt – returns an element at the specified position. (The position is 1-based.)
getValue – returns the list object.
insertAt – inserts an element at the specified condition.
isEmpty – returns "true" if the list contains no elements, and returns "false" otherwise.
removeAt – removes an element at the specified condition.
setAt – sets value at the specified position.
setValue – replaces list value with the new list.
size – returns element count.

For Rule Actions, only one function is available:

execute – executes the Rule Action.

The Data Item section of the Resources tab lists only the data items that are referenced by the composite definitions used by composite rule actions within the current rule. For each of these data items, the following functions are supported and can be dragged to the editor:

getPatterns – returns the STRING_LIST object that contains the current regular expression patterns used by the data item.
setPatterns – replaces the list of regular expression patterns used by the data item.
getValues – returns the STRING_LIST object that contains the current values used by the data item.
setValues – replaces the list of values used by the data item.

More details about using these four methods are provided in the topic Dynamic-Data-Items.

The File section of the Resources tab allows you to write the Data Privacy log to a DD name on z/OS. The DD name must be defined in JCL as in the following example:

//DPRLOG DD DSN=U.DPR.OUT,
// DISP=SHR

Currently only one file, DPRLOG, is listed in the File section.

There are two methods provided for files:

write – writes a string passed as a parameter to the file.
writeln – writes a string passed as a parameter, followed by the new line character, to the file.

Any errors when writing to a log file will be logged as informational messages in the Java execution log, but such errors will not halt execution. This functionality is currently supported only on z/OS. Execution on other platforms will ignore "write" and "writeln" statements present in the rule logic.

Special Characters

To use special characters within strings, these characters should be escaped using the standard Java escaping algorithm. The following list describes the special characters that have to be escaped:

\t Insert a tab in the text at this point.
\b Insert a backspace in the text at this point.
\n Insert a newline in the text at this point.
\r Insert a carriage return in the text at this point.
\f Insert a formfeed in the text at this point.
\' Insert a single quote character in the text at this point.
\" Insert a double quote character in the text at this point.
\ \ Insert a backslash character in the text at this point.

Tip

It also supports the standard Java formatting for Unicode characters, such as \u2126 for Ω.

Condition Statements

A Condition statement is a logic component that evaluates to a true or false outcome that is needed in scenarios that require a decision to be made before an action can be performed. A condition statement consists of a left operand, a comparison operator, and a right operand. The left and right operands are a value of some type, and the comparison operator is used to compare the two operands to produce a logical result. The left and right operands can be a simple field name from a table, a constant value, a data element, or a complex expression statement using functions and project variables.

A condition statement can also use the logical operators AND, OR, and NOT. Brackets are used to group logical conditions when it is necessary to combine more than one condition using the logical operators.

String and number evaluation of the condition statement is based on the items that are used. If the statement consists of table fields or variables that are numbers, then a number comparison is performed in the condition. If string variables or fields are used in the condition statement, the comparison is character based. When entering values in the expressions, a string value must be enclosed in double-quotes or the values are interpreted as numbers.

At execution time, the condition statement is evaluated as true or false. If the result of the condition statement is true, the action is executed. If the result of the condition statement is false, the action is not executed.

After you complete your expression, click Validate Expression to ensure that you have created a valid expression, then click OK to return to the project.