20 About Expressions

An expression is a string enclosed in curly braces ({ }) that can be evaluated to a single value at runtime. Expressions can reference configuration properties and dynamic runtime data.

For example, you might have a list of values for an employee JobId field that displays all job titles from the jobId field from the Jobs business object. To list only the job titles for a given department based on the DepartmentId of the current row, you could use a query parameter with the following expression:

DepartmentId={ this.BusinessObject.Fields['DepartmentId'].Value }

where:

• this represents the currently selected field;
• BusinessObject represents the business object to which this field belongs;
• Fields['DepartmentId'] is the field (DepartmentId) associated with the business object; and
• Value is the value of the field.

You can also use Parent in an expression to refer to an ancestor business object ("parent" or higher) in a business object hierarchy. For example, to refer to a field in the parent business object you might use something like this:

ProjectNumber={ this.BusinessObject.Parent.Fields['ProjectNumber'].Value }

Parent can appear multiple times in the expression depending on the level you want to refer to in your business object hierarchy. For example, ProjectNumber={ this.BusinessObject.Parent.Parent.Parent.Fields['ProjectNumber'].Value } returns the value of the ProjectNumber field that belongs to the current business object's great grandparent business object.

You can also use an expression in the list of values for a row finder variable like this:

CountryId={ this.Finder.Variables['CountryId'].Value }

where:

• Finder is the row finder to which this finder variable belongs, and
• Variables['CountryId'] is the finder variable (CountryId) whose value determines the available choices of the current finder variable.

The value of an operand or an intermediate result in an expression can be a Boolean value, string, or integer. However, the results of expressions may be converted to strings and concatenated if needed when resolving the entire property value.

For any given configuration property that supports expressions, you must escape any curly braces (\{ or \}) that you wish to use literally.

Note:

Some workbook configuration properties support expressions and others do not. Those properties that support expressions may support all reserved words or only a subset of them. Consult the documentation for each property to determine what is, and is not, supported.

Reserved Words

Refer to this table for some of the reserved words used in add-in expressions. Please note that this list is not exhaustive.

Reserved Word	Note
this	Represents the property owner depending on the configuration context. For example, when defining a field's configuration property, "this" represents the field. See specific configuration properties for details.
BusinessObject	Represents the business object to which the currently selected field belongs
Finder	Represents the row finder to which the currently selected variable belongs
Parent	Represents the parent business object of the currently selected field's business object in a business object hierarchy. Use additional instances in your expression to refer to higher level business objects, such as Parent.Parent for the grandparent business object and so on.
Value	Value of a parameter or a field
SelectWindow	Search-and-select window in a list of values
Workbook	Represents the integrated workbook

Literal Values

Literal values of these data types are supported in expressions:

• Boolean
• String
• Integer or floating-point number

Data Type	Description
Boolean	Supported values (case-sensitive, no quotes): TRUE True true FALSE False false Note: It's recommended that you use capital case only (TRUE and FALSE).
String	String literals inside expressions must be enclosed in single quotes ('). Single quotes inside string literals must be escaped ( \').
Integer or Floating-Point Number	Only the Western Arabic numerals (0-9) can be used. Other digits are not supported. These symbols are supported: Leading negative sign (-) Decimal separator (.) Exponent (E or e followed by an optional sign and exponential digits) Note: This is allowed only when a decimal separator is present; for example, when the value is a floating-point number. These symbols are not supported: Leading positive sign (+) Note: The plus sign when used as an operator is supported. Thousand separator such as a space, period, comma, or underscore No digit after the decimal separator

Note:

Boolean and number literal values must be in the form described here. For example, if you are in a country that uses a decimal comma (,), you must still use a decimal point or period in your expression.

Here are some examples of how numbers are supported in expressions:

Supported	Not Supported
0.123	0,123 .123
123 123.0	123.
-456	+456 (part of literal value instead of doing addition)
1234	1,234 1 234
1234.567	1,234.567
3.14E2	03.14E2
1.0e10	1e10

Note:

These rules only apply to literal values used in expressions. They do not apply to data formats used in an Excel cell. For example, you must write 135000 without thousand separator in this validation rule { this.Value > 135000 } but that validation rule can be used on an integer field that shows 150,000 or 150.000 in cell.

Operators

Operator precedence is high to low.

Operator	Note
[ ] .	Collection access, object member access
( )	Grouping to change precedence
- !	Unary minus, negation
* /	Math (multiplicative)
+ -	Math (additive), also + for string concatenation
< > <= >=	Relational
== !=	Equality
&&	Logical AND
||	Logical OR
? :	Ternary conditional

Examples

Here are some sample 'q'-type filter query parameters for use in list of values configurations:

Parameter Value	Use	Sample Value	Final Parameter Value
DepartmentId={ this.BusinessObject.Fields['DepartmentId'].Value }	This string sets the value of DepartmentId in the query to the current row item's department Id value.	Department Id is 101	DepartmentId=101
DepartmentId={ this.BusinessObject.Parent.Parent.Fields['DepartmentId'].Value }	This string sets the value of DepartmentId in the query to the department Id value in the current row item's "grandparent" layout.	Department Id is 101	DepartmentId=101
FirstName LIKE '{ SelectWindow.SearchTerm }*'	This string matches employees whose first name begins with the user-provided search term entered in the Search-and-Select window.	Search term is Steve	FirstName LIKE 'Steve*'
CountryId={ this.Finder.Variables['CountryId'].Value }	This string sets the value of CountryId in the query to the value of the current row finder's CountryId variable.	Country Id is USA	CountryId=USA
DepartmentId={ this.BusinessObject.Fields['DepartmentId'].Value } { SelectWindow.SearchTerm == '' ? '' : 'AND FirstName LIKE \'' + SelectWindow.SearchTerm + '*\'' }	This string includes two expressions. The second expression uses the ternary operator. It returns results based on whether there is a search term in the search box. If there is no search term, the parameter returns values matching the current row item's department Id value. If there is a search term, the parameter returns results that match the department Id and the search term. The quotes are all single quotation marks. Note also the enclosed empty strings and escaped single quotes.	Department id is 101 and there is no search term	DepartmentId=101
		Department id is 101 and the search term is Steve	DepartmentId=101 AND FirstName LIKE 'Steve*'