Expression language methods

JSONArray.addAll(JSONArray)

This method appends one array to another.

For this dialog runtime context:

{
  "context": {
    "toppings_array": ["onion", "olives"],
    "more_toppings": ["mushroom","pepperoni"]
  }
}

Make this update:

{
  "context": {
    "toppings_array": "<? $toppings_array.addAll($more_toppings) ?>"
  }
}

Result: The method itself returns null. However, the first array is updated to include the values from the second array.

{
  "context": {
    "toppings_array": ["onion", "olives", "mushroom", "pepperoni"]
  }
}

JSONArray.append(object)

This method appends a new value to the JSONArray and returns the modified JSONArray.

For this Dialog runtime context:

{
  "context": {
    "toppings_array": ["onion", "olives"]
  }
}

Make this update:

{
  "context": {
    "toppings_array": "<? $toppings_array.append('ketchup', 'tomatoes') ?>"
  }
}

Result:

{
  "context": {
    "toppings_array": ["onion", "olives", "ketchup", "tomatoes"]
  }
}

JSONArray.clear()

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

Use the following expression in the output to define a field that clears an array that you saved to a context variable ($toppings_array) of its values.

{
  "output": {
    "array_eraser": "<? $toppings_array.clear() ?>"
  }
}

If you subsequently reference the $toppings_array context variable, it returns '[]' only.

JSONArray.contains(Object value)

This method returns true if the input JSONArray contains the input value.

For this Dialog runtime context which is set by a previous node or external application:

{
  "context": {
    "toppings_array": ["onion", "olives", "ham"]
  }
}

Dialog node or response condition:

$toppings_array.contains('ham')

Result: true because the array contains the element ham.

JSONArray.containsIgnoreCase(Object value)

This method returns true if the input JSONArray contains the input value, regardless of whether the value is specified in uppercase or lowercase letters.

For this Dialog runtime context which is set by a previous node or external application:

{
  "context": {
    "toppings_array": ["onion", "olives", "ham"]
  }
}

Dialog node or response condition:

$toppings_array.containsIgnoreCase('HAM')

Result: true because the array contains the element ham and the case is ignored.

JSONArray.containsIntent(String intent_name, Double min_score, [Integer top_n])

This method returns true if the intents JSONArray specifically contains the specified intent, and that intent has a confidence score that is equal to or higher than the specified minimum score. Optionally, you can specify a number to indicate that the intent must be included within that number of top elements in the array. The top_n parameter is ignored if you specify a negative number.

Returns false if the specified intent is not in the array, does not have a confidence score that is equal to or greater than the minimum confidence score, or the array index of the intent is lower than the specified index location.

The service automatically generates an intents array that lists the intents that the service detects in the input whenever user input is submitted. The array lists all intents that are detected by the service in order of highest confidence first.

You can use this method in a node condition to not only check for the presence of an intent, but to set a confidence score threshold that must be met before the node can be processed and its response returned.

For example, use the following expression in a node condition when you want to trigger the dialog node only when the following conditions are met:

• The #General_Ending intent is present.
• The confidence score of the #General_Ending intent is over 80%.
• The #General_Ending intent is one of the top 2 intents in the intents array.

intents.containsIntent("General_Ending", 0.8, 2)

JSONArray.filter(temp, "temp.property operator comparison_value")

Filters an array by comparing each array element value to a value you specify. This method is similar to a collection projection. A collection projection returns a filtered array based on a name in an array element name-value pair. The filter method returns a filtered array based on a value in an array element name-value pair.

The filter expression consists of the following values:

• temp: Name of a variable that is used temporarily as each array element is evaluated. For example, city.

• property: Element property that you want to compare to the comparison_value. Specify the property as a property of the temporary variable that you name in the first parameter. Use the syntax: temp.property. For example, if latitude is a valid element name for a name-value pair in the array, specify the property as city.latitude.

