Expression language methods for actions

now(String timezone)

The now() method returns the current date and time for a specified time zone, in the format yyyy-MM-dd HH:mm:ss 'GMT'XXX:

now('Australia/Sydney').

In this example, if the current date and time is 2021-11-26 11:41:00, the returned string is 2021-11-26 21:41:00 GMT+10.00 or 2021-11-26 21:41:00 GMT+11.00 depending on Daylight Saving Time.

The output string format change is applicable to date and time calculation methods as well. For example, if the <date> string used is in the format yyyy-MM-dd HH:mm:ss, such as when you use the method today(), then the output is in the same format (yyyy-MM-dd HH:mm:ss). However, if the <date> string is in the format yyyy-MM-dd HH:mm:ss 'GMT'XXX, such as when you use the method now(), then the output is in the format yyyy-MM-dd HH:mm:ss 'GMT'XXX.

.reformatDateTime(String format)

Formats date and time strings for output. The parameter is a format string that specifies how the date or time value is formatted. The format string must be specified by using the Java SimpleDateFormat syntax.

This method returns a string that is formatted according to the specified format:

• MM/dd/yyyy for 12/31/2016
• h a for 10pm

To return the day of the week:

• EEEE for Tuesday
• E for Tue
• u for day index (1 = Monday, ..., 7 = Sunday)

For example, this expression returns the value 17:30:00 as 5:30 PM:

${system_current_date}.reformatDateTime('h:mm a')

If the input string includes only a time, the default date 1970-01-01 is used in the output. If the input string includes only a date, the default time 12 AM (00:00) is used.

.before(String date/time)

• Determines whether a date and time value is before the specified date and time argument, as in this example:

${system_current_date}.before('2021-11-19')

You can compare a date with another date, or a time with another time. You can also compare a time with a date and time value, in which case the date is ignored and only the times are compared. Any other comparisons of mismatched values (for example, comparing a date with a time) return false, an exception is logged in output.debug.log_messages (which you can see in the assistant preview or in API responses).

.after(String date/time)

• Determines whether the date and time value is after the date and time argument.

.sameMoment(String date/time)

• Determines whether the date and time value is the same as the date and time argument.

.sameOrAfter(String date/time)

• Determines whether the date and time value is after or the same as the date and time argument.
• Analogous to .after().

.sameOrBefore(String date/time)

• Determines whether the date and time value is before or the same as the date and time argument.

Date and time calculations

Use the following methods to calculate a date.

where <date> is specified in the format yyyy-MM-dd or yyyy-MM-dd HH:mm:ss.

For example, to get tomorrow's date, specify the following expression:

${system_current_date}.plusDays(1)

Use the following methods to calculate a time.

where <time> is specified in the format HH:mm:ss.

For example, to get the time one hour from now, specify the following expression:

 now().plusHours(1)  

Working with time spans

To show a response based on whether today's date falls within a certain time span, you can use a combination of time-related methods. For example, if you run a special offer during the holiday season every year, you might want to check whether today's date falls between November 25 and December 24 of this year.

First, define the dates of interest as session variables. In the following start and end date session variable expressions, the date is being constructed by concatenating the dynamic current year value with hardcoded month and day values:

start_date = now().reformatDateTime('Y') + '-12-24'
end_date = now().reformatDateTime('Y') + '-11-25'

Then, in a step condition, you can indicate that you want to show the response only if the current date falls between the start and end dates that you defined as session variables:

now().after(${start_date}) && now().before(${end_date})

java.util.Date support

In addition to the built-in methods, you can use standard methods of the java.util.Date class.

For example, to get the date of the day that falls a week from today, you can use the following syntax:

new Date(new Date().getTime() + (7 * (24*60*60*1000L)))

This expression first gets the current date in milliseconds (since January 1, 1970, 00:00:00 GMT). It also calculates the number of milliseconds in 7 days ((24*60*60*1000L) represents one day in milliseconds). It then adds 7 days to the current date. The result is the full date of the day that falls a week from today (for example, Fri Jan 26 16:30:37 UTC 2018).

