Actions and Parameters

Actions

An action corresponds to the step your application will take when a specific intent has been triggered by a user’s input. Actions can have parameters for extracting information from user requests and will appear in the following format in a JSON response:

{“action”:”action_name”}
{“parameter_name”:”parameter_value”}

Both the action name and it’s parameters are defined in the Action section of an intent. For example, if you are building an application for sending messages, the Action section would have the name of the action, as well as any automatically defined or manually added parameter values.

Parameters

Parameters are elements generally used to connect words in a user’s response, to entities. In JSON responses to a query, parameters are returned in the following format:

{“parameter_name”:”parameter_value”}

Parameters appear in two different areas. In the User Says section, parameters related to known entities will be highlighted (annotated) after an example is added. Clicking on an annotated word in an example, will reveal a table with data on the chosen entity.

A table of the parameters in the intent, is located under the Action section of the intent page. This table represents all of the parameters used throughout all of the User Says examples in the current intent.

Defining Parameters

Automatic (Default)

When you enter an example in the User Says section of an intent, words that correspond to system and developer entries will be highlighted (annotated), and parameters will automatically appear in the parameter table.

Manual

There are some cases when you may need to define or edit parameters and their values manually. For example, if your application controls a robot’s step motor, you may want to use fixed values for the parameters. You need to enter these values manually.

Deleting Parameters

You can delete the association between a word and an entity by removing the annotation from a single User Says example. Doing this will only affect this particular example.

If you need to delete an association from the entire intent, you can delete the parameter row by hovering over the parameter, click on the menu button and choose Delete.

The Parameter Table

Entries in both the User Says and Action parameter tables can be manually defined or edited. Changes to parameters in the User Says table, only affect the parameters in the selected User Says example. Changes to parameters in the Action table affect the parameter throughout the current intent.

Required

Checking this option will mark the parameter as required, which means the the parameter is needed to perform the action in the intent. When this option is enabled, a Prompts column will be revealed. This is the response the agent will give when a required parameter isn’t collected.

Parameter Name

This property defines how the parameter will show up in the JSON response:

{“parameter_name”:”parameter_value”}
Entity

This property is the entity (system or developer) that is linked to the parameter. The linked entity can be changed by clicking on the current property and choosing a new entity from the searchable list.

Value

This property is the value assigned to the parameter. In the User Says table, this will show the resolved value from the specific example.

In the Action table, the value is represented as $ and the parameter name. Clicking on value will either show you additional options (automatic) or allow you to edit the value (manual). This is how the value will show up in the JSON response:

{“parameter_name”:”parameter_value”}
Is List

This property marks the parameter as having it’s value as a list. This is ideal for situations where a user’s input contains an enumeration, like “I would like apples, bananas, and oranges.” More on defining list values.

Defining Values

Constant

Your application may need parameters with fixed values.

For example, if your application controls a robot’s step motor, you may want to use fixed values for the parameters. You would need to enter these values manually.

Default

To define a default parameter value, hover over the parameter row, click on the menu button, and select Default Value. This is ideal for situations where you can expect a default value without the user specifying.

For example, your user could say “I want to order a hamburger.” A default value of 1 would be used since a specific quantity wasn’t provided. The returned parameters would look like this:

“resolvedQuery”: “I want to order a hamburger”,
    “parameters”: {
        “item”: “hamburger”,
        “number”: “1”
    }
List

List values can contain an indefinite number of elements. You can define simple User Says examples, which allow for more inputs to be matched.

For example, if you expect users to say "I want apples, bananas, and oranges." or "I want apples and oranges.", you could add the example "I want apples" and then highlight the word “apples” and set the @fruit entity and check the Is List property for the parameter.

When a user says "I want oranges, apples, and bananas." it will recognize all items as related to the @fruit entity.

@sys.date

By default, when you expect a date from a User Says example, the system entity @sys.date is used. If the user provides an incomplete date like “Monday” or “July 8th”, the system will return it’s best estimation at the nearest future date.

For example, if today is November 3rd, 2017 and the user says “Book a ticket for Monday”, the system will return ”date”: “2017-11-6” which is the closest Monday in the future.

You can change the how incomplete dates are handled by setting the parameter value’s option. Clicking on the value for the parameter will give you the following options:

$date.recent - This option estimates the closest past date. If it's November 3rd, 2017 and a user asks “What happened on Monday?” the system will return ”date”: “2017-10-30” which is the closest Monday in the past.

$date.partial - This option accepts the partial date provided by the user, in cases where you want to handle the data with your own logic. If it’s November 3rd, 2017 and a user asks “What happened on April 23rd?” the system would return ”date”: “UUUU-04-23” which is the unaltered data provided by the user.

Extracting Values

Original

You may want to extract the original value from the user’s input to give a grammatically correct response.

For example, a user may ask for one or more items and could use a singular or plural form, like “I want one hamburger” versus “I want five hamburgers”. To provide a proper response, you can define a new parameter with the original value. Click on the value in the “Action” table to see the $parameter_value.original option.

From Composite Entities

By default, composite entities return object-type values. In order to extract string values from "sub-entities", you will need to manually define parameters with the following format:

$composite_entity_parameter_name.subentity_alias
From Contexts

To refer to a parameter value contained within an active context, you will need to manually define parameters with the following format:

#context_name.parameter_name

For example, if you have an active context called “greeting” that contains a parameter called name and you want to reference that parameter's value in another parameter or in a response, you'd use the following format:

#greeting.name

Managing Parameters with Template Mode

In some rare cases, you may want to use Template Mode (indicated by the @ icon at the beginning of the line) instead of the suggested Example Mode.

In templates, entities can be directly referenced in User Says examples. Entities should be referenced by their names, prefixed with the @ sign, and can be used with or without aliases: @entity:alias or @entity respectively.

For example, while using Example Mode, a User Says example could be “What is the forecast for tomorrow?”. This same example in Template Mode would be “What is the @condition for @sys.date?”

The main case for using Template Mode is to take advantage of special syntax.

Referring to Parameter Values in Responses

To reference parameter values in the responses, use the following format:

$parameter_name

If your agent needs to confirm what your user just ordered, and the items use the $item value, a response would look like this: