1. Using Robots in Oracle Integration 3
  2. Best Practices and Guidelines
  3. Guidelines for Expressions

Pre-General Availability: 2024-09-02

Guidelines for Expressions

When you define an action in a robot, you sometimes need to update a value, complete a calculation using the value, or perform an operation on the value. Complete these tasks by using expressions. For each expression, you must use the correct syntax.

About Expressions

An expression performs an operation on a value and returns another value.

When building a robot, you can use expressions in many fields. The value that an expression works with can come from many places, including:

  • An application that the robot interacts with.

  • Another application.

  • A variable, parameter, or property that you define.

  • A value that you define.

For more real-world examples of expressions, see Use Cases.

Mathematical Operators

A mathematical operator performs math operations, such as addition and subtraction.

Operator Python equivalent Description Expression Returns
+ + Addition ${2+2} 4
- - Subtraction ${3-1} 2
* * Multiplication ${3*2} 6
/ / Division ${8/4} 2
% % Modulo, which returns the remainder of a division ${3%2} 1

Comparison Operators

A comparison operator compares values and returns true or false.

Operator Python equivalent Description Expression Returns
> >

Greater than

 ${2>3} false
< <

Less than

 ${1<3} true
>= >=

Greater than or equal to

 ${2>=1} false
<= <=

Less than or equal to

 ${4<=5} true
== ==

Equal to

${1==1}

${one==one}

 true

Logical Operators

A logical operator combines two comparisons and returns true or false.

Operator Python equivalent Description Expression Returns
&& and

Both statements must be true

${1<=2 && 2<=3}

true
|| or

Either statement must be true

${2<=1 || 3<=2}

 false

Inversion Operators

An inversion operator returns the opposite result from what you'd expect.

Operator Python equivalent Description Expression
! not

NOT operation, which inverses the result of a comparison

Use parentheses to clearly separate the NOT operation (!) from the expression.

${!(1>=2)} returns true

${!(1<=2 && 2<=3)} returns false

${!(2<=1 || 3<=2)} returns true

Functions

A function takes in data, processes it, and returns a result.

Function Python equivalent Description Format Example
toNumber

No direct equivalent, though you can use int() and float() to convert strings to numbers

Returns an integer or float for a numerical string.

${toNumber(value)}

where:

value is the number to return

Return a number from a numeric string value

toNumber("100.00") returns 100.00

toNumber("100,000") returns 100000

toNumber("100,000.00") returns 100000.00

toNumber($VARIABLE.amount) returns a value according to the value of the variable:

  • If $VARIABLE.amount is 100, returns 100
  • If $VARIABLE.amount is 100.00, returns 100.00

If the string value contains any non-numeric characters, an error occurs. For example, toNumber("100A") returns an error

toString

str()

Returns a string that represents an object.

${toString(value)}

where:

value is the string to return

Return a string that represents a number

${toString(1)} returns 1

Return a person's first and last name

You define a data type named Person. Person contains two properties: First_name and Last_name.

Next, you define a variable, var1. Base var1 on the Person data type.

A robot returns the following values for the variable:

  • var1.FirstName = “John”
  • var1.Lastname = “Doe”

Given this scenario, the following expression:

${toString(var1)}

returns { “FirstName”: “John”,. “lastName”: “Doe” }
subString $name[start:stop]

Returns the specified characters within a string.

Indexes are zero based. In plain English, a zero-based index means that you start counting the values at 0. For example, if you're using a substing function for the value ABC:
  • A is entry 0
  • B is entry 1
  • C is entry 2

${subString(string, startIndex, endIndex)}

where:

  • string is the string to evaluate
  • startIndex is the first character to include in the returned substring
  • endIndex is the last character to include in the returned substring

Return a subset of letters

${subString(ABCDEF, 0, 0)} returns A

${subString(ABCDEF, 1, 1)} returns B

${subString(ABCDEF, 2, 4)} returns CDE

Return the last four digits of a phone number

${subString(5551234567, 6, 9)} returns 4567

Formatting Rules for Expression Syntax

When you're creating robot actions or robot resources, you can enter expression syntax into many fields. You must use the correct syntax for each expression.

General Formatting Rules

Some general rules apply to all expressions.

Guideline More information

Format all expressions using the following syntax: ${}

Enclose the entirety of every expression within curly brackets. For example:

${toString($VARIABLE.CurrentInvoice[InvoiceAmount]) == $VARIABLE.InvAmt && $VARIABLE.CurrentInvoice[SupplierName] ==$VARIABLE.SuppName}

Enclose all literal strings in quotation marks: ""

A literal string is any straight text that you type. For example:

${"https://www.mycompany.com/"}

You can use literal numbers but not exponents

Supported values:

  • 1, -1, and +1
  • 1.56, -1.56 and +1.56

Not supported values:

  • 1e2
  • 2^2

Expect that the order of operations follows globally established rules of precedence

For example, the expressions on either side of a logical operator are evaluated before the logical operator is evaluated.

Formatting Rules for Placeholder Values

Each placeholder value, such as a variable, robot connection, or input and output property, has its own formatting rules for expression syntax.

Value Format

Input Input properties

Format for an input property

${INPUT.input_property_name}

where:

  • input_property_name is the name of the input property.

Format for a data type property on an input property

Use this format when you base an input property on a custom data type with one or more properties, and you need to refer to one of the data type properties.

  • Option 1: ${INPUT.input_property_name[property_name]}

    You can include spaces in the [property_name] value.

  • Option 2: ${INPUT.input_property_name.property_name}

    No spaces are allowed in the property_name value, so you can use this option only if the data type's property has no spaces in its name.

where:

  • input_property_name is the name of the input property.

  • property_name is the name of the data type property that the input property is based upon.

Note: Inputs properties can be nested. Follow the same formatting rules for these nested properties. For example:

  • ${INPUT.input_property_name[property_name][property_name][property_name]}

  • ${INPUT.input_property_name.property_name.property_name.property_name}

Output Output properties

Format for an output property

${OUTPUT.output_property_name}

where:

  • output_property_name is the name of the output property.

Format for a data type property on an output property

Use this format when you base an output property on a custom data type with one or more properties, and you need to refer to one of the data type properties.

  • Option 1: ${OUTPUT.output_property_name[property_name]}

    You can include spaces in the [property_name] value.

  • Option 2: ${OUTPUT.output_property_name.property_name}

    No spaces are allowed in the property_name value, so you can use this option only if the data type's property has no spaces in its name.

where:

  • output_property_name is the name of the property of the output.

  • property_name is the name of the data type property that the output property is based upon.

Note: Output properties can be nested. Follow the same formatting rules for these nested properties. For example:

  • ${OUTPUT.output_property_name[property_name][property_name][property_name]}

  • ${OUTPUT.output_property_name.property_name.property_name.property_name}

Page states Page states

${pageState("page_state_name")}

where:

  • page_state_name is the name of the page state

Robot connections Robot connections

${CONNECTION.robot_connection_name.property}

where:

  • robot_connection_name is the name of the robot connection

  • property is the name of the property in the robot connection

Target a page element Targets

${TARGET.target_name}

where:

  • target_name is the name of the target.

Variables Variables

Format for a variable

${VARIABLE.variable_name}

where:

  • variable_name is the name of the variable.

Format for a data type property on a variable

Use this format when you base a variable on a custom data type with one or more properties, and you need to refer to one of the properties.

  • Option 1: ${VARIABLE.variable_name[property_name]}

    You can include spaces in the [property_name] value.

  • Option 2: ${VARIABLE.variable_name.property_name}

    No spaces are allowed in the property_name value, so you can use this option only if the data type's property has no spaces in its name.

where:

  • variable_name is the name of the variable.

  • property_name is the name of the property of the data type that the variable is based upon.

Note: Variables can have nested properties. Follow the same formatting rules for these nested properties. For example:

  • ${VARIABLE.variable_name[property_name][property_name][property_name]}

  • ${VARIABLE.variable_name.property_name.property_name.property_name}

When to Convert a String to a Number

When you use the get text action to obtain a value from an application, Oracle Integration stores the value as a string. If you want to perform a numeric function on the value, such as adding it to another number or comparing it to another number, you must first convert the value to a number.

If you don't convert the value to a number, the numeric function won't work as expected.

Use the toNumber function to convert a string to a number. See Functions.