Expressions

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

Many properties on Robot 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 Robot.

Expressions in the Robot are very similar to expressions in most common programming languages, such as Java, C#, JavaScript, and so on. They consist of constants, variables, operations (addition, subtraction, multiplication, comparison operations, logic operation, and so on), 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 Robot.

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 and the Expression Editor:

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 (") as 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 To use line break in the built-in browser, 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, Number, Date, Time, or DateTime. 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:

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	422 1.017
/	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.

Functions

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:

Numeric
Text
DateTime
Date
Time
Conversion

Numeric functions

Function	Result type	Example
abs(Integer)	Integer	abs(-5) returns 5.
abs(Number)	Number	abs(-2) returns 2.
ceil(Number)	Integer	Returns the least integer greater than or equal to the number. ceil(2.4) returns 3.
computeMD5(binary: Binary)	Text	Computes an MD5 checksum of the binary input.
floor(Number)	Integer	Returns the least integer smaller than or equal to the number. floor(8.7) returns 8.
round(Number)	Integer	Returns the least integer greater or smaller to the number basing on the arithmetic rules. round(1.4) returns 1. round(1.6) returns 2.
trunc(Number)	Integer	Returns the number without the decimal part. trunc(4.8732) returns 4.
max(Integer, Integer)	Integer	max(4, 9) returns 9.
max(Number, Number)	Number	max(12, 99) returns 99.
min(Integer, Integer)	Integer	min(23, 47) returns 23.
min(Number, Number)	Number	min(15.01, 32.5) returns 15.01.
random()	Number	Returns a random number greater than or equal to 0.0 and less than 1.0. random()
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. random(5, 96)

Text functions

Function	Result type	Example
ampersandDecode(Text)	Text	ampersandDecode(">") returns >.
ampersandEncode(Text)	Text	ampersandEncode(">") returns >.
base64Decode(Text)	Binary	base64Decode("SGVsbG8=").text("UTF8") returns Hello.
binary(Text, Text)	Binary	Converts text value into binary. "Hello".binary("UTF8")
boolean(Text)	Boolean	The text can be either "true" or "false". boolean("true") returns "true" of type Boolean.
capitalize(Text)	Text	Returns text, where all words are capitalized: all words start with an upper case letter and have the remaining letters in the lower case. capitalize("hello world") returns Hello World.
contains(Text, Text)	Boolean	Checks that the text contains the specified text. contains("I have found it", "have") returns true.
endsWith(Text, Text)	Boolean	endsWith("Why portraits have fascinated us for millennia", "millennia") returns true.
indexOf(Text, Text)	Integer	indexOf("Why portraits have fascinated us for millennia", "millennia") returns 37.
integer(Text)	Integer	integer("7") returns 7 of type Integer.
length(Text)	Integer	Returns the length of the text, calculating the number of symbols. length("Hello") returns 5.
matches(text: Text, regex: Text)*	Boolean	Checks that the text matches the regular expression. matches("My phone number is 123-45-678", "(.*)( \\d{3}-\\d{2}-\\d{3})") returns true.
number(Text)	Number	number(987) returns 987.0.
password(Text)	Password	Converts a text into a password. This is useful when a password is required to log in to an application during the robot development. For security reasons, this function should not be used in a production environment. password("123abc!@") returns Password=074f4d84dfe28d...
removeNonPrintable(Text)	Text	Returns a text without non-printable characters. removeNonPrintable("Text with non-printable characters")
replaceAll(text: Text, regex: Text, replacement: Text)*		Replaces all sub-text that matches the regular expression with the given replacement. Regular expressions support multiple matches and references with $. "345-84-7735".replaceAll(") returns 345-84-7735. Note that the backslash must be escaped.
startsWith(Text, Text)	Boolean	startsWith("To be or not to be", "To") returns true.
substring(Text, Integer)	Text	"workflow".substring(5) returns low.
substring(Text, Integer, Integer)	Text	substring("DesignStudio",1,8) returns esignSt.
toJSON(Text)	Text	toJSON("Hello") returns "Hello" as a text.
toLowerCase(Text)	Text	toLowerCase("START") returns start.
toUpperCase(Text)	Text	toUpperCase("sun") returns SUN.
trim(Text)	Text	Removes all space and white space characters from both ends of the text string. trim(" Let's start ") returns Let's start.
unquote(text: Text)	Text	Removes any quotes from a text. "\"hello\"".unquote() returns hello without quotes.

* 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.

DateTime functions. The result of the DateTime functions contains the date, time, time zone ID, and offset. The representation depends on the specified parameters. By default, unless a specific time zone is indicated manually, the local time zone of the computer is used, which is determined when the expression being evaluated.

Function	Result type
dateTime()	DateTime Returns the current date (year, month, day), time (hours, minutes, seconds), offset and zoneID.
dateTime(date: Date, time: Time)	DateTime Returns the specified date and time. Example dateTime(date(2022, 1, 10), time(12, 0, 5)) returns date: year = 2022, month = 1, day = 10; time: hour = 12, minutes = 0, seconds = 5, nanoseconds = 0; zoneID = "<time zone of the DateTime>."
dateTime(date: Date, time: Time, zone: Text)	DateTime Returns the specified date, time, and time zone ID or offset. Example dateTime(date(2010,11,08), time(12,44,00), zoneId(Dublin))
dateTime(text: Text, pattern: Text)	DateTime Converts a Text value into a DateTime value using the default locale of the computer. Example dateTime("2022-01-02 12:30", "yyyy-MM-dd HH:mm")
dateTime(text: Text, pattern: Text, locale: Text)	DateTime Creates a DateTime value from a text using a pattern and a locale. Example dateTime("January 1, 2022 12:30", "MMMM d, yyyy HH:mm ", "en-US").
dateTime(text: Text, pattern: Text, defaultDate: Date)	DateTime Converts a Text value into a DateTime value using a pattern and a default date to use if the text does not contain a date. Example dateTime("12:30", "HH:mm", date()) Here the date is the current date.
dateTime(text: Text, pattern: Text, dafaultDate: Date, locale: Text)	DateTime Creates a DateTime value from a text using a pattern, a default date and a locale. The locale is used if the pattern matches a text with a date in which case the default date is not used. The default date is used if the text does not contain a date. Example dateTime(text, "[MMMM d, yyyy] HH:mm", date(), "en-US"), where text is a variable containing the date to extract and date() is the current date. The pattern matches both texts: January 1, 2022 12:30 and 12:30. In the first case, it returns a DateTime value with the date January1, 2022, and in the second case, it returns it with the current date. In both cases the time is 12:30.
offset(dateTime: DateTime)	Text Returns the offset of the DateTime value. Example offset(dateTime()) returns the offset of the current date on your computer, such as+01:00.
zoneId(dateTime: DateTime)	Text Returns the time zone of the DateTime value. Example zoneId(dateTime()) returns the value of the zoneID of the current date, such as Europe/Paris.
withYears(dateTime: DateTime, years: Integer)	DateTime Returns a copy of the date and time with the year altered. Example dateTime(date(2021, 7, 20), time(12, 13, 14)).withYears(2022) returns the DateTime value where the year is 2022.
withMonth(dateTime: DateTime, months: Integer)	DateTime Returns a copy of the date and time with the month altered. For an example, see "withYears."
withDay(dateTime: DateTime, days: Integer)	DateTime Returns a copy of the date and time with the day altered. For an example, see "withYears."
withHour(dateTime: DateTime, hours: Integer)	DateTime Returns a copy of the date and time with the hour altered. For an example, see "withYears."
withMinute(dateTime: DateTime, minutes: Integer)	DateTime Returns a copy of the date and time with the minute altered. For an example, see "withYears."
withSecond(dateTime: DateTime, seconds: Integer)	DateTime Returns a copy of the date and time with the second altered. For an example, see "withYears."
withNano(dateTime: DateTime, nanos: Integer)	DateTime Returns a copy of the date and time with the nanosecond altered. For an example, see "withYears."
withOffset(dateTime: DateTime, offset: Text)	DateTime Returns a copy of the date and time at the specified offset. Changing the offset may change the zone ID, so the offset and the zone ID are consistent with each other. Example (given the offset of +1) withOffset(dateTime(), "+3") returns the time with the offset of +3, which means the time is 2 hours ahead of the current time. Also, the zone ID changes to UTC +03:00, which is Europe/Moscow.
withZoneId(dateTime: DateTime, zoneID: Text)	DateTime Returns a copy of the date and time in the specified time zone. Changing the zone ID may change the offset, so the zone ID and the offset are consistent with each other. Example withZoneId(dateTime(), "Europe/Moscow") returns current time in the specified zone ID.
plusYears(dateTime: DateTime, amount: Integer)	DateTime Returns a copy of the date and time with the specified number of years added. Example dateTime(date(2021, 7, 20), time(12, 13, 14)).plusYears(1) returns a DateTime value with the date 2022-07-22 12:13:14.0 at the time zone where the Robot is executed.
plusMonths(dateTime: DateTime, amount: Integer)	DateTime Returns a copy of the date and time with the specified number of months added. All "plus" functions operate with a calendar rollover. For an example, see "plusDays."
plusWeeks(dateTime: DateTime, amount: Integer)	DateTime Returns a copy of the date and time with the specified number of weeks added. All "plus" functions operate with a calendar rollover. For an example, see "plusDays."
plusDays(dateTime: DateTime, amount: Integer)	DateTime Returns a copy of the date and time with the specified number of days added. All "plus" functions operate with a calendar rollover. In the following example with plusDays(70), given that March has 31 days and April has 30 days, 27 days are first added to the 4th day of March, and then the remaining 43 days are added, resulting in the 13th of May. Example dateTime(date(2022, 3, 4), time(12, 13, 14)).plusDays(70) returns date: year = 2022, month = 5, day = 13; time: hour = 12, minute = 13, second = 14, nanosecond = 0; zoneID = "<time zone of the DateTime>."
plusHours(dateTime: DateTime, amount: Integer)	DateTime Returns a copy of the date and time with the specified number of hours added. All "plus" functions operate with a calendar rollover. For an example, see "plusDays."
plusMinutes(dateTime: DateTime, amount: Integer)	DateTime Returns a copy of the date and time with the specified number of minutes added. Example dateTime(date(2022, 7, 20), time(12, 13, 14)).plusMinutes(7) returns date: year = 2022, month = 7, day = 20; time: hour = 12, minutes = 20, seconds = 14, nanoseconds = 0; zoneID = "<time zone of the DateTime>" All "plus" functions operate with a calendar rollover.
plusSeconds(dateTime: DateTime, amount: Integer)	DateTime Returns a copy of the date and time with the specified number of seconds added. All "plus" functions operate with a calendar rollover. For an example, see "plusDays."
plusNanos(dateTime: DateTime, amount: Integer)	DateTime Returns a copy of the date and time with the specified number of nanoseconds added. All "plus" functions operate with a calendar rollover. For an example, see "plusDays."
minusYears(dateTime: DateTime, amount: Integer)	DateTime Returns a copy of the date and time with the specified number of years subtracted. Example dateTime(date(2022, 7, 20), time(12, 13, 14)).minusYears(10) returns a DateTime value with the date 2012-07-22 12:13:14.0 at the time zone where the Robot is executed.
minusMonths(dateTime: DateTime, amount: Integer)	DateTime Returns a copy of the date and time with the specified number of months subtracted. Example dateTime(date(2022, 7, 20), time(12, 13, 14)).minusMonths(10) returns a DateTime value with the date 2021-09-20 12:13:14 at the time zone where the Robot is executed.
minusWeeks(dateTime: DateTime, amount: Integer)	DateTime Returns a copy of the date and time with the specified number of weeks subtracted. All "minus" functions operate with a calendar rollover. For an example, see "minusMonths."
minusDays(dateTime: DateTime, amount: Integer)	DateTime Returns a copy of the date and time with the specified number of days subtracted. All "minus" functions operate with a calendar rollover. In the following example with minusDays(20), given that March has 31 days and February has 29 days, 14 days are first subtracted from the 14th day of March, and then the remaining 6 days are subtracted, resulting in the 23rd of February. Example dateTime(date(2020, 3, 14),time(12, 13, 14)).minusDays(20) returns date: year = 2020, month = 2, day = 23; time: hour = 12, minutes = 14, seconds = 14, nanoseconds = 0; zoneID = "<time zone of the DateTime>."
minusHours(dateTime: DateTime, amount: Integer)	DateTime Returns a copy of the date and time with the specified number of hours subtracted. All "minus" functions operate with a calendar rollover. For an example, see "minusDays."
minusMinutes(dateTime: DateTime, amount: Integer)	DateTime Returns a copy of the date and time with the specified number of minutes subtracted. All "minus" functions operate with a calendar rollover. For an example, see "minusDays."
minusSeconds(dateTime: DateTime, amount: Integer)	DateTime Returns a copy of the date and time with the specified number of seconds subtracted. All "minus" functions operate with a calendar rollover. For an example, see "minusDays."
minusNanos(dateTime: DateTime, amount: Integer)	DateTime Returns a copy of the date and time with the specified number of nanoseconds subtracted. All "minus" functions operate with a calendar rollover. For an example, see "minusDays."
yearsUntil(from: DateTime, to: DateTime)	Integer Calculates the number of years from the first DateTime argument to the second DateTime argument. Example dateTime(date(2022, 1, 20), time(12, 13, 14)).yearsUntil(dateTime(date(3785, 11, 20), time(12, 13, 14))) returns 1763.
monthsUntil(from: DateTime, to: DateTime)	Integer Calculates the number of months from the first DateTime argument to the second DateTime argument. Example dateTime(date(2022, 1, 20), time(12, 13, 14)).monthsUntil(dateTime(date(2022, 11, 20), time(12, 13, 14))) returns 10.
daysUntil(from: DateTime, to: DateTime)	Integer Calculates the number of days from the first DateTime argument to the second DateTime argument. For an example, see "monthsUntil."
hoursUntil(from: DateTime, to: DateTime)	Integer Calculates the number of hours from the first DateTime argument to the second DateTime argument. For an example, see "monthsUntil."
minutesUntil(from: DateTime, to: DateTime)	Integer Returns the number of minutes from the first DateTime argument to the second DateTime argument. For an example, see "monthsUntil."
secondsUntil(from: DateTime, to: DateTime)	Integer Returns the number of seconds from the first DateTime argument to the second DateTime argument. For an example, see "monthsUntil."
millisUntil(from: DateTime, to: DateTime)	Integer Returns the number of milliseconds from the first DateTime argument to the second DateTime argument. For an example, see "monthsUntil."
nanosUntil(from: DateTime, to: DateTime)	Integer Returns the nanoseconds of nanoseconds from the first DateTime argument to the second DateTime argument. For an example, see "monthsUntil."
dayOfYear(dateTime: DateTime)	Integer Returns the day of the year. Example dateTime(date(2022, 3, 1), time(12, 13, 14)).dayOfYear() returns day = 60
weeksUntil(from: DateTime, to: DateTime)	Integer Returns the number of weeks from the first DateTime argument to the second DateTime argument. Example dateTime(date(2022, 1, 20), time(12, 13, 14)).weeksUntil(dateTime(date(2025, 11, 20), time(12, 13, 14))) returns 200.
text(dateTime: DateTime)	Text Converts a DateTime value into a text representation. Example text(dateTime()) returns the current date and time, for example, 2022-02-10T13:46:56.907958+01:00[Europe/Paris].
text(dateTime: DateTime, pattern: Text)	Text Converts a DateTime value into a text representation matching the specified pattern and locale. The pattern can be specified in many different ways, such as: "d/M/yyyy HH:mm" "d-M-yyyy HH:mm:ss" Examples (given the DateTime of 2022-12-20T00:30:00+03:00) text("d/M/yyyy HH:mm") returns 20/12/2022 00:30.
text(dateTime: DateTime, pattern: Text, locale: Text)	Text Returns the text representation of the date and time of DateTime matching the specified pattern and locale. The pattern can be specified in many different ways, such as: "d/M/yyyy HH:mm" "d-M-yyyy HH:mm:ss" "EEEE MMM d yy HH:mm" (where EEEE would return the week day spelled out in full, MMM would return the month name abbreviated to three letters, and so on) The locale is specified as follows: en-US, fr-FR, ja-JP, ru-RU, and so on. Examples (given the current date is 20.12. 2021 00:30:00) text("EEEE MMM d yy HH:mm", "en-US") returns Monday Dec 20 21 00:30. text("EEE MMMM d yyyy HH:mm", "en-US") returns Mon December 20 2021 00:30. text("yyyy'年'MM'月'd'日' HH:mm:ss","ja-JP") returns 2021年12月20日 00:30:00.
fromExcelDate(excelDate: Number)	DateTime Converts a DateTime value into an Excel date represented as a number. Example (given the ExcelDate value is 44969) ExcelDate.fromExcelDate() returns year=2023, month=2, day=12.
toExcelDate(dateTime: DateTime)	Number Converts a DateTime value into an Excel date represented as a number. Example (given the current date is 08.02.2022 18:45:00) dateTime().toExcelDate() returns 44600.76050844907149439677596092224.

Date functions

Function	Result type
date()	Date Returns the current date.
date(year: Integer, month: Integer, day: Integer)	Date Returns the date with the specified year, month, and day.
date(DateTime)	Date If DateTime is specified previously, it returns the date value of DateTime.
date(text: Text, pattern: Text)	Date Converts a Text value into a Date value using a pattern. Example date("2022-01-02", "yyyy-MM-dd")
date(text: Text, pattern: Text, locale: Text)	Date Converts a Text value into a Date value using a pattern and a locale. Example date("January 1, 2022", "MMMM d, yyyy", "en-US")
year(date: Date)	Integer Returns the year of the current date.
month(date: Date)	Integer Returns the month (between 1 and 12) of the current date.
day(date: Date)	Integer Returns the day of the month (between 1 and 31) of the current date.
withYear(date: Date, years: Integer)	Date Returns a copy of the date with the year altered. Example date(2022, 3, 4).withYear(2037) returns year = 2037, month = 3, day = 4.
withMonth(date: Date, months: Integer)	Date Returns a copy of the date with the month altered. date(2022, 3, 4).withMonth(5)returns year = 2022, month = 8, day = 4.
withDay(date: Date, days: Integer)	Date Returns a copy of the date with the day altered. Example date(2022, 3, 4).withDay(10) returns year = 2022, month = 3, day = 10.
plusYears(date: Date, amount: Integer)	Date Returns a copy of the date with the specified number of years added. All "plus" functions operate with a calendar rollover. For an example, see "plusDays."
plusMonths(date: Date, amount: Integer)	Date Returns a copy of the date with the specified number of months added. All "plus" functions operate with a calendar rollover. For an example, see "plusDays."
plusWeeks(date: Date, amount: Integer)	Date Returns a copy of the date with the specified number weeks added. All "plus" functions operate with a calendar rollover. For an example, see "plusDays."
plusDays(date: Date, amount: Integer)	Date Returns a copy of the date with the specified number of days added. All "plus" functions operate with a calendar rollover. In the following example with plusDays(70), given that March has 31 days and April has 30 days, 27 days are first added to the 4th day of March, and then the remaining 43 days are added, resulting in the 13th of May. Example date(2022, 3, 4).plusDays(70) returns year = 2022, month = 5, day = 13.
minusYears(date: Date, amount: Integer)	Date Returns a copy of the date with the specified number of years subtracted. All "minus" functions operate with a calendar rollover. date(2022, 3, 14).minusYears(20) returns year= 2002, month = 3, day = 4.
minusMonths(date: Date, amount: Integer)	Date Returns a copy of the date with the specified number of months subtracted. All "minus" functions operate with a calendar rollover. For an example, see "minusDays."
minusWeeks(date: Date, amount: Integer)	Date Returns a copy of the date with the specified number of weeks subtracted. All "minus" functions operate with a calendar rollover. For an example, see "minusDays."
minusDays(date: Date, amount: Integer)	Date Returns a copy of the date with the specified number of days subtracted. All "minus" functions operate with a calendar rollover. In the following example with minusDays(20), given that March has 31 days and February has 29 days, 14 days are first subtracted from the 14th day of March, and then the remaining 6 days are subtracted, resulting in the 23rd of February. Example date(2022, 3, 14).minusDays(20) returns year = 2022, month = 2, day = 23.
yearsUntil(from: Date, to: Date)	Integer Returns the number of years from the first Date argument to the second Date argument. Example (given that the current year is 2022) date().yearsUntil(date(2023, 11, 12)) returns 1.
monthsUntil(from: Date, to: Date)	Integer Returns the number of months from the first Date argument to the second Date argument. For an example, see "yearsUntil."
daysUntil(from: Date, to: Date)	Integer Returns the number of days from the first Date argument to the second Date argument. For an example, see "yearsUntil."
weeksUntil(from: Date, to: Date)	Integer Returns the number of weeks from the first Date argument to the second Date argument. For an example, see "yearsUntil."
isLeapYear(date: Date)	Boolean Returns "true" if the year is a leap year; otherwise, returns "false." Example date(2020, 3, 4).isLeapYear returns true because 2020 was a leap year.
text(date: Date)	Text Converts a Date value into a text representation. Example text(date(2000, 12, 25)) returns 2000-12-25.
text(date: Date, pattern: Text)	Text Converts a Date value into a text representation matching the specified pattern. Example text(date(2000, 12, 25), "M/YY/d") returns 12/00/25.
text(date: Date, pattern: Text, locale: Text)	Text Converts Date value into a text representation matching the specified pattern and locale. Example text(date(2023, 12, 12), "MMMM d, yyyy", "de-DE") returns Dezember 12, 2023.

Time functions

Function	Result type
time()	Time Returns the current time.
time(hours: Integer, minutes: Integer, seconds: Integer)	Time Returns the time with the specified hour, minute, and second.
time(hours: Integer, minutes: Integer, seconds: Integer, nanos: Integer)	Time Returns the time with the specified hour, minute, second, and nanosecond.
time(dateTime: DateTime)	Time If DateTime is specified previously, it returns the time value of DateTime.
time(text: Text, pattern: Text, locale: Text)	Time Converts a Text value into a Time value using the specified pattern and locale. Example time("January 1, 2022 12:30", "MMMM d, yyyy hh:mm a", "en-US")
hour(time: Time)	Integer Returns the hour of the current time.
minute(time: Time)	Integer Returns the minute of the current time.
second(time: Time)	Integer Returns the second of the current time.
nanosecond(time: Time)	Integer Returns the nanosecond of the current time.
withHour(time: Time, hours: Integer)	Time Returns a copy of the time with the hour altered. Example time(14, 50, 45).withHours(2) returns hour = 2, minute = 50, second = 45, nanosecond = 0.
withMinute(time: Time, minutes: Integer)	Time Returns a copy of the time with the minute altered. For an example, see "withHour."
withSecond(time: Time, seconds: Integer)	Time Returns a copy of the time with the second altered. For an example, see "withHour."
withNano(time: Time, nanos: Integer)	Time Returns a copy of the time with the nanosecond altered. For an example, see "withHour."
plusHours(time: Time, amount: Integer)	Time Returns a copy of the time with the specified number of hours added. Example time(14, 50, 45).plusHours(2) returns hour = 16, minute = 50, second = 45, nanosecond = 0.
plusMinutes(time: Time, amount: Integer)	Time Returns a copy of the time with the specified number of minutes added. For example, see "plusHours."
plusSeconds(time: Time, amount: Integer)	Time Returns a copy of the time with the specified number of seconds added. For example, see "plusHours."
plusNanos(time: Time, amount: Integer)	Time Returns a copy of the time with the specified number of nanoseconds added. For example, see "plusHours."
minusHours(time: Time, amount: Integer)	Time Returns a copy of the time with the specified number of hours subtracted. Example time(14, 50, 45).minusHours(2) returns hour 12, minute = 50, second = 45, nanosecond = 0.
minusMinutes(time: Time, amount: Integer)	Time Returns a copy of the time with the specified number of minutes subtracted. For example, see "minusHours."
minusSeconds(time: Time, amount: Integer)	Time Returns a copy of the time with the specified number of seconds subtracted. For example, see "minusHours."
minusNanos(time: Time, amount: Integer)	Time Returns a copy of the time with the specified number of nanoseconds subtracted. For example, see "minusHours."
hoursUntil(from: Time, to: Time)	Integer Returns the number of hours from the first Time argument to the second Time argument. Example time(9, 41, 35).hoursUntil(time(15, 34, 12)) returns 5.
minutesUntil(from: Time, to: Time)	Integer Returns the number of minutes from the first Time argument to the second Time argument. For an example, see "hoursUntil."
secondsUntil(from: Time, to: Time)	Integer Returns the number of seconds from the first Time argument to the second Time argument. For an example, see "hoursUntil."
millisUntil(from: Time, to: Time)	Integer Returns the number of milliseconds from the first Time argument to the second Time argument. For an example, see "hoursUntil."
nanosUntil(from: Time, to: Time)	Integer Returns the number of nanoseconds from the first Time argument to the second Time argument. For an example, see "hoursUntil."
toSecondsOfDay(time: Time)	Integer Converts the time into seconds. Example time(1, 0, 0).toSecondsOfDay() returns 3600.
toNanosOfDay(time: Time)	Integer Converts the time into nanoseconds. Example time(1, 0, 0).toNanosOfDay() returns 3600000000000.
text(time: Time)	Text Converts a Time value into a text representation. Example text(time(10, 15, 00)) returns 10:15:00.
text(time: Time, pattern: Text)	Text Converts a Time value into a text representation matching the specified pattern. Example text(time(10, 15, 00), "hh:m a") returns 10:15 AM.
text(time: Time, pattern: Text, locale: Text)	Text Converts a Time value into a text representation matching the specified pattern and locale. Example text(time(10, 15, 00), "hh:m a", "de-DE") returns 10:15 vorm.

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. Example ampersandEncode("&") returns &.
ampersandDecode(text: Text)	Text Ampersand decode a text. Example ampersandDecode(">") returns >.
base64Encode(binary: Binary)	Text Base64 encode using Base64 transfer encoding for MIME (RFC 2045). Example binary.base64Encode(), where binary is a variable with a Binary value.
base64Decode(text: Text)	Binary Base64 decode using Base64 transfer encoding for MIME (RFC 2045). Example base64Decode("SGVsbG8=").text("UTF8") returns Hello.
boolean(text: Boolean)	Boolean The text must match either "true" or "false". Example boolean(false:Boolean) returns false.
integer(Number)	Integer The number must be an integer value, such as 1.0.
integer(Text)	Integer The text must be a text representation of an integer, such as "42".
number(Integer)	Number number(17)returns 17.0.
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. Example "Hello".binary("UTF8").text("UTF8") returns Hello. "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).
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\"" The 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 Robot, you can create the list yourself by string concatenation. This way you can return values from the Robot to the Basic Engine 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()	<b/>
ampersandDecode("<b/>") or "<b/>". 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

Consider the following 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 Data 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.

Expression Editor

The Expression Editor is an interactive editor that opens when you click an input field in the Robot and if the given field supports entering an expression. The editor consists of two horizontal panes. The upper pane is the input pane to enter and edit the expression and the lower pane is the result pane. The result pane can show the result of evaluating the expression, an error message, or both. The following errors can be shown:

Parse errors: The syntax of the expression is incorrect.
Type errors: There is a type error in the expression or the result does not have the correct type.
Evaluation errors: Some error occurred while evaluating the expression, such as division by zero.

In the following example, the expression is x + 1.0 where x is a variable of Integer type. The expression is correctly typed, but as the result is assigned to the variable of Integer type, an error message shows that the result type of the expression is not the expected one.

You can copy the result of the expression and the error message from the lower pane of the editor by right clicking it and selecting Copy Value. If the value is a record type, the result is shown as a tree and each attribute value can be copied separately. Password and Binary values cannot be copied.

To close the Expression Editor, click outside the editor or press Esc.

Editor Modes

The editor has a mode button to the left of the upper pane that switches between an expression and a value mode. The editor in the figure above is in the Expression mode. When the editor is in the Value mode, the mode button is blank. When the editor is in the expression mode, the button shows an equals sign (=). You can use the keyboard shortcut Ctrl-E to switch between the two modes.

Value Mode

In the value mode, the entered value is simply interpreted as a value, such as a Text, a Boolean, a Number, etc. and no evaluation takes place. The result panel shows the result. The only error that can be shown is when the result type is incorrect.

If in the value mode, the entered value starts with "=", the editor switches to the expression mode.

Device Automation Expression editor in Value mode

Expression Mode

In the expression mode, everything you type in the input pane is interpreted as an expression and checked for syntax and type errors. If you are editing an expression at the current flow point and there are no errors, it is evaluated and its result is displayed. The evaluation happens while you are typing so that you always know what the state of your expression is. If you are editing an expression that is not at the current flow point, it is evaluated if it does not contain any variables, that is if its value does not depend on the current state.

If there is an error during evaluation of an expression, for example divide by zero, the Result pane reports this by showing the name of the exception and a message describing the issue. You can copy the name of the exception by right-clicking it and selecting Copy Value.

Devide by zero error in the Expression Editor

Text completion in the expression mode helps entering names of variables, field names, and function names. The text completion window automatically appears when you type something that has a completion help. For example, if you start typing a variable name and there is a variable starting with what you have already typed, the completion window appears. If you press a dot (.) after a variable of record type, the completion window shows a list of completion options corresponding to the fields of the record type. The following example shows completion help after typing "p".

If you press a dot (.) after a sub-expression of simple type, the completion window shows a list of completion options corresponding to the function for which the first argument has the same simple type.

To navigate the options in the completion list, use the arrow keys or a mouse. To select an option in the completion list, press Enter, Tab, or double-click the option. To open the completion window without typing anything, press Ctrl+Space. To close the completion window, click outside the window or press Esc.

If a part of an expression is selected in the input pane and this selection corresponds to a proper sub-expression (one that may be evaluated on its own), the value of this sub-expression is shown in the result pane as in the following figure.

If you select the name of a function in the Input pane, a description of this function is shown in the Result pane.