This section describes expressions in Desktop Automation and how they are edited and evaluated.

Many properties on Desktop Automation steps can either be specified as plain value (for instance, a number), or as an expression. An expression is evaluated and then the result of this evaluation is used for the property where plain values are used directly as the value of the property. For instance, the Count property on the Click step could be specified as a number, such as 2, but could also be specified as an expression, such as clickCount where clickCount is a variable defined in the scope of the step and given a value somewhere else in the Desktop Automation Workflow.

Expressions in Desktop Automation are very similar to expressions in most common programming languages, such as Java, C#, JavaScript, etc. They consist of constants, variables, operations (addition, subtraction, multiplication, comparison operations, logic operation, and etc.), and functions. The following are a few examples of expressions:

• (1 + 2)*3

• x > 0 || x <= 6

• max(x, 10)

• "hello".substring(3)

Expressions are typed and these types are the same as variables have. This means that operation and function may only be applied to operands of a certain type. Depending on the operand type, it returns a value of a given type when evaluated. For example, addition of two operands of type Integer provides a result of type Integer, such as 1+2 evaluates to 3. If the type of the operands is Number, then the result is of type Number, such as 1.0+2.0 evaluates to 3.0. The type of an expression is statically checked before the expression is evaluated and a type error in an expression is reported as an error in the Desktop Automation Workflow.

Evaluation of an expression cannot change the state of the workflow, that is you cannot assign a value to a variable inside the expression. Only steps can do this, for instance the Assign step assigns a value to a variable and this value may come from evaluating an expression.

The following sections explain different components of expressions.

Constants

Constants are values of the following simple types.

Type	Example
Integer	42 -17
Number	3.14159 -.33
Boolean	true false
Text	"Hello" "First"

