Workflow Expression Builder

 

 In this article: 

Overview	Basic overview of the Workflow Expression Builder
Accessing Data	How to access other activity data using the expression builder
Shortcuts	Shortcuts available to the expression builder
String Concatenation	How to perform string concatenation
Arithmetic Operations	The various arithmetic operations available to the expression builder
Logical Operators	Methods for adding logic to expressions
String Manipulation	Functions available for manipulating text strings
Date/Time Functions	Functions available for working with date and time objects
Important Considerations	Items to be aware of or to pay particular attention to

 

Overview

The workflow expression builder is an input window that appears when entering data into the runtime expression field of any accessible property in the workflow designer.

It allows for dynamic data to be entered at design time that produces different results at runtime, depending on the criteria of the expression, whether that's based on the execution of a previous activity, the result of a built-in function, some calculation etc.

The expression builder can be accessed by clicking on the small ellipse (...) button inside the runtime expression of any built-in property. If a built-in property has NA in the box and no ellipse button then runtime data is not available for that property, either the property is read-only, it's an output property or it will only accept design-time data.

 

Accessing Data

To find out all possible accessible data in the expression builder you can use the keyboard combination Ctrl + Space. This will bring up a list of all available activities, shortcuts and functions.

It is possible to access the data contained in any built-in or user-defined property of previous workflow activities in a workflow. These are accessed by entering <ActivityName><dot><PropertyName>. For example, in the following example, we have an EnvironmentVariable activity called GetHostname that retrieves the value of the environment variable %COMPUTERNAME%. This has an output property called VariableValue that contains that retrievd value. If we want to access that value and output it in a logger activity we would use GetHostname.VariableValue

Note: Everything within the workflow expression builder is case-sensitive.

 

Shortcuts

There are shortcuts available for certain data types. These are not functions but instead allow selection of a data type from the list of available items without having to type them.

date - selection of this brings up a date-time picker that allows selection of a date and time value.

true - this can be used in an expression to check whether a condition is true.
Example: GetFileInformation.IsFolder  - returns true if the specified file/folder is a folder 

false - this can be used in an expression to check whether a condition is false.
Example: GetFileInformation.IsFolder  - returns false if the specified file/folder is NOT a folder

null - this can be used in an expression to check whether the value of a property is null (empty/no value)
Example: GetFileInformation.NameOfFile = null - checks whether the name of the specified file is null, would happen if the file specified does not exist.

 

String Concatenation

String concatenation is used for joining multiple text strings together and can be used for joining text with property values. Strings are joined using the plus (+) sign. An example of how this can be used is shown below where the results of a registry read activity is joined to a text string that describes the data being brought out:

In this example, we are getting the data of the registry value HKLM\Software\Adaptiva\Client\client_data_manager.client_id and then using a logger activity to output:

"The Client ID is: " + RegRead.ValueString

If run on a client with a client ID of 4126 then this would say The Client ID is: 4126.

Note that when joining a property value with some arbitrary text, the text string must be enclosed in double-quotes (" "). The plus sign (+) acts as a join between the text and the property value.

 

Arithmetic Operations

When working with numeric values, the expression builder can be used to perform basic arithmetic operations. These include addition (+), subtraction (-), multiplication (*) and division (/).

When combining these together, standard order of operations rules apply and parentheses can be used to modify the order of operations. 

Addition (+) - To add two numbers together, use a plus (+) sign.
Example: 4 + 12
Result: 16

Subtraction (-) - To subtract one number from another, use a minus (-) sign.
Example: 12 - 4
Result: 8

Multiplication (*) - To multiple one number with another, use an asterisk (*) sign.
Example: 4 * 12
Result: 48

Division (/) - To divide one number by another, use a forward-slash (/) sign.
Example: 12/4
Result: 3

Combining - To combine these, use parentheses to define order of operation.
Example: (12+4)*(12-4)
Result: (16)*(8)
Result: 128

 

Logical Operators

Sometimes it's necessary to add logic to an expression, for example when evaluating the result of an activity. In such cases, it may be necessary to evaluate more than one condition. In these cases an AND (&) statement or an OR (|) statement can be used.

AND (&) - The ampersand (&) character is used for a simple AND statement. This evaluates both sides of the condition and exits true if both sides are true. If either side is false, it exits false.

AND (&&) - A double-ampersand (&&) is used for a conditional AND statement. This evaluates the left side of the condition and then only evaluates the right side of the condition if the left is true. If the left is false then it exits false without evaluating the right. If the left is true and right is true then it exits true. If the left is true and right is false, it exits false.

OR (|) - The vertical-line (|) character is used for a simple OR statement. This evaluates both sides of the condition and exits true if either side is true. If both sides are false, it exits false.

OR (||) - A double-vertical-line (||) is used for a conditional OR statement. This evaluates the left side of the condition and then only evaluates the right side of the condition if the left is false. If the left is true then it exits true without evaluating the right. If the left is false and the right is true then it exits true. If both the left and right and false then it exits false.

 

String Manipulation

The expression builder supports multiple functions for modifying or obtaining data from text strings.

The following built-in functions are supported:

CharAt
Usage: CharAt(TEXT input, WHOLE_NUMBER index) - TEXT
Description: Returns the character at a specific position in the string.
Example Expression: CharAt("Hello World", 1)
Example Result: e
Notes: CharAt is zero-indexed meaning the first character is at position 0. Therefore the character in "Hello World" at position 1 is the e.

CompareTo
Usage: CompareTo(TEXT input, TEXT anotherText) - WHOLE_NUMBER
Description: Compares one text string with another and returns 0 if they match.
Example Expression: CompareTo("Hello World", "Hello World")
Example Result: 0

EndsWith
Usage: EndsWith(TEXT input, TEXT suffix) - BOOLEAN
Description: Returns true if the specified input text ends with the specified suffix.
Example Expression: EndsWith("Hello World", "rld")
Example Result: true

IndexOf
Usage: IndexOf(TEXT input, TEXT indexText) - WHOLE_NUMBER
Description: Returns the position within the input string where the specified indexText is found
Example Expression: IndexOf("Hello World", "or")
Example Result: 7
Notes: IndexOf is zero-indexed meaning the first character is at position 0. Therefore the position in "Hello World" that "or" was found is at position 7.
If the indexText does not exist within the input text, the return value is -1

Length
Usage: Length(TEXT input) - WHOLE_NUMBER
Description: Returns the number of characters in the input string, including spaces.
Example Expression: Length("Hello World")
Example Result: 11

MatchesRegex
Usage: MatchesRegex(TEXT input, TEXT regex) - BOOLEAN
Description: Returns true if the specified input string matches the specified regular expression.
Example Expression: MatchesRegex("Hello World", ".el{2}o\\s.*")
Example Result: true
Notes: Beware of escape characters. In the expression builder, the backslash (\) character is an escape character, so to use a backslash in the regex, it must be substituted with a double-backslash.
Note that because the regex is a string, it too must be enclosed in double-quotes (" ").

Replace
Usage: Replace(TEXT input, TEXT regex, TEXT replacementText) - TEXT
Description: Replaces the first instance of a regular expression match of regex within the input text with the specified replacementText.
Example Expression: Replace("Hello World", "el{2}o", "ey there")
Example Result: "Hey there World"

StartsWith
Usage: StartsWith(TEXT input, TEXT prefix) - BOOLEAN
Description: Returns true if the input string starts with the specified prefix.
Example Expression: StartsWith("Hello World", "Hello")
Example Result: true

Contains
Usage: Contains(TEXT input, TEXT subText) - BOOLEAN
Description: Returns true if the input string contains the specified subText string.
Example Expression: Contains("Hello World", "o W")
Example Result: true
Notes: The comparison is case sensitive, so "Hello" will not match with "hello".

Lowercase
Usage: Lowercase(TEXT input) - TEXT
Description: Converts the specified input string into all lowercase
Example Expression: Lowercase("hello world")
Example Result: "hello world"

Uppercase
Usage: Uppercase(TEXT input) - TEXT
Description: Converts the specified input string into all uppercase
Example Expression: Uppercase("Hello World")
Example Result: "HELLO WORLD"

Trim
Usage: Trim(TEXT input) - TEXT
Description: Removes any leading or trailing white space characters from the input string
Example Expression: Trim("   Hello World   ")
Example Result: "Hello World"

Substring
Usage: Substring(TEXT input, WHOLE_NUMBER startIndex, WHOLE_NUMBER endIndex) - TEXT
Description: Returns a text string from the specified position within the input string
Example Expression: Substring("Hello World", 1, 5)
Example Result: ello
Notes: The startIndex of substring is zero-indexed meaning the first character is at position 0. The endIndex represents the index after the character to be captured. Therefore the character in "Hello World" at position 1 is the e and the character just before position 5 is the o.

EqualIgnoreCase
Usage: EqualIgnoreCase(TEXT input1, TEXT input2) - BOOLEAN
Description: Returns whether the text string in input1 matches the text string in input2 regardless of their character casing.
Example Expression: EqualIgnoreCase("Hello World", "hElLo WoRlD")
Example Result: true

 