• operator: Operator to use to compare the property value to the comparison_value.

  Supported operators are:

  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: Value that you want to compare each array element property value against. To specify a value that can change depending on the user input, use a context variable or entity as the value. If you specify a value that can vary, add logic to guarantee that the comparison_value value is valid at evaluation time or an error will occur.

[
   {
      "name":"Tokyo",
      "population":9273000
   },
   {
      "name":"Rome",
      "population":2868104
   },
   {
      "name":"Beijing",
      "population":20693000
   },
   {
      "name":"Paris",
      "population":2241346
   }
]

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

[
   {
      "name":"Tokyo",
      "population":9273000
   },
   {
      "name":"Beijing",
      "population":20693000
   }
]

The cities with more than 5 million people include <?  T(String).join(", ",($cities.filter("city", "city.population > 5000000")).![name]) ?>.

$cities.filter("city", "city.population > $population_min")

[
   {
      "name":"Tokyo",
      "population":9273000
   },
   {
      "name":"Beijing",
      "population":20693000
   }
]

The cities with more than $population_min people include <?  T(String).join(", ",($cities.filter("city", "city.population > $population_min")).![name]) ?>.

$cities.filter("y", "y.name == @city")

[
   {
      "name":"Tokyo",
      "population":9273000
   }
]

The population of @city is: <? ($cities.filter("y", "y.name == @city").![population]).get(0) ?>.

JSONArray.get(Integer)

This method returns the input index from the JSONArray.

For this Dialog runtime context which is set by a previous node or external application:

{
  "context": {
    "name": "John",
    "nested": {
      "array": [ "one", "two" ]
    }
  }
}

Dialog node or response condition:

$nested.array.get(0).getAsString().contains('one')

Result: True because the nested array contains one as a value.

Response:

"output": {
  "generic" : [
    {
      "values": [
        {
        "text" : "The first item in the array is <?$nested.array.get(0)?>"
        }
      ],
      "response_type": "text",
      "selection_policy": "sequential"
    }
  ]
  }

JSONArray.getRandomItem()

This method returns a random item from the input JSONArray.

For this Dialog runtime context:

{
  "context": {
    "toppings_array": ["onion", "olives", "ham"]
  }
}

Dialog node output:

{
  "output": {
  "generic" : [
    {
      "values": [
        {
    "text": "<? $toppings_array.getRandomItem() ?> is a great choice!"
        }
      ],
      "response_type": "text",
      "selection_policy": "sequential"
    }
  ]
  }
}

Result: "ham is a great choice!" or "onion is a great choice!" or "olives is a great choice!"

Note: The resulting output text is randomly chosen.

JSONArray.indexOf(value)

This method returns the index number of the element in the array that matches the value you specify as a parameter or -1 if the value is not found in the array. The value can be a String ("School"), Integer(8), or Double (9.1). The value must be an exact match and is case sensitive.

For example, the following context variables contain arrays:

{
  "context": {
    "array1": ["Mary","Lamb","School"],
    "array2": [8,9,10],
    "array3": [8.1,9.1,10.1]
  }
}

The following expressions can be used to determine the array index at which the value is specified:

<? $array1.indexOf("Mary") ?> returns `0`
<? $array2.indexOf(9) ?> returns `1`
<? $array3.indexOf(10.1) ?> returns `2`

This method can be useful for getting the index of an element in an intents array, for example. You can apply the indexOf method to the array of intents generated each time user input is evaluated to determine the array index number of a specific intent.

intents.indexOf("General_Greetings")

If you want to know the confidence score for a specific intent, you can pass the earlier expression in as the index value to an expression with the syntax intents[index].confidence. For example:

intents[intents.indexOf("General_Greetings")].confidence

JSONArray.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 this Dialog runtime context:

{
  "context": {
    "toppings_array": ["onion", "olives", "ham"]
  }
}

Dialog node output:

{
  "output": {
  "generic" : [
    {
      "values": [
        {
    "text": "This is the array: <? $toppings_array.join(';') ?>"
        }
      ],
      "response_type": "text",
      "selection_policy": "sequential"
    }
  ]
  }
}

Result:

This is the array: onion;olives;ham;

If a user input mentions multiple toppings, and you defined an entity named @toppings that can recognize topping mentions, you could use the following expression in the response to list the toppings that were mentioned:

So, you'd like <? @toppings.values.join(',') ?>.

If you define a variable that stores multiple values in a JSON array, you can return a subset of values from the array, and then use the join() method to format them properly.

"flights_found": [
  {
    "time": "10:00",
    "flight_code": "OK123"
  },
  {
    "time": "12:30",
    "flight_code": "LH421"
  },
  {
    "time": "16:15",
    "flight_code": "TS4156"
  }
]

<? $flights_found.![flight_code] ?>

The flights that fit your criteria are:
  <? T(String).join(",", $flights_found.![flight_code]) ?>.

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 you can return as part of the output of a dialog node, 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 using the following syntax:

%e.{property}%

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

For example, suppose your assistant has stored an array containing flight details in a context 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 should preserve 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%."
}

JSONArray.remove(Integer)

This method removes the element in the index position from the JSONArray and returns the updated JSONArray.

For this Dialog runtime context:

{
  "context": {
    "toppings_array": ["onion", "olives"]
  }
}

Make this update:

{
  "context": {
    "toppings_array": "<? $toppings_array.remove(0) ?>"
  }
}

Result:

{
  "context": {
    "toppings_array": ["olives"]
  }
}

JSONArray.removeValue(object)

This method removes the first occurrence of the value from the JSONArray and returns the updated JSONArray.

For this Dialog runtime context:

{
  "context": {
    "toppings_array": ["onion", "olives"]
  }
}

Make this update:

{
  "context": {
    "toppings_array": "<? $toppings_array.removeValue('onion') ?>"
  }
}

Result:

{
  "context": {
    "toppings_array": ["olives"]
  }
}

JSONArray.set(Integer index, Object value)

This method sets the input index of the JSONArray to the input value and returns the modified JSONArray.

For this Dialog runtime context:

{
  "context": {
    "toppings_array": ["onion", "olives", "ham"]
  }
}

Dialog node output:

{
  "context": {
    "toppings_array": "<? $toppings_array.set(1,'ketchup')?>"
  }
}

Result:

{
  "context": {
    "toppings_array": ["onion", "ketchup", "ham"]
  }
}

JSONArray.size()

This method returns the size of the JSONArray as an integer.

For this Dialog runtime context:

{
  "context": {
    "toppings_array": ["onion", "olives"]
  }
}

Make this update:

{
  "context": {
    "toppings_array_size": "<? $toppings_array.size() ?>"
  }
}

Result:

{
  "context": {
    "toppings_array_size": 2
  }
}

JSONArray split(String regexp)

This method splits the input string by using the input regular expression. The result is a JSONArray of strings.

For this input:

"bananas;apples;pears"

This syntax:

{
  "context": {
    "array": "<?input.text.split(";")?>
  }
}

Results in this output:

{
  "context": {
    "array": [ "bananas", "apples", "pears" ]
  }
}

com.google.gson.JsonArray support

In addition to the built-in methods, you can use standard methods of the com.google.gson.JsonArray class.

{
  "context":{
    "answer": "<? output.answer?:new JsonArray().append('temp_value') ?>"
  }

.after(String date or time)

Determines whether the date/time value is after the date/time argument.

.before(String date or time)

Determines whether the date/time value is before the date/time argument.

For example:

• @sys-time.before('12:00:00')

• @sys-date.before('2016-11-21')

• If comparing different items, such as time vs. date, date vs. time, and time vs. date and time, the method returns false and an exception is printed in the response JSON log output.log_messages.

  For example, @sys-date.before(@sys-time).

• If comparing date and time vs. time the method ignores the date and only compares times.

now(String time zone)

Returns a string with the current date and time in the format yyyy-MM-dd HH:mm:ss. Optionally specify a timezone value to get the current date and time for a specific time zone, with a returned string in the format yyyy-MM-dd HH:mm:ss 'GMT'XXX.

• Static function.
• The other date/time methods can be invoked on date-time values that are returned by this function and it can be passed in as their argument.
• The user interface creates a $timezone context variable for you automatically so the correct time is returned when you test from the "Try it out" pane. If you don't pass a time zone, the time zone that is set automatically by the UI is used. Outside of the UI, GMT is used as the time zone. To learn about the syntax to use to specify the time zone, see Time zones supported by system entities.

Example of now() being used to first check whether it's morning before responding with a morning-specific greeting.

{
  "conditions": "now().before('12:00:00')",
  "output": {
      "generic": [
        {
        "values": [
          {
          "text": "Good morning!"
          }
        ],
        "response_type": "text",
        "selection_policy": "sequential"
        }
      ]
  }
}

Example of using now() with a timezone to return the current time (in England):

{
  "output": {
      "generic": [
        {
        "values": [
          {
          "text": "The current date and time is: <? now('Europe/London') ?>"
          }
        ],
        "response_type": "text",
        "selection_policy": "sequential"
        }
      ]
  }
}

You can substitute the hard-coded time zone value with a context variable to dynamically change the time based on a time zone that is passed to the expression. For example: <? now('$myzone') ?>. The $myzone context variable might be set to 'Australia/Sydney' in one conversation and to 'Mexico/BajaNorte' in another.

.reformatDateTime(String format)

Formats date and time strings to the format desired for user output.

Returns a formatted string 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 context variable definition creates a $time variable that saves the value 17:30:00 as 5:30 PM.

{
  "context": {
    "time": "<? @sys-time.reformatDateTime('h:mm a') ?>"
  }
}

Format follows the Java SimpleDateFormat rules.

Note: When trying to format time only, the date is treated as 1970-01-01.

.sameMoment(String date/time)

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

.sameOrAfter(String date/time)

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

.sameOrBefore(String date/time)

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

today()

Returns a string with the current date in the format yyyy-MM-dd.

• Static function.
• The other date methods can be invoked on date values that are returned by this function and it can be passed in as their argument.
• If the context variable $timezone is set, this function returns dates in the client's time zone. Otherwise, the GMT time zone is used.

Example of a dialog node with today() used in the output field:

{
  "conditions": "#what_day_is_it",
  "output": {
    "generic": [
      {
        "values": [
          {
          "text": "Today's date is <? today() ?>."
          }
        ],
        "response_type": "text",
        "selection_policy": "sequential"
      }
    ]
  }
}

Result: Today's date is 2018-03-09.

Working with time spans

To show a response based on whether today's date falls within a certain time frame, you can use a combination of time-related methods. For example, if you run a special offer during the holiday season every year, you can check whether today's date falls between November 25 and December 24 of this year. First, define the dates of interest as context variables.

In the following start and end date context variable expressions, the date is being constructed by concatenating the dynamically-derived current year value with hard-coded month and day values.

"context": {
   "end_date": "<? now().reformatDateTime('Y') + '-12-24' ?>",
   "start_date": "<? now().reformatDateTime('Y') + '-11-25' ?>"
 }

In the response 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 context 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.

To get the date of the day that falls a week from today, you can use the following syntax.

{
  "context": {
    "week_from_today": "<? 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. (The (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. Note that the time is in the UTC time zone. You can always change the 7 to a variable ($number_of_days, for example) that you can pass in. Just be sure that its value gets set before this expression is evaluated.

If you want to be able to subsequently compare the date with another date that is generated by the service, then you must reformat the date. System entities (@sys-date) and other built-in methods (now()) convert dates to the yyyy-MM-dd format.

{
  "context": {
    "week_from_today": "<? new Date(new Date().getTime() +
      (7 * (24*60*60*1000L))).format('yyyy-MM-dd') ?>"
  }
}

After reformatting the date, the result is 2018-01-26. Now, you can use an expression like @sys-date.after($week_from_today) in a response condition to compare a date specified in user input to the date saved in the context variable.

The following expression calculates the time 3 hours from now.

{
  "context": {
    "future_time": "<? new Date(new Date().getTime() + (3 * (60*60*1000L)) -
      (5 * (60*60*1000L))).format('h:mm a') ?>"
  }
}

The (60*60*1000L) value represents an hour in milliseconds. This expression adds 3 hours to the current time. It then recalculates the time from a UTC time zone to EST time zone by subtracting 5 hours from it. It also reformats the date values to include hours and minutes AM or PM.

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.

If you 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. For example, numbers that are greater than 2^31 (2,147,483,648) or lower 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).