Text values must not contain double quotes (") since this terminates the Text value. Instead use \" when you need a double quote in your Text value. The backslash sign (\) is generally used for special characters in Text values that you cannot write directly in expressions. The special characters are:

Character	Description
\n	line break Note To use line break in the built-in browser in Desktop Automation, use \r\n
\r	carriage return
\f	form feed
\"	double quote
\t	tab
\b	backspace
\\	the backslash character itself
\uXXXX	Unicode character coded in a hexadecimal number, for example "\u002A" is an alternative way of writing "*"

Variables

Variables in an expression can be any variables or input parameters defined in a workflow that are in scope at the location of the expression. Input parameters are always in scope, because their scope is the entire workflow. Variables are in scope if they are defined at the top level of the workflow or inside a Group step.

Operations

An operation is an expression consisting of an operator and some operands. In the expression 1+2, + is the operator and 1 and 2 are the operands. So the operator defines an operation that should be performed on the value of the operands when the expression is evaluated. In this section we describe the operators that can occur in expressions. In most cases the operation that these operators perform is straightforward. If you are familiar with expressions in programming languages, you can skip this description and consult the summary table below.

Arithmetic operations

Expressions support normal arithmetic operations, such as addition (+), subtraction (-), multiplication (*), division (/), and modulo (%). Each of the operations take two operands that can have any combination of type Integer and Number. If at least one of the operands is of type Number, the result type is also Number. Otherwise it is of type Integer.

When using an addition operation (+), if one of the operands is Text and the other operand is of type Integer, Number, Boolean or Text, the result type is Text. For example, "a" + 1 evaluates to the text "a1". The value of the operand that is not of Text type is converted into text and then the values of the two operands are concatenated into the resulting text. The subtraction operation - can also be used as negation of numbers, such as -x where x is of type Integer or Number. The operator % is called a modulo, or remainder operator. It returns the remainder after division of two operands, for example, 5 % 2 returns 1. More precisely it is defined mathematically as follows:

x % y = x - trunc(x / y) * y
where
trunc(x) = sgn(x) * floor(|x|)

Evaluation of an arithmetic operation may result in an exception thrown. This can happen for addition, subtraction, multiplication, and division operations if the result is outside the limit for numbers, such as overflow if a Number value is too big, in which case an OverflowIssue exception is thrown. The division and modulus operators throw a DivisionByZeroIssue exception if the value of the second operand is zero. For example:

• 17 % 2 evaluates to 1

• -17.3 % 2.0 evaluates to -1.3

Equality operators

There are two equality operators in workflow expressions.

• == Determines if the value of one operand is equal to another

• != Determines if the value of one operand is not equal to another

These operators work on operands of all types, but the type of the operands must be the same, for instance, you cannot compare a Number to an Integer.

Relational operators

Relational operators determine if one operand is less than or greater than another operand. The operands must be numbers, that is of type Integer or Number and the types of the operands in an expression must be the same. There are four relational operators:

Operator	Description
<	less than
<=	less than or equal to
>	greater than
>=	greater than or equal to

Logical operators

There are two binary (taking two operands) logical operators: AND (&&) and OR (||), and one unary (takes one operand): NOT (!). They are defined for Boolean operands and their return type is also Boolean. The && operator returns true if the value of both of its operands is true and false in any other case. The || operator returns true if the value of at least one of its operands is true and false in case they are both false. The ! operator returns true if the value of the operand is false and returns false if the operand is true.

Evaluation of the && and || operators is slightly different from evaluation of most other operators. Normally all operands are evaluated before the operator is evaluated, but for the && and || operators the first operand is evaluated first and if this is enough to determine the result of the operation, the second argument is not evaluated. For example, in x==1 || x==2 if x is 1, the second part of the expression (x==2) is not evaluated.

Conditional operator

Conditional operator takes three operands and has the following form:

<Op>?<Op>:<Op>

where <Op> can be any operand with some restrictions. For example, x==1?0:1 evaluates to 0 if the value of x is 1 and to 1 otherwise. The type of the first operand must be Boolean and the other two operands can be of any type, but must be the same.

Evaluation of the conditional operator is also slightly different from the evaluation of most other operators. For the conditional operator, the first operand is evaluated first and then depending on its value, only one of the other two operands is evaluated. If the first operand is true (or false) then the second (or third) operand is evaluated and the result is the result of this evaluation. This also means that even if an evaluation error occurs in the operand that is not evaluated, this does not lead to an exception thrown. For example, in x == 0.0? 1.0: 1/x if x has value 0.0, 1/x is not evaluated and no DivisionByZeroIssue exception is thrown.

Summary of operators

The table below lists the expression operators.

Operator	Description	Examples
+	Addition or text concatenation	1+2 "hello " + name
-	Subtraction or negation	1-2 5-2.9 -5
*	Multiplication	42*2 1.0*17
/	Division	1/2 1/2.0
%	Modulus	x % 2 2.5 % 1.0
==,!=	Equals, not equals	true == false x != 0
<,<=	Less than, less than or equals	0 < 1 1.0 <= 0.0
>,>=	Greater than, greater than or equals	0 > 1 1.0 >= 0.0
&&,||	Logical AND, logical OR	true || x false && y
!	Logical NOT	!true
_?_:_	Conditional operator	x>0? x: 0

Parenthesis

You can use parenthesis to determine the order of evaluation in an expression and alter the result obtained from the expression. For example, the expression 1+2*3 evaluates to 7, but if you insert a parenthesis as follows: (1+2)*3, the result changes to 9, because the content of the parenthesis is evaluated before the surrounding operator.

Function

Expressions can also contain function calls. There are two ways to call a function. The first is called a direct function call and looks like this: f(<Op>,…,<Op>), such as max(1,2). The other is called a method function call and it looks like this: <Op>.f(<Op>,…,<Op>), for example, 1.max(2). The two ways are related as follows:

<Op₁>.f(<Op₂>,...,<Op_n>) is the same as f(<Op₁>,...,<Op_n>).

Functions are similar to operators in that the operands must have certain types and the result type depends on the types of the operands. For example, the function max that determines the maximum of two numbers can be called with operands of type Integer or Number and the return type is the same as the type of the operands.

If during the evaluation a function gets an operand value that is incorrect, such as outside the expected range, an IncorrectValueIssue exception is thrown.

Kofax RPA provides the following functions.

Table 1. Numeric functions

Function	Result type
abs(Integer)	Integer
abs(Number)	Number
ceil(Number)	Integer
computeMD5(binary: Binary)	Text Computes an MD5 checksum of the binary input.
floor(Number)	Integer
round(Number)	Integer
trunc(Number)	Integer
max(Integer, Integer)	Integer
max(Number, Number)	Number
min(Integer, Integer)	Integer
min(Number, Number)	Number
random()	Number Returns a random number greater than or equal to 0.0 and less than 1.0.
random(Integer, Integer)	Integer Returns a random integer greater than or equal to the value of the first operand and less than or equal to the value of the second operand.

Examples	Evaluates to the following result
abs(-2)	2
1.5.round()	2
random(1,6)	an integer value between 1 and 6

Table 2. Text functions

Function	Result type
length(Text)	Integer
substring(Text, Integer)	Text
substring(Text, Integer, Integer)	Text
indexOf(Text, Text)	Integer
contains(Text, Text)	Boolean
trim(Text)	Text
capitalize(Text)	Text
startsWith(Text, Text)	Boolean
endsWith(Text, Text)	Boolean
toLowerCase(Text)	Text
toUpperCase(Text)	Text
matches(text: Text, regex: Text)*	Boolean Checks that the text matches the regular expression.
removeNonPrintable(text: Text)	Text Removes non printable characters.
replaceAll(text: Text, regex: Text, replacement: Text)*	Replaces all sub-text that matches the regular expression with the given replacement.
unquote(text: Text)	Text Removes any quotes from a text. For example, both "hello" and 'hello' produces hello without quotes.

Note * This function may run for a long time depending on the used text and regular expression. For example, entering a lot of extra zeros in the text causes the matches function to run very long. Adding a single A at the end makes it return true almost immediately such as matches("0000000000000000000000", "(0*)*A"). Every time you change the expression, the previous evaluation is cancelled (if it is still running) and a new evaluation is started.

Example	Evaluates to the following result
"workflow".substring(5)	low

Table 3. Conversion functions. Conversion functions convert values from one type to another. Conversion may fail if the value of the operand does not represent a value that can be converted into a value of the result type.

Function	Result type
ampersandEncode(text: Text)	Text Ampersand encode a text.
ampersandDecode(text: Text)	Text Ampersand decode a text.
base64Encode(binary: Binary)	Text Base64 encode using Base64 transfer encoding for MIME (RFC 2045).
base64Decode(text: Text)	Binary Base64 decode using Base64 transfer encoding for MIME (RFC 2045).
boolean(text: Boolean)	Boolean The text must match either "true" or "false".
integer(Number)	Integer The number must be an integer value, for example 1.0
integer(Text)	Integer The text must be a text representation of an integer, such as "42"
number(Integer)	Number
number(Text)	Number Text must be a text representation of a number, such as "17.7"
text(Integer)	Text
text(Number)	Text
text(Boolean)	Text
text(binary: Binary, charsetName: Text)	Text Converts a binary representation of a text into a value of type Text. Specify a character set, such as UTF8 as an argument.
binary(text: Text, charsetName: Text)	Binary Converts a text value into a binary value. Specify a character set, such as UTF8 as an argument.
toJSON()	Converts any type of value except Password to a text value formatted as JSON object. Record types that contain a Password type attribute cannot be converted to JSON. Converted value examples 5 becomes "5" 1.2 becomes "1.2" true becomes "true" "Hello" becomes "\"Hello\"" A binary value becomes a base 64 encoding of the binary value A record value, R(a = 5, b = true, t = "Hello") becomes "{\"a\":5,\"b\":true,\"t\":\"Hello\"" Note Workflow State view does not show reverse slashes before quote marks. The way the converted record value is shown above is how you have to write it in an expression. toJSON function cannot generate an array, such as [1, 2, 3]. When you use a JSON value in a Desktop Automation robot, you can create the list yourself by string concatenation. This way you can return values from the Desktop Automation robot the web automation robot. See Work with JSON for more information.

The following table lists and describes examples of conversion functions written in two ways: direct function call such as text(2), and method call such as 2.text(). While in the first variant the function is called directly, the second variant enables you to use text completion when writing expressions in the expression mode. For more information, see Expression Mode later in this section.

Examples
Function	Evaluates to the following result
ampersandEncode("<b/>") or "<b/>".ampersandEncode()	&lt;b/&gt;
ampersandDecode("&lt;b/&gt;") or "&lt;b/&gt;". ampersandDecode()	<b/>
base64Encode(bin) or bin.base64Encode() where bin is a variable containing a Binary value resulting from "Hello".binary("ASCII")	SGVsbG8=
base64Decode("SGVsbG8=").text("UTF8") or "SGVsbG8=".base64Decode().text("UTF8")	Hello
"true".boolean() "false".boolean() "False".boolean()	Boolean true Boolean false Throws a ConversionIssue exception as it does not must match neither "true" nor "false"
integer(2.0) or 2.0.integer() integer("2") or "2".integer	2
number(2) or 2.number() number("2") or "2".number()	2.0
number(".1E10") or ".1E10".number()	1.0E9
"Hello".binary("UTF8").text("UFT8") where "Hello".binary("UTF8") evaluates to a binary value encoded using the UTF8 character encoding. When the binary value is converted to text, as in this example, the binary value must be encoded using the same character encoding (UTF8 in this case).	Hello
"hello".toJSON()	"hello"
17.7.toJSON()	17.7
true.toJSON()	true
Company.toJSON() where Company is a variable of a record type containing Text, Integer, and Boolean field types.	a Text value with the following value: {"name":"Acme Corp.", "url":"www.acme-corp.com", "revenue":1000000000, "CEO":"Marvin Acme", "fictional":true}

Limits for number values

Integers

The largest integer that can be represented is 1E34-1. This is a number with 34 nines. If you have this number and add 1 to it, you get an OverflowIssue exception. Likewise the smallest integer value that can be represented is -1E34+1. So all integer values must be in the interval from -1E34+1 and to 1E34-1 (both included).

Numbers

Representation of numbers matches the IEEE 754R Decimal128 that uses 34 decimal digits and a representation of the exponent in the range of −2147483648 to +2147483648. If evaluation of an expression leads to a number outside the range, you get an OverflowIssue exception.

See Limits in Numbers for more information.

It is possible to enter numbers with an exponent as follows:

1.234E5, 0.1E-2, 1000.0e42, etc.

A base number is optionally followed by an E or e and an integer exponent. When numbers are displayed in the Desktop Automation Workflow State view or in the Expression editor, they are normalized according to the following rules:

• One trailing zero is shown after the decimal point if there are no other decimal digits, such as 1.0E12
• The exponent is only shown if it is numerically larger than or equal to 9, that is:
• • 1.0E8 is shown as 100000000, but 1.0E9 is shown as 1.0E9
  • 1.0E-8 is shown as .000000001, but 1.0E-9 is shown as 1.0E-9
• All digits up to the maximum number of 34 are shown (numbers are rounded off to have a maximum of 34 digits). For example, number 9.999999999999999999999999999999999 is shown as is. If you add one more 9 to this number, it is shown as 10.0. Actually the number value is rounded off so that internally it is also represented as 10.0. Therefore, the numbers can be entered in one way and displayed in another way, which adds some flexibility in how numbers may be entered, such as 10.0 or 0.1E2.

The conversion function text(Number) also returns the number written according to the above rules.