toDouble()

Converts the object or field to the Double number type. You can call this method on any object or field. If the conversion fails, null is returned.

toInt()

Converts the object or field to the Integer number type. You can call this method on any object or field. If the conversion fails, null is returned.

toLong()

Converts the object or field to the Long number type. You can call this method on any object or field. If the conversion fails, null is returned.

To specify a Long number type in a SpEL expression, you must append an L to the number to identify it as such (for example, 5000000000L). This syntax is required for any numbers that do not fit into the 32-bit Integer type. Numbers that are greater than 2^31 (2,147,483,648) or less than -2^31 (-2,147,483,648) are considered Long number types. Long number types have a minimum value of -2^63 and a maximum value of 2^63-1 (or 9,223,372,036,854,775,807).

Standard math

Use SpEL expressions to define standard math equations, where the operators are represented by using these symbols:

java.lang.Math()

You can use the functions of the java.lang.Math class to perform basic numeric operations.

You can use the Class methods, including:

• max():

  T(Math).max(${step_297},${step_569})
  

• min():

  T(Math).min(${step_297},${step_569})
  

• pow():

  T(Math).pow(${step_297}.toDouble(),2.toDouble())
  

See the java.lang.Math reference documentation for information about other methods.

java.util.Random()

Returns a random number. You can use any of the following syntax options:

• To return a random Boolean value (true or false), use new Random().nextBoolean().
• To return a random double number between 0 (included) and 1 (excluded), use new Random().nextDouble()
• To return a random integer between 0 (included) and a number you specify, use new Random().nextInt(_n_), where n is 1 greater than the top of the number range you want. For example, if you want to return a random number between 0 and 10, specify new Random().nextInt(11).
• To return a random integer from the full integer value range (-2147483648 to 2147483648), use new Random().nextInt().

For example, you might create step that is executed only for a randomly selected subset of customers. The following step condition would mean that the step has a 50% chance of executing:

new Random().nextInt(2) == 1

See the java.util.Random reference documentation for information about other methods.

You can also use standard methods of the following classes:

• java.lang.Byte
• java.lang.Integer
• java.lang.Long
• java.lang.Double
• java.lang.Short
• java.lang.Float

String.append(Object)

This method appends an input object (as a string) to a string, and returns a modified string.

${step_297}.append('next text')

String.contains(String)

This method returns true if the action variable or session variable contains a substring, which is useful in conditions.

${step_297}.contains('Yes')

String.endsWith(String)

This method returns true if the string ends with the input substring.

${step_297}.endsWith('?')

String.equals(String)

This method returns true if the specified string equals the action variable or session variable.

${step_297}.equals('Yes')

String.equalsIgnoreCase(String)

This method returns true if the specified string equals the action variable or session variable irrespective of case.

${step_297}.equalsIgnoreCase('Yes')

String.extract(String regexp, Integer groupIndex)

This method returns a string from the input that matches the specified regular expression group pattern. It returns an empty string if no match is found.

This method is designed to extract matches for different regex pattern groups, not different matches for a single regex pattern. To find different matches, see the getMatch() method.

In this example, the action variable is saving a string that matches the regex pattern group that you specify. In the expression, two regex patterns groups are defined, each one enclosed in parentheses. Inherent is a third group that is composed of the two groups. This is the first (groupIndex 0) regex group; it matches with a string that contains the full number group and text group. The second regex group (groupIndex 1) matches with the first occurrence of a number group. The third group (groupIndex 2) matches with the first occurrence of a text group after a number group.

${step_297}.extract('([\d]+)(\b [A-Za-z]+)', <n>)

If action variable contains:

Hello 123 this is 456.

the results are as follows:

• When <n>=0, the value is 123 this.
• When <n>=1, the value is 123.
• When <n>=2, the value is this.

String.find(String regexp)

This method returns true if any segment of the string matches the input regular expression. You can call this method against a JSONArray or JSONObject element, and it converts the array or object to a string before it makes the comparison.

For example, if the action variable ${step_297} collects the string Hello 123456, then the following expression returns true:

${step_297}.find('^[^\d]*[\d]{6}[^\d]*$')

The condition is true because the numeric portion of the input text matches the regular expression ^[^\d]*[\d]{6}[^\d]*$.

String.getMatch(String regexp, Integer matchIndex)

This method returns a string that matches the occurrence of the specified regular expression pattern. This method returns an empty string if no match is found.

As matches are found, they are added to what you can think of as an array of matches. Because the array element count starts at 0, if you want to return the third match, you would specify 2 as the matchIndex value. For example, if you enter a text string with three words that match the specified pattern, you can return the first, second, or third match only by specifying its index value.

For example, the following example is looking for a group of numbers in an action variable.

${step_297}.getMatch('([\d]+)', 1)

If the action variable ${step_297} contains the string hello 123 i said 456 and 8910, this expression returns 456.

String.isEmpty()

This method returns true if the string is an empty string, but not null, as in this example:

${step_297}.isEmpty()

String.length()

This method returns the character length of the string, as in this example:

${step_297}.length()

If the action variable ${step_297} contains the string Hello, this expression returns 5.

String.matches(String regexp)

This method returns true if the string matches the input regular expression, as in the example:

${step_297}.matches('^Hello$')

If the action variable ${step_297} contains the string Hello, this expression evaluates to true.

String.startsWith(String)

This method returns true if the string starts with the specified substring, as in this example:

${step_297}.startsWith('What')

If the action variable ${step_297} contains the string What is your name?, this expression returns true.

String.substring(Integer beginIndex, Integer endIndex)

This method returns a substring beginning with the character at beginIndex and ending with the character before endIndex. (The endIndex character itself is not included in the substring.) The index values are zero-based, so the first character in the string is at index 0.

This example returns a substring that begins at index 5 (which is the sixth character), and continuing to the end of the string:

${step_297}.substring(5, ${step_297}.length())

If the action variable ${step_297} contains the string This is a string., this expression returns is a string.

String.toJson()

This method parses a string that contains JSON data and returns a JSON object or array, as in this example:

${json_var}.toJson()

If the session variable ${json_var} contains the following string:

"{ \"firstname\": \"John\", \"lastname\": \"Doe\" }"

the toJson() method returns the following object:

{
  "firstname": "John",
  "lastname": "Doe"
}

String.toLowerCase()

This method returns the specified string that is converted to lowercase letters, as in this example:

${step_297}.toLowerCase()

If the action variable ${step_297} contains the string This is A DOG!, this expression returns the string this is a dog!.

String.toUpperCase()

This method returns the original string that is converted to uppercase letters, as in this example:

${step_297}.toUpperCase()

If the action variable ${step_297} contains the string hi there, this method returns the string HI THERE.

String.trim()

This method trims any spaces at the beginning and end of a string and returns the modified string, as in this example:

${step_297}.trim()

If the action variable ${step_297} contains the string something is here , this method returns the string something is here.

java.lang.String support

In addition to the built-in methods, you can use standard methods of the java.lang.String class.

T(java.lang.String).format('%d + %d equals %d', 1, 1, 2)

T(String).format('%.2f',${step_297})

Array.add(value...)

This method adds one or more new values to the array and returns true if the operation is successful.

${Items}.add('four', 'five')

If Items is ['one', 'two', 'three'], this example updates it in place to become ['one', 'two', 'three', 'four', 'five'].

Array.addAll(Array array)

This method adds one array to another and returns null.

${Items}.addAll(${New_items})

If Items is ['one', 'two', 'three'] and New_items is ['four', 'five', 'six'], this example updates Items in place to become ['one', 'two', 'three', 'four', 'five', 'six'].

Array.append(value...)

This method appends one or more new values to the array and returns the result as a new array. The original array is not modified.

${Items}.append('four', 'five')

If Items is ['one', 'two', 'three'], this example returns the new array ['one', 'two', 'three', 'four', 'five'].

Array.clear()

This method removes all values from the array and returns null.

${Items}.clear()

After this expression is evaluated, Items is an empty array ([]).

Array.contains(value)

This method returns true if the array contains an item that is exactly equal to the input value. The specified value can be a string or a number.

${Items}.contains(123)

If Items is [123, 456, 789], this example returns true.

Array.containsIgnoreCase(value)

This method returns true if the array contains an item that is equal to the input value. Strings are matched regardless of whether the value is specified in uppercase or lowercase letters. The specified value can be a string or a number.

${Items}.contains('two')

This example returns true if the Items array contains any capitalization of the string two (for example, TWO or Two would also match).

Array.filter(temp_var, "temp_var.property operator comparison_value")

Filters an array by comparing each array element to a value you specify, returning a new array that contains only the matching elements.

The filter expression consists of the following values:

• temp_var: An arbitrary name for a temporary variable that is used to hold each array element as it is evaluated. For example, if the original array contains objects that describe cities, you might use city as the temporary variable name.

• property: The element property that you want to filter on. This must be a property of the elements in the source array. Specify the property as a property of temp_var, by using the syntax temp_var.property. For example, if latitude is a valid property name for the source elements, you might specify the property as city.latitude.

• operator: The operator to use to compare the property value to the comparison value. You can use any of the following operators:

  Supported filter operators

  Operator	Description
  ==	Is equal to
  >	Is greater than
  <	Is less than
  >=	Is greater than or equal to
  <=	Is less than or equal to
  !=	Is not equal to

• comparison_value: The value that you want to compare each array element property value to. You can specify a literal value or reference a variable.

[
   {
      "name":"Tokyo",
      "population":13988129

   },
   {
      "name":"Rome",
      "population":2860009

   },
   {
      "name":"Beijing",
      "population":21893095

   },
   {
      "name":"Paris",
      "population":2165423

   }
]

${cities}.filter("city", "city.population > 5000000")

[
   {
      "name":"Tokyo",
      "population":13988129

   },
   {
      "name":"Beijing",
      "population":21893095

   }
]

${cities}.filter("city", "city.population > ${step_123}")

Array.get(Integer index)

This method returns the item from the array that is at the specified index position. Arrays are zero-indexed, meaning that the first item in the array is at index position 0.

${Items}.get(1)

If Items is ['one', 'two', 'three'], this example returns two.

The get() method is an alternative to using brackets ([]) to retrieve an item from an array. The following example is also valid and returns the same result:

${Items}[1]

If you are using a value that is specified by a customer to choose an item from an array, you might need to subtract 1 to convert to a zero-indexed value. For example, you might use an expression like ${Items}.get(${step_123} - 1) to retrieve the intended value.

Array.getRandomItem()

This method returns a randomly chosen item from the array.

${Items}.getRandomItem()

If Items is ['one', 'two', 'three'], this example returns one, two, or three, on a random basis.

Array.indexOf(value)

This method returns the index position of the first occurrence of the input value in the array, or -1 if the array does not contain the input value. The specified value can be a string or a number.

${Items}.indexOf(`two`)

If Items is ['one', 'two', 'three'], this example returns the integer 1 (indicating the second position in the zero-indexed array).

Array.join(String delimiter)

This method joins all values in this array to a string. Values are converted to string and delimited by the input delimiter.

For example, you might use a variable that is named pizza_toppings that contains the array ["pepperoni", "ham", "mushrooms"]. The following expression converts this array into the string pepperoni, ham, mushrooms:

${toppings_array}.join(', ')

If you use that expression to define the value of a variable, you can then reference that variable in your assistant output to create a human-readable message (for example, You have selected the following toppings: pepperoni, ham, mushrooms).

JSONArray.joinToArray(template, retainDataType)

This method extracts information from each item in the array and builds a new array that is formatted according to the template you specify. The template can be a string, a JSON object, or an array. The method returns an array of strings, an array of objects, or an array of arrays, depending on the type of template.

This method is useful for formatting information as a string that you can return as part of the output of a step, or for transforming data into a different structure so you can use it with an external API.

In the template, you can reference values from the source array by using the following syntax:

%e.{property}%

where {property} represents the name of the property in the source array.

