Expression configuration
Function overview
Expression configuration enhances the scalability of the Alibaba Cloud Intelligent Customer Service chatbot platform, enabling support for complex business scenarios.
Syntax rules and descriptions
The following expression types are supported:
Slot: A slot configured on a slot filling node. You can use the slotVars['full_slot_name'] or slotVars['full_slot_name.origin'] syntax to reference it. The expression evaluates to the corresponding slot value or its normalized value, which is valid within the currently active intent. For example:
A reference evaluates to the corresponding slot value for the currently active intent. For example:
sysVars['CheckWeatherIntent.Location'] or sysVars['CheckWeatherIntent.Location.origin'] evaluates to the value of the corresponding slot.
or the corresponding normalized value
Variables: These are variables that you define in the bot. You can reference them using the botVars['variable_name'] syntax. The value is valid for the entire conversation. For example, botVars['city_name'] returns the value of the custom variable "city_name", such as "Beijing".
Service return parameters: These are parameters returned from a global service or custom function. You can reference them using the svcVars['xxx'] syntax. The value is valid for the entire conversation. For example, svcVars['global_service_name.return_parameter_name'] returns the value of a specific return parameter from the referenced global service.
Conversation environment parameters: These are variables passed from an upstream system with the request. You can reference them using the envVars['environment_parameter_name'] syntax. The value is valid only for the current conversation turn. For example, envVars['VENDOR_PARAM'] returns the value of the VENDOR_PARAM environment parameter.
Common environment parameters include VENDOR_PARAM, SENDER_ID, SENDER_NICK, TAG, EMOTION_POLARITY, EMOTION_NAME, and CURRENT_QUERY.
For example, envVars['VENDOR_PARAM']['key1'] returns the value that corresponds to key1 in VENDOR_PARAM.
System parameters: These are variables automatically maintained by Dialog Studio (DS) during a Q&A session. You can reference them using the sysVars['xxx'] syntax. The value is valid for the entire conversation. System parameters fall into three main categories:
Retrieve the current user intent: sysVars['user_intent']
Retrieve the number of times a specific intent was triggered. For example, sysVars['check_weather_intent.intentHitTimes'].
Retrieve the trigger count for a branch in a Start node or an interaction node. For example, sysVars['node_name.branch_name.hitTimes'].
Built-in variables: These are system-provided utilities that typically start with sys. The following built-in variables are supported:
sysTurn: The number of the current conversation turn.
sysDate: The current system date in yyyy-MM-dd format.
sysTime: The current system time in HH:mm:ss format.
sysQuery: Retrieves the current user query. This is equivalent to envVars['CURRENT_QUERY'].
sysGetRandom(n): Returns a random number in the range of [1, n]. For example, sysGetRandom(10) might return 7.
Entities: An entity name is prefixed with the at sign (@). Entities are typically used for conditional checks on the DS canvas and are valid only for the current conversation turn.
@user_ID: The expression evaluates to a member of the detected "user_ID" entity. If it is a system entity, the result is the detected value, such as "Beijing". When used in a conditional judgment, the expression evaluates to true if the entity is detected and false if it is not.
Intent: You can use the number sign (#) as a prefix for the intent name. This is typically used for conditional judgments on the DS canvas and is valid only for the current conversation turn. For example:
#check_weather_intent: The expression evaluates to the confidence level of the intent, such as 0.95. When used in a conditional judgment, the expression evaluates to true if the intent is detected and false if it is not.
Usage examples
Conditional judgments
Expressions for conditional judgments must evaluate to either true or false. The operands for logical operators, such as not, and, or or, must be of type String, Integer, Boolean, or null. The following are common examples:
Expression | Description |
#check_weather_intent | Checks if the user's query contains the "check_weather_intent". |
@sys.date | Checks if the user's query contains a time in yyyy-MM-dd format. |
sysDate>='2022-01-01' | Checks if the current date is on or after '2022-01-01'. |
botVars['userId'] == '123456789' | Checks if the custom variable "user_ID" is equal to "123456789". |
sysQuery matches'.*medal.*' | Checks if the user's query contains the word "medal". Note `matches` is a built-in keyword used for strict matching with standard regular expressions. |
botVars['location'].contains('Beijing') | Checks if the value returned by the custom variable "location" contains "Beijing". |
(new java.util.Date().getTime() - new java.text.SimpleDateFormat("yyyy-MM-dd").parse(@sys_date).getTime())/1000>=1 * 30 * 24 * 3600 | Checks if the time entered by the user is more than one month ago. |
Variable assignment and response scripts
Optional slot: In previous versions of the DS canvas, you had to configure optional slots. In the new canvas, you can add a variable assignment to the user branch. For example:
Expression | Description |
global_variable_1=entityVars['address_entity'][0].normalizedValue |
|
global_variable_2=sysDate | Assigns the current date to global_variable_2. |
global_variable_3=sysGetRandom(5) | Generates a random number in the range of [1, 5] and assigns it to global_variable_3. |
Advanced usage examples
List-based response script configuration
Scenario: In some business scenarios, a third-party service returns a list of indeterminate length, such as an inventory list. This section explains how to use expressions to allow operators to flexibly configure response scripts on the canvas.
Solution: Use a function-based expression evaluation syntax. You can configure it directly in the chatbot's response text box. The format is `<f:method_name input=input_expression output=output_expression/>`. The elements are described as follows:
Method name: The supported method is `list`, which indicates an enumeration.
Input expression: All evaluatable expressions are supported. The return type must match the function identifier (`list`).
Output expression: All evaluatable template expressions are supported, which are consistent with response scripts.
Built-in variables include `&list_index` for the list index and `&list_element` for the element in the list.
If each element in the list is a Map, you can retrieve a key's value using `&list_[key]`.
Examples:
JSON array type:
The value of `svcVars['query_details_service.result']` is `{"ret":[{"category":"women's_clothing","detail":"out_of_stock"},{"category":"toys","detail":"in_stock"}]}`.
Expression: `<f:list input=svcVars['query_details_service.result']['ret'] output=Detail-Item ${&list_index+1}: Category ${&list_category}, Status: ${&list_detail},/>`
The evaluated result is: `Detail-Item 1: Category women's_clothing, Status: out_of_stock, Item 2: Category toys, Status: in_stock,`
Simple array type:
The value of `svcVars['query_list_service.result']` is `["women's_clothing","toys"]`.
Expression: `<f:list input=svcVars['query_list_service.result'] output=Item ${&list_index+1}: ${&list_element},/>`
The evaluated result is: `Item 1: women's_clothing, Item 2: toys,`
Other
To retrieve the original value of a specified entity: `rawEntities['entity_name'][0].entityValue`
Unsupported scenarios
Expressions that start with a number sign (#) for intents are not supported for variable assignment or in response scripts.
Expressions that start with an at sign (@) for entities are not supported in response scripts.