If you need to find out if a number is too long to be recognized properly in the dialog, you can check whether there are more than 18 integers in the number by using an expression like this:

``` {: codeblock}

  If you need to work with numbers that are longer than 18 integers, consider using a pattern entity (with a regular expression such as `\d{20}`) to work with them instead of using `@sys-number`.

### Standard math {: #dialog-methods-numbers-standard-math}

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

| Arithmetic operation | Symbol |
|--------|:-----------|
| addition | + |
| division | / |
| multiplication | * |
| subraction | - |

For example, in a dialog node response, you might add a context variable that captures a number specified in the user input (`@sys-number`), and saves it as `$your_number`. You can then add the following text as a text response:

``` {: codeblock}
I'm doing math. Given the value you specified ($your_number), when I add 5, I get: <? $your_number + 5 ?>. 
When I subtract 5, I get: <? $your_number - 5 ?>. 
When I multiply it by 5, I get: <? $your_number * 5 ?>. 
When I divide it by 5, I get: <? $your_number/5 ?>.

If the user specifies 10, then the resulting text response looks like this:

I'm doing math. Given the value you specified (10), when I add 5, I get: 15. 
When I subtract 5, I get: 5. 
When I multiply it by 5, I get: 50. 
When I divide it by 5, I get: 2.

Java number support

java.lang.Math()

Performs basic numeric operations.

You can use the the Class methods, including these:

• max()

{
  "context": {
    "bigger_number": "<? T(Math).max($number1,$number2) ?>"
  },
  "output": {
    "generic": [
      {
        "values": [
          {
          "text": "The bigger number is $bigger_number."
          }
        ],
        "response_type": "text",
        "selection_policy": "sequential"
      }
    ]
  }
}

• min()

{
  "context": {
    "smaller_number": "<? T(Math).min($number1,$number2) ?>"
  },
  "output": {
    "generic": [
      {
        "values": [
          {
          "text": "The smaller number is $smaller_number."
          }
        ],
        "response_type": "text",
        "selection_policy": "sequential"
      }
    ]
  }
}

• pow()

{
  "context": {
    "power_of_two": "<? T(Math).pow($base.toDouble(),2.toDouble()) ?>"
  },
  "output": {
    "generic": [
      {
        "values": [
          {
          "text": "Your number $base to the second power is $power_of_two."
          }
        ],
        "response_type": "text",
        "selection_policy": "sequential"
      }
    ]
  }
}

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

java.util.Random()

Returns a random number. You can use one 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 the top of the number range you want + 1. 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 a dialog node that is triggered by the #random_number intent. The first response condition might look like this:

Condition = @sys-number
{
  "context": {
    "answer": "<? new Random().nextInt(@sys-number.numeric_value + 1) ?>"
  },
  "output": {
    "generic": [
      {
        "values": [
          {
          "text": "Here's a random number between 0 and @sys-number.literal: $answer."
          }
        ],
        "response_type": "text",
        "selection_policy": "sequential"
      }
    ]
  }
}

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

You can use standard methods of the following classes also:

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

JSONObject.clear()

This method clears all values from the JSON object and returns null.

For example, you want to clear the current values from the $user context variable.

{
  "context": {
    "user": {
      "first_name":"John",
      "last_name":"Snow"
    }
  }
}

Use the following expression in the output to define a field that clears the object of its values.

{
  "output": {
    "object_eraser": "<? $user.clear() ?>"
  }
}

If you subsequently reference the $user context variable, it returns {} only.

You can use the clear() method on the context or output JSON objects in the body of the API /message call.

- All default values that were set for variables in nodes that have been triggered during the current session.
- Any updates made to the default values with information provided by the user or external services during the current session.

{
  "output": {
    "generic": [
      {
        "values": [
          {
          "text": "Response for this node."
          }
        ],
        "response_type": "text",
        "selection_policy": "sequential"
      }
    ],
    "context_eraser": "<? context.clear() ?>"
  }
}

{
  "output": {
    "generic": [
      {
        "values": [
          {
          "text": "Have a great day!"
          }
        ],
        "response_type": "text",
        "selection_policy": "sequential"
      }
    ],
    "output_eraser": "<? output.clear() ?>"
  }
}

JSONObject.has(String)

This method returns true if the complex JSONObject has a property of the input name.

For this Dialog runtime context:

{
  "context": {
    "user": {
      "first_name": "John",
      "last_name": "Snow"
    }
  }
}

Dialog node output:

{
  "conditions": "$user.has('first_name')"
}

Result: The condition is true because the user object contains the property first_name.

JSONObject.remove(String)

This method removes a property of the name from the input JSONObject. The JSONElement that is returned by this method is the JSONElement that is being removed.

For this Dialog runtime context:

{
  "context": {
    "user": {
      "first_name": "John",
      "last_name": "Snow"
    }
  }
}

Dialog node output:

{
  "context": {
    "attribute_removed": "<? $user.remove('first_name') ?>"
  }
}

Result:

{
  "context": {
    "user": {
      "last_name": "Snow"
    },
    "attribute_removed": {
      "first_name": "John"
    }
  }
}

com.google.gson.JsonObject support

In addition to the built-in methods, some of the standard methods of the com.google.gson.JsonObject class are also supported.

String.append(Object)

This method appends an input object to the string as a string and returns a modified string.

For this Dialog runtime context:

{
  "context": {
    "my_text": "This is a text."
  }
}

This syntax:

{
  "context": {
    "my_text": "<? $my_text.append(' More text.') ?>"
  }
}

Results in this output:

{
  "context": {
    "my_text": "This is a text. More text."
  }
}

String.contains(String)

This method returns true if the string contains the input substring.

Input: "Yes, I'd like to go."

This syntax:

{
  "conditions": "input.text.contains('Yes')"
}

Results: The condition is true.

String.endsWith(String)

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

For this input:

"What is your name?".

This syntax:

{
  "conditions": "input.text.endsWith('?')"
}

Results: The condition is true.

String.equals(String)

This method returns true if the specified string equals the input string exactly.

Input: "Yes"

This syntax:

{
  "conditions": "input.text.equals('Yes')"
}

Results: The condition is true.

If the input is Yes., then the result is false because the user included a period and the expression expects only the exact text, Yes without any punctuation.

String.equalsIgnoreCase(String)

This method returns true if the specified string equals the input string, regardless of whether the case of the letters match.

Input: "yes"

This syntax:

{
  "conditions": "input.text.equalsIgnoreCase('Yes')"
}

Results: The condition is true.

If the input is Yes., then the result is false because the user included a period and the expression expects only the text, Yes, in uppercase or lowercase letters without any punctuation.

String.extract(String regexp, Integer groupIndex)

This method returns a string from the input that matches the regular expression group pattern that you specify. 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 context 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. There is an inherent third group that is comprised of the two groups together. This is the first (groupIndex 0) regex group; it matches with a string that contains the full number group and text group together. 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.

{
  "context": {
    "number_extract": "<? input.text.extract('([\\d]+)(\\b [A-Za-z]+)',n) ?>"
  }
}

