Variable data types

Simple variables, and complex variable fields have a data type. Choose the type of a variable based on what you want it to hold. When you use a variable of a specific type in a dynamic message, its value can be rendered with appropriate formatting.

String

String of characters (default).

Alphanumeric

String of alphanumeric characters (a-z, A-Z, 0-9).

Digits

String of digits (0-9).

Boolean

Boolean value (true, false).

Integer

Whole number.

Decimal

Decimal-point number.

Amount

Amount, including currency.

Date

Date (YYYYMMDD).

Time

Time (HHMM).

Distance

Distance, including unit and modifier.

Temperature

Temperature, including unit.

Dynamic Entity Data

Dynamic Entity Data is a special variable type, meant to support dynamic list entities. A variable of this type extends a list entity with a set of literals and values to be compiled at runtime.

Use Dynamic Entity Data variables for entities with up to 100 values. For entities that must support more than 100 values, consider referencing precompiled ASR and NLU resources. See dynamic list entity for detailed instructions.

List

List of values of a single simple variable type, or complex values based on a single schema.

A variable of type List can have elements of one type only—a simple type, or a complex type based on a predefined or custom schema.

Dynamic Entity Data and List are not supported types for list elements.

Lists can only get their values from an external system, via data access nodes or external actions nodes.

Compatibility between variables and entities

The data type of a variable determines which entities and other variables are compatible for use in assignments and conditions.

A variable of type string on the left-hand side of an assign action is compatible with all entities and variable types. However, if you use a variable of type string on the right-hand side of an assign action, you are responsible for making sure its value will comply with the internal format of the variable or entity on the left-hand side. Neglecting this could generate errors in your application, at runtime.

In assignments between a variable and an entity, the variable type in the first column of the table below, and the corresponding entity types (fourth column) are compatible both as left operands and right operands. For example, given variable isFirstTime (Boolean) and entity myFIRST_TIME (isA nuance_BOOLEAN), these assignments are both possible:

  • isFirstTime = myFIRST_TIME
  • myFIRST_TIME = isFirstTime

In assignments between two variables, for a left operand with a type in the first column of the table, the right operand can be the same type or another type listed in the last column. For example, given the variables myDecimal (decimal), and myInteger (integer), this assignment is possible:

  • myDecimal = myInteger

However the reverse is not supported:

  • myInteger = myDecimal

In conditional expressions, you cannot directly compare a variable and an entity, or two variables of different types. You must first assign the entity, or one of the two variables, to an intermediate variable of the appropriate type. For example, if you want to compare myDecimal (decimal), and myInteger (integer):

  1. Create a variable of type decimal—for example, myDecimal2
  2. Set an assignment—for example, myDecimal2 = myInteger
  3. Use myDecimal and myDecimal2 in an expression—for example, if myDecimal is greater than myDecimal2

In backend calls, if you configured a data access node or an external actions node with Get data parameters of type digits, the backend must return a string of digits, and not a JSON integer. Likewise, when you test your dialog design in Try mode, the stub data for such variables must be a string of digits.

Variable type Compatible entity data type Description Compatible entity types (collection methods) Other compatible variable types
String Generic String of characters (default) YES_NO, nuance_GENERIC_ORDER, List, Regex, Freeform Alphanumeric, Digits
Alphanumeric Alphanumeric String of alphanumeric characters (a-z, A-Z, 0-9) Regex Digits
Digits Digits String of digits (0-9) nuance_CARDINAL_NUMBER, Regex Integer (not JSON integers)
Boolean Boolean Boolean (true, false) nuance_BOOLEAN —
Integer Digits Whole number nuance_CARDINAL_NUMBER Digits
Decimal Number Decimal-point number nuance_DOUBLE, nuance_NUMBER Integer
Amount Amount Amount, including currency nuance_AMOUNT —
Date Date Date (YYYYMMDD) DATE, nuance_EXPIRY_DATE —
Time Time Time (HHMM) TIME —
Distance Distance Distance, including unit and modifier nuance_DISTANCE —
Temperature Temperature Temperature, including unit nuance_TEMPERATURE —
Dynamic Entity Data — Special type, to support dynamic list entities (for entities with more than 100 values, use the ExternalResourceReferences predefined variable instead) Dynamic list entities —
List — List of values of a single simple variable type (except for Dynamic Entity Data), or complex values based on a single schema Depends on the type of the list elements Type of the list elements

Supported methods

The data type of a variable also determines which methods are available when the variable is used in a dynamic message, a conditional expression, or on the right-hand side of an assignment.

This table shows the methods that are available for each simple variable type, when a variable is used in a dynamic message, a conditional expression, or on the right-hand side of an assignment.

Variable type Methods in assignments Methods in conditional expressions Methods in message annotations
String .length(), .concat(…), .search(…), .substring(…) .value(), .length() Formatted value, .value(), .length()
Alphanumeric Value (implicit) Value (implicit) Formatted value, .value()
Digits Value (implicit) Value (implicit) Formatted value, .value()
Boolean Value (implicit) Value (implicit) Value (implicit)
Integer Value (implicit) Value (implicit) Formatted value, .value()
Decimal Value (implicit) Value (implicit) Formatted value, .value()
Amount .getNumber(), .getUnit() .value(), .getNumber(), .getUnit() Formatted value, .value(), .getNumber(), .getUnit()
Date .getDay(), .getMonth(), .getYear(), .isBefore(…), .isAfter(…), .addDay(…), .addMonth(…), .addYear(…) .value(), .getDay(), .getMonth(), .getYear() Formatted value, .value(), .getDay(), .getMonth(), .getYear()
Time .getHour(), .getMinute(), .getMeridiem(), .isBefore(…), .isAfter(…), .addHour(…), .addMinute(…) .value(), .getHour(), .getMinute(), .getMeridiem() Formatted value, .value(), .getHour(), .getMinute(), .getMeridiem()
Distance getNumber(), getUnit(), getModifier() .value(), .getNumber(), .getUnit(), getModifier() Formatted value, .value(), .getNumber(), .getUnit(), getModifier()
Temperature .getNumber(), .getUnit() .value(), .getNumber(), .getUnit() Formatted value, .value(), .getNumber(), .getUnit()
List .length(), .get(…), .contains(…) .value(), .length() .value(), .length()
Dynamic Entity Data Value (implicit) Value (implicit) Value (implicit)