For example, suppose that your assistant stores an array that contains flight details in a session variable. The stored data might look like this:

"flights": [
      {
        "flight": "AZ1040",
        "origin": "JFK",
        "carrier": "Alitalia",
        "duration": 485,
        "destination": "FCO",
        "arrival_date": "2019-02-03",
        "arrival_time": "07:00",
        "departure_date": "2019-02-02",
        "departure_time": "16:45"
      },
      {
        "flight": "DL1710",
        "origin": "JFK",
        "carrier": "Delta",
        "duration": 379,
        "destination": "LAX",
        "arrival_date": "2019-02-02",
        "arrival_time": "10:19",
        "departure_date": "2019-02-02",
        "departure_time": "07:00"
      },
      {
        "flight": "VS4379",
        "origin": "BOS",
        "carrier": "Virgin Atlantic",
        "duration": 385,
        "destination": "LHR",
        "arrival_date": "2019-02-03",
        "arrival_time": "09:05",
        "departure_date": "2019-02-02",
        "departure_time": "21:40"
      }
    ]

To build an array of strings that describe these flights in a user-readable form, you might use the following expression:

${Flight_data}.joinToArray("Flight %e.flight% to %e.destination%", true)

This expression would return the following array of strings: ["Flight AZ1040 to FCO","Flight DL1710 to LAX","Flight VS4379 to LHR"].

The optional retainDataType parameter specifies whether the method preserves the data type of all input values in the returned array. If retainDataType is set to false or omitted, in some situations, strings in the input array might be converted to numbers in the returned array. For example, if the selected values from the input array are "1", "2", and "3", the returned array might be [ 1, 2, 3 ]. To avoid unexpected type conversions, specify true for this parameter.

<br/>Flight number: %e.flight% <br/> Airline: %e.carrier% <br/> Departure date: %e.departure_date% <br/> Departure time: %e.departure_time% <br/> Arrival time: %e.arrival_time% <br/>

${Flight_data}.joinToArray(${Template})

Flight number: AZ1040
Airline: Alitalia
Departure date: 2019-02-02
Departure time: 16:45
Arrival time: 07:00

Flight number: DL1710
Airline: Delta
Departure date: 2019-02-02
Departure time: 07:00
Arrival time: 10:19

Flight number: VS4379
Airline: Virgin Atlantic
Departure date: 2019-02-02
Departure time: 21:40
Arrival time: 09:05

{
  "departure": "Flight %e.flight% departs on %e.departure_date% at %e.departure_time%.",
  "arrival": "Flight %e.flight% arrives on %e.arrival_date% at %e.arrival_time%."
}

Array.remove(Integer index)

This method removes the item in the specified index position from the array, and returns the updated array.

${Items}.remove(1)

If Items is ['one', 'two', 'three'], this example returns ['one', 'three']. The original Items array is also modified in place.

Array.removeValue(value)

This method removes the first occurrence of the specified value from the array, and returns the updated array. The specified value can be a string or a number.

${Items}.removeValue('two')

If Items is ['one', 'two', 'three'], this example returns ['one', 'three']. The original Items array is also modified in place.

Array.set(Integer index, value)

This method replaces the item in the specified index position with the specified value, and returns the updated array.

${Items}.set(2,'five')

If Items is ['one', 'two', 'three'], this example returns ['one', 'two', 'five']. The original Items array is also modified in place.

Array.size()

This method returns the number of items in the array as an integer.

${Items}.size()

If Items is ['one', 'two', 'three'], this example returns 3.

Array.sort()

This method does an in-place sorting and returns the sorted array. The default parameter is ascending. You can specify descending to change the sort order. Any other parameter entry is ignored and a log error appears.

${Items}.sort("ascending")

The method compares numbers and strings. A number is always smaller than a string. Any other type is converted to string by default to compare.

For example:

Array.transform()

The Array.transform() method is used with the session_history variable only. You can transform the output of the variable to match a specific generative AI system.

Table: Signatures for chat formats shows signatures that you can use for the different chat formats:

If currentAction is true:

The n : true flags are not included in the output of transform.