Date/Time Functions

The expression builder supports multiple functions for working with Date/Time objects. When entering a date/time into a DATE field, it's possible to use either an existing DATE object (e.g. SystemTime.LocalTime) or type in/select a date using the date shortcut. When using the date shortcut or typing in a date/time it needs to be surrounded by single quotes (' ').

The following built-in functions are supported:

GetYear
Usage: GetYear(DATE inputDate) - WHOLE_NUMBER
Description: Retrieves the year value from the specified inputDate
Example Expression: GetYear('1:15:30.000 PM, Tue, Apr 10, 2018')
Example Result: 2018

GetMonth
Usage: GetMonth(DATE inputDate) - WHOLE_NUMBER
Description: Retrieves the month value from the specified inputDate
Example Expression: GetMonth('1:15:30.000 PM, Tue, Apr 10, 2018')
Example Result: 4

GetDate
Usage: GetDate(DATE inputDate) - WHOLE_NUMBER
Description: Retrieves the day value from the specified inputDate
Example Expression: GetDate('1:15:30.000 PM, Tue, Apr 10, 2018')
Example Result: 10

GetHours
Usage: GetHours(DATE inputDate) - WHOLE_NUMBER
Description: Retrieves the hour value from the specified inputDate
Example Expression: GetHours('1:15:30.000 PM, Tue, Apr 10, 2018')
Example Result: 13

GetMinutes
Usage: GetMinutes(DATE inputDate) - WHOLE_NUMBER
Description: Retrieves the minute value from the specified inputDate
Example Expression: GetMinutes('1:15:30.000 PM, Tue, Apr 10, 2018')
Example Result: 15

GetSeconds
Usage: GetSeconds(DATE inputDate) - WHOLE_NUMBER
Description: Retrieves the second value from the specified inputDate
Example Expression: GetSeconds('1:15:30.000 PM, Tue, Apr 10, 2018')
Example Result: 30

GetTimeInMs
Usage: GetTimeInMs(DATE inputDate) - WHOLE_NUMBER
Description: Returns the current time represented in milliseconds (in EPOCH format - the time since Jan 1st 1970 00:00:00 UTC)
Example Expression: GetTimeInMs('1:15:30.000 PM, Tue, Apr 10, 2018')
Example Result: 1523362530000

GetDayOfWeek
Usage: GetDayOfWeek(DATE inputDate) - WHOLE_NUMBER
Description: Returns the day of the week of the specified inputDate
Example Expression: GetDayOfWeek('1:15:30.000 PM, Tue, Apr 10, 2018')
Example Result: 3
Notes: The week starts on a Sunday. Sunday=1, Monday=2, Tuesday=3 etc.

GetDayOfWeekInMonth
Usage: GetDayOfWeekInMonth(DATE inputDate) - WHOLE_NUMBER
Description: Returns the position in the month of the day of the inputDate. For example, if the inputDate was the 2nd Wednesday of the month, it would return 2, if it was the 4th Monday of the month it would return 4, if it was the 1st Saturday of the month it would return 1 etc.
Example Expression: GetDayOfWeekInMonth('1:15:30.000 PM, Tue, Apr 10, 2018')
Example Result: 2

GetDayOfMonth
Usage: GetDayOfMonth(DATE inputDate) - WHOLE_NUMBER
Description: Returns the day of the month for the specified inputDate
Example Expression: GetDayOfMonth('1:15:30.000 PM, Tue, Apr 10, 2018')
Example Result: 10

GetDayOfYear
Usage: GetDayOfYear(DATE inputDate) - WHOLE_NUMBER
Description: Returns the day of the year for the specified inputDate
Example Expression: GetDayOfYear('1:15:30.000 PM, Tue, Apr 10, 2018')
Example Result: 100

GetWeekOfMonth
Usage: GetWeekOfMonth(DATE inputDate) - WHOLE_NUMBER
Description: Returns the week of the month for the specified inputDate
Example Expression: GetWeekOfMonth('1:15:30.000 PM, Tue, Apr 10, 2018')
Example Result: 2

GetWeekOfYear
Usage: GetWeekOfYear(DATE inputDate) - WHOLE_NUMBER
Description: Returns the week of the year for the specified inputDate
Example Expression: GetWeekOfYear('1:15:30.000 PM, Tue, Apr 10, 2018')
Example Result: 15

SetYear
Usage: SetYear(DATE inputDate, WHOLE_NUMBER year) - DATE
Description: Changes the year in the specified inputDate and adjusts the other date values accordingly.
Example Expression: SetYear('1:15:30.000 PM, Tue, Apr 10 2018', 2022)
Example Result: '1:15:30.000 PM, Sun, Apr 10, 2022')

SetMonth
Usage: SetMonth(DATE inputDate, WHOLE_NUMBER month) - DATE
Description: Changes the month in the specified inputDate and adjusts the other date values accordingly.
Example Expression: SetMonth('1:15:30.000 PM, Tue, Apr 10, 2018', 11)
Example Result: '1:15:30.000 PM, Mon, Dec 10, 2018'
Notes: January starts at 0, so December is 11.

SetDate
Usage: SetDate(DATE inputDate, WHOLE_NUMBER date) - DATE
Description: Changes the day in the specified inputDate and adjusts the other date values accordingly.
Example Expression: SetDate('1:15:30.000 PM, Tue, Apr 10, 2018', 14)
Example Result: '1:15:30.000 PM, Sat, Apr 14, 2018'

SetHours
Usage: SetHours(DATE inputDate, WHOLE_NUMBER hours) - DATE
Description: Changes the hour in the specified inputDate and adjusts the other date values accordingly.
Example Expression: SetHours('1:15:30.000 PM, Tue, Apr 10, 2018', 8)
Example Result: '8:15:30.000 PM, Tue, Apr 10, 2018'

SetMinutes
Usage: SetMinutes(DATE inputDate, WHOLE_NUMBER minutes) - DATE
Description: Changes the minute in the specified inputDate and adjusts the other date values accordingly.
Example Expression: SetMinutes('1:15:30.000 PM, Tue, Apr 10, 2018', 18)
Example Result: '1:18:30.000 PM, Tue, Apr 10, 2018'

SetSeconds
Usage: SetSeconds(DATE inputDate, WHOLE_NUMBER seconds) - DATE
Description: Changes the seconds in the specified inputDate and adjusts the other date values accordingly.
Example Expression: SetSeconds('1:15:30.000 PM, Tue, Apr 10, 2018', 44)
Example Result: '1:15:44.000 PM, Tue, Apr 10, 2018'

NewDate
Usage: NewDate(WHOLE_NUMBER year, WHOLE_NUMBER month, WHOLE_NUMBER date, WHOLE_NUMBER hours, WHOLE_NUMBER minutes, WHOLE_NUMBER seconds) - DATE
Description: Returns a new date/time object representing the specified date
Example Expression: NewDate(2018,4,10,13,15,30)
Example Result: '1:15:30.000 PM, Tue, Apr 10, 2018'

AfterDate
Usage: AfterDate(DATE inputDate1, DATE when) - BOOLEAN
Description: Returns true if the inputDate1 is after the when date
Example Expression: AfterDate('1:15:30.000 PM, Tue, Apr 10, 2018', '1:15:30.000 PM, Mon, Apr 2, 2018')
Example Result: true

BeforeDate
Usage: BeforeDate(DATE inputDate1, DATE when) - BOOLEAN
Description: Returns true if the inputDate1 is before the when date
Example Expression: BeforeDate('1:15:30.000 PM, Tue, Apr 10, 2018', '1:15:30.000 PM, Wed, Apr 18, 2018')
Example Result: true

CompareDate
Usage: CompareDate(DATE inputDate, DATE anotherDate) - WHOLE_NUMBER
Description: Returns 0 if the inputDate matches the anotherDate
Example Expression: CompareDate('1:15:30.000 PM, Tue, Apr 10, 2018', '1:15:30.000 PM, Tue, Apr 10, 2018')
Example Result: true

FormatDate
Usage: FormatDate(DATE inputDate, TEXT dateformat) - TEXT
Description: Converts the inputDate into the specified dateformat
Example Expression: FormatDate('1:15:30.000 PM, Tue, Apr 10, 2018', "yyyy-MM-dd HH:mm:ss")
Example Result: "2018-04-10 13:15:30"

ParseDate
Usage: ParseDate(TEXT inputDate, TEXT dateformat) - DATE
Description: Takes an inputDate as a text string and converts it into a date/time object using the specified dateformat string.
Example Expression: ParseDate("2018-04-10 13:15:30", "yyyy-MM-dd HH:mm:ss")
Example Result: '1:15:30.000 PM, Tue, Apr 10, 2018'

AddYear
Usage: AddYear(DATE inputDate, WHOLE_NUMBER year) - DATE
Description: Adds the specified number of years specified in year to the specified inputDate
Example Expression: AddYear('1:15:30.000 PM, Tue, Apr 10, 2018',2)
Example Result: '1:15:30.000 PM, Tue, Apr 10, 2020'

AddMonth
Usage: AddMonth(DATE inputDate, WHOLE_NUMBER month) - DATE)
Description: Adds the specified number of months specified in month to the specified inputDate
Example Expression: AddMonth('1:15:30.000 PM, Tue, Apr 10, 2018',4)
Example Result: '1:15:30.000 PM, Fri, Aug 10, 2018'

AddDate
Usage: AddDate(DATE inputDate, WHOLE_NUMBER date) - DATE)
Description: Adds the specified number of days specified in date to the specified inputDate
Example Expression: AddDate('1:15:30.000 PM, Tue, Apr 10, 2018',10)
Example Result: '1:15:30.000 PM, Fri, Apr 20, 2018'

AddHours
Usage: AddHours(DATE inputDate, WHOLE_NUMBER hours) - DATE)
Description: Adds the specified number of hours to the specified inputDate
Example Expression: AddHours('1:15:30.000 PM, Tue, Apr 10, 2018',5)
Example Result: '6:15:30.000 PM, Tue, Apr 10, 2018'

AddMinutes
Usage: AddMinutes(DATE inputDate, WHOLE_NUMBER minutes) - DATE)
Description: Adds the specified number of minutes to the specified inputDate
Example Expression: AddMinutes('1:15:30.000 PM, Tue, Apr 10, 2018',3)
Example Result: '1:18:30.000 PM, Tue, Apr 10, 2018'

AddSeconds
Usage: AddSeconds(DATE inputDate, WHOLE_NUMBER seconds) - DATE)
Description: Adds the specified number of seconds to the specified inputDate
Example Expression: AddSeconds('1:15:30.000 PM, Tue, Apr 10, 2018',20)
Example Result: '1:15:50.000 PM, Tue, Apr 10, 2018'

RollYear
Usage: RollYear(DATE inputDate, WHOLE_NUMBER year) - DATE)
Description: Adds the specified number of years specified in year to the inputDate.
Example Expression: RollYear('1:15:30.000 PM, Tue, Apr 10, 2018',2)
Example Result: '1:15:30.000 PM, Fri, Apr 10, 2020'
Notes: Because Year is the highest value, RollYear does the same thing as AddYear.

RollMonth
Usage: RollMonth(DATE inputDate, WHOLE_NUMBER month) - DATE)
Description: Adds the specified number of months specified in month to the inputDate but without rolling over years.
Example Expression: RollMonth('1:15:30.000 PM, Tue, Apr 10, 2018',10)
Example Result: '1:15:30.000 PM, Sat, Feb 10, 2018'

RollDate
Usage: RollDate(DATE inputDate, WHOLE_NUMBER date) - DATE)
Description: Adds the specified number of days specified in date to the inputDate but without rolling over months.
Example Expression: RollDate('1:15:30.000 PM, Tue, Apr 10, 2018',22)
Example Result: '1:15:30.000 PM, Mon, Apr 02, 2018'

RollHours
Usage: RollHours(DATE inputDate, WHOLE_NUMBER hours) - DATE)
Description: Adds the specified number of hours to the inputDate but without rolling over days.
Example Expression: RollHours('1:15:30.000 PM, Tue, Apr 10, 2018',15)
Example Result: '4:15:30.000 AM, Tue, Apr 10, 2018'

RollMinutes
Usage: RollMinutes(DATE inputDate, WHOLE_NUMBER minutes) - DATE)
Description: Adds the specified number of minutes to the inputDate but without rolling over hours.
Example Expression: RollMinutes('1:15:30.000 PM, Tue, Apr 10, 2018',50)
Example Result: '1:05:30.000 PM, Tue, Apr 10, 2018'

RollSeconds
Usage: RollSeconds(DATE inputDate, WHOLE_NUMBER seconds) - DATE)
Description: Adds the specified number of seconds to the inputDate but without rolling over minutes.
Example Expression: RollSeconds('1:15:30.000 PM, Tue, Apr 10, 2018',55)
Example Result: '1:15:25.000 PM, Tue, Apr 10, 2018'

 

Important Considerations

• Always check the dataType listed in the expression builder window. The expression that gets built should always be of the same data type to that which is expected.
  
  
• Always enclose text strings in double-quotes (" "), even when concatenating them with property values. DATE values should be enclosed in single quotes (' ') unless referencing a DATE object. Integers (WHOLE_NUMBER), decimal numbers (FRACTIONAL_NUMBER) and booleans should not be enclosed in any quotes.
• Use parentheses for enclosing nested functions or for changing the order of operation for arithmetic operations.