When you specify the regex in JSON, you must provide two backslashes (\). If you specify this expression in a node response, you need one backslash only. For example:

<? input.text.extract('([\d]+)(\b [A-Za-z]+)',n) ?>

Input:

"Hello 123 this is 456".

Result:

• 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 will convert the array or object to a string before making the comparison.

For this input:

"Hello 123456".

This syntax:

{
  "conditions": "input.text.find('^[^\d]*[\d]{6}[^\d]*$')"
}

Result: 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 from the input that matches the occurrence of the regular expression pattern that you specify. 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 a matches array. If you want to return the third match, because the array element count starts at 0, 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.

In the following expression, you are looking for a group of numbers in the input. This expression saves the second pattern-matching string into the $second_number context variable because the index value 1 is specified.

{
  "context": {
    "second_number": "<? input.text.getMatch('([\\d]+)',1) ?>"
  }
}

If you specify the expression in JSON syntax, you must provide two backslashes (\). If you specify the expression in a node response, you need one backslash only.

For example:

<? input.text.getMatch('([\d]+)',1) ?>

• User input:

  "hello 123 i said 456 and 8910".
  

• Result: 456

In this example the expression looks for the third block of text in the input.

<? input.text.getMatch('(\b [A-Za-z]+)',2) ?>

For the same user input, this expression returns and.

String.isEmpty()

This method returns true if the string is an empty string, but not null.

For this Dialog runtime context:

{
  "context": {
    "my_text_variable": ""
  }
}

This syntax:

{
  "conditions": "$my_text_variable.isEmpty()"
}

Results: The condition is true.

String.length()

This method returns the character length of the string.

For this input:

"Hello"

This syntax:

{
  "context": {
    "input_length": "<? input.text.length() ?>"
  }
}

Results in this output:

{
  "context": {
    "input_length": 5
  }
}

String.matches(String regexp)

This method returns true if the string matches the input regular expression.

For this input:

"Hello".

This syntax:

{
  "conditions": "input.text.matches('^Hello$')"
}

Result: The condition is true because the input text matches the regular expression \^Hello\$.

String.startsWith(String)

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

For this input:

"What is your name?".

This syntax:

{
  "conditions": "input.text.startsWith('What')"
}

Results: The condition is true.

String.substring(Integer beginIndex, Integer endIndex)

This method gets a substring with the character at beginIndex and the last character set to index before endIndex. The endIndex character is not included.

For this Dialog runtime context:

{
  "context": {
    "my_text": "This is a text."
  }
}

This syntax:

{
  "context": {
    "my_text": "<? $my_text.substring(5, $my_text.length()) ?>"
  }
}

Results in this output:

{
  "context": {
    "my_text": "is a text."
  }
}

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 context 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 original String converted to lowercase letters.

For this input:

"This is A DOG!"

This syntax:

{
  "context": {
    "input_lower_case": "<? input.text.toLowerCase() ?>"
  }
}

Results in this output:

{
  "context": {
    "input_lower_case": "this is a dog!"
  }
}

String.toUpperCase()

This method returns the original String converted to uppercase letters.

For this input:

"hi there".

This syntax:

{
  "context": {
    "input_upper_case": "<? input.text.toUpperCase() ?>"
  }
}

Results in this output:

{
  "context": {
    "input_upper_case": "HI THERE"
  }
}

String.trim()

This method trims any spaces at the beginning and the end of the string and returns the modified string.

For this Dialog runtime context:

{
  "context": {
    "my_text": "   something is here    "
  }
}

This syntax:

{
  "context": {
    "my_text": "<? $my_text.trim() ?>"
  }
}

Results in this output:

{
  "context": {
    "my_text": "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.

{
  "formatted String": "<? T(java.lang.String).format('%d + %d equals %d', 1, 1, 2) ?>"
}

{
  <? T(String).format('%.2f',<number to format>) ?>
}