Expressions for Variable Values

You can use FreeMarker expressions for values of variables in your dialog flows.

Handy Expressions

Here are some common expressions you can use in your flows.

Tip:

Autocompletion guides you through writing these (and other) Apache FreeMarker expressions.
Operation Freemarker Expression Result Type
Get name of parent flow ${system.parentFlow} String
Get event payload ${skill.system.event.value.EVENT_NAME} JSON object
Access NLP result ${skill.system.nlpresult.value} JSON object
Access skill-scope variable ${skill.VAR_NAME}  
Access flow-scope variable ${VAR_NAME}  
Access flow input param ${INPUT_PARAM_NAME}  
Access user-scope variable ${user.VAR_NAME}  
Access profile-scope variable ${profile.VAR_NAME}  
Get Answer Intent answer ${skill.system.event.value.intent.answer}

Note: You can also use ${skill.system.event.value.answerIntent.answer}.

 
Get intent name

${skill.system.event.value.intent.intentName}

String
Get error message ${skill.system.event.value.dialogError.errorMessage} String
Access Resource bundle entry ${skill.system.rb.RB_ENTRY_NAME} Resource Bundle
Access the value of a custom parameter ${skill.system.config.CUSTOM_PARAMETER_NAME} String

For more on FreeMarker in your components, see Apache FreeMarker Template Language Syntax.

Apache FreeMarker Template Language Syntax

You can use Apache FreeMarker Template Language (FTL) to access variable values, show or hide response items, find key words in a user message, print a list of values, or display arrays that are sorted by a specific data attribute. The basic syntax for these value expressions is ${...}. You can incorporate FTL into the property definitions for various dialog flow components.

Note:

You can also define the expressions using the if directive (<#if>...</#if>).
To do this... ...Do this
Read values from variables. Add the value property using dot notation:
${VAR_NAME.value}
For example:
${MyEmail.value}
Read values from variables defined by complex entities. Use dot notation to add an additional property:
${VAR_NAME.value.property}
For example:
${MyMoney.value.totalCurrency}
If you use an expression like ${MyMoney} in a System.Output component in a skill with a YAML-based dialog flow, you will see all the properties of the referenced currency JSON object.
Return the set of values that are defined for a value list entity. Use the built-in type and enumValues variable in the following syntax:
${VAR_NAME.type.enumValues}
Use built-ins for strings, arrays (sequences), numbers, and dates. See Apache FreeMarker Reference. Follow the value property with a question mark (?) and the operation name:
${VAR_NAME.value?ftl_function}
  • string operations:
    ${VAR_NAME.value?lower_case}
  • array operations:
    ${VAR_NAME.value?size?number}
  • number operations:
    ${VAR_NAME.value?round}
  • time and date operations:
    ${VAR_NAME.value.date?long?number_to_date?string.short}
Concatenate FTL expressions. String the operations together using a question mark (?):
${VAR_NAME.value?ftl_function1?ftl_function2}

Referencing Entity Values in Multi-Language Skills

When you have multi-language skills, you should make sure the component that is resolving your entities has Use Full Entity Matches set to true. This enables you to write the following kinds of expressions:

  • Expressions that reference the entity value in the language of the conversation. You can use such expressions to do things such as display the entity values to users in buttons, confirmation messages, etc.

    For such expressions, you append value to get the value in the language of the conversation. For example, if you have defined a dialog flow variable, pizza, and want to reference the PizzaSize entity value in a prompt, you would use the following in the expression: pizza.value.PizzaSize.value (instead of just pizza.value.PizzaSize).

  • Expressions that reference the value of the entity in the primary language. The primary language value serves as a kind of key for the corresponding values in all of the entity's languages. You can reference this value for business logic purposes without having to worry about which language the conversation is in.

    For these expressions, you append primaryLanguageValue (e.g. pizza.value.PizzaSize.primaryLanguageValue).