All bots built with the Bot Framework Composer have a "memory", a representation of everything that is currently in the bot's active mind. Developers can store and retrieve values in the bot's memory, and can use those values to create loops, branches, dynamic messages and behaviors in the bot. Properties stored in memory can be used inside templates or as part of a calculation.
The memory system makes it possible for bots built in Composer to do things like:
- Store user profiles and preferences.
- Remember things between sessions such as the last search query or a list of recently mentioned locations.
- Pass information between dialogs.
A piece of data in memory is referred to as a property. A property is a distinct value identified by a specific address comprised of two parts, the scope of the property and the name of the property: scope.name.
Here are a couple of examples:
user.nameturn.activitydialog.indexuser.profile.age
The scope of the property determines when the property is available, and how long the value will be retained.
The bot's memory has two "permanent" scopes. The first is a place to store information about individual users, the second is a place to store information about ongoing conversations:
-
user is associated with a specific user. Properties in the user scope are retained forever.
-
conversation is associated with the conversation id. Properties in the user scope are retained forever and may be accessed by multiple users within the same conversation (for example, multiple users together in a Microsoft Teams channel).
The bot's memory also has two "ephemeral" scopes. Ephemeral scopes are a place to store temporary values that are only relevant while a task is being handled. The two scopes are:
-
dialog is associated with the active dialog and any child or parent dialogs. Properties in the dialog scope are retained until the last active dialog ends.
-
turn is associated with a single turn. You can also think of this as the bot handling a single message from the user. Properties in the turn scope are discarded at the end of the turn.
Input is collected from user's with prompt types provided in the Ask a question sub-menu.
Prompts define the question posed to the user and are set in the Prompt box under the Bot Asks tab in the properties panel on the left.
Under the User Input tab you'll see Property to fill, where the user's response will be stored. Prompt responses can be formatted before being stored by selecting an option for Output Format, and their locale can be set with Default locale.
In the above example of a number prompt, the result of the prompt "What is your age?" will be stored as the user.age property. The result will be stored as a float since the float output format was selected.
For more information about implementing text other prompts see the article Asking users for input.
The Bot Framework Composer provides a set of memory manipulation actions in the Manage properties sub-menu. These actions can be used to create, initialize, modify and delete properties in memory. Properties can be created in the editor and during runtime. Composer will automatically manage the underlying data for you.
Use Set a property to set the value of a property.
The value of a property can be set to a literal value, like true, 0, or fred, or it can be set to the result of a computed expression. When storing simple values it is not necessary to initialize the property.
Use Set properties to set a group of properties.
The value of each property is assigned individually in the Properties panel. Don't forget to press Enter to save the property setting before you set the next one.
Use Initialize a property to create new properties that are objects or arrays.
It is important to note that before setting the value of a sub-property like user.profile.age that user.profile must first be initialized. It is not necessary to also initialize user.profile.age unless age also contains sub-values.
Use Delete a Property to remove a property from memory.
Use Delete properties to remove properties from memory.
Use Edit an Array Property to add and remove items from an array. Items set in Value can be added or removed from the beginning or end of an array in the Items property using push, pop, take, remove, and clear in Type of change. The result of the edited array is saved to Result Property
Note that it is possible to push the value of an existing property into an array property. For example, push turn.choice onto dialog.choices.
Child dialogs can return values to their parent dialogs. In this way, a child dialog can encapsulate a multi-step interaction, collect and compute multiple values, and then return a single value to its parent dialog.
For example, a child dialog might first Initialize an object property called dialog.profile. Then, using prompts, build a compound property representing a user profile:
Finally, the dialog returns the compound value to the parent dialog. The return value is specified as the Default result property within the trigger for the child dialog:
Finally, the parent dialog is configured to capture the return value inside the Begin a new dialog action:
When executed, the bot will execute the profile child dialog, collect the user's name and age in a temporary scope, then return it to the parent dialog where it is captured into the user.profile property and stored permanently.
Some properties are automatically created and managed by the bot. These are available automatically.
| Property | Description |
|---|---|
| turn.activity | The full incoming Activity object. |
| turn.intents | If a recognizer is run, the intents found. |
| turn.entities | If a recognizer is run, the entities found. |
| turn.dialogEvents.event name.value | Payload of a custom event fired using the EmitEvent action. |
Bots can retrieve values from memory for a variety of purposes. The bot may need to use a value in order to construct an outgoing message, or make a decision based on a value then perform actions based on that decision, or use the value to calculate other values.
Sometimes, you will refer directly to a property by its address in memory: user.name. Other times, you will refer to one or more properties as part of an expression: (dialog.orderTotal + dialog.orderTax) > 50.
The Bot Framework Composer uses the common expression language to calculate computed values. This syntax allows developers to create composite values, define complex conditional tests, and transform the content and format of values. For more information see the common expression language operators and pre-built functions.
When used in expressions, no special notation is necessary to refer to a property from memory.
A bot can evaluate values from memory when making decisions inside a branching action like an If/Else or Switch branch. The conditional expression that is tested in one of these branching actions is an expression that, when evaluated, drives the decision.
In the example below, the expression user.profile.age > 13 will evaluate to either True or False, and the flow will continue through the appropriate branch.
In this second example, the value of turn.choice is used to match against multiple Switch cases. Note that, while it looks like a raw reference to a property, this is actually an expression and since no operation is being taken on the property, the expression evaluates to the raw value.
When using For each and For each page loops, properties also come into play. Both require an Items property that holds the array, and For each page loops also require a Page size, or number of items per page.
One of the most powerful features of the Bot Framework system is Language Generation, particularly when used alongside properties pulled from memory.
You can refer to properties in the text of any message, including prompts.
You can also refer to properties in LG templates. See the Language Generation readme to learn more the Language Generation system.
To use the value of a property from memory inside a message, wrap the property reference in curly brackets: {user.profile.name}
The screenshot below demonstrates how a bot can prompt a user for a value, then immediately use that value in a confirmation message.
In addition to getting properties values, it is also possible to embed properties in expressions used in a message template. Refer to the Common Expression Language page for the full list of pre-built functions.
Properties can also be used within an LG template to provide conditional variants of a message and can be passed as parameters to both built-in and custom functions. Learn more about LG.
The Bot Framework Composer provides a variety of shortcuts for referring to properties in memory. Refer to the Managing state documentation for the complete list of memory shorthand notations.
- Language Generation in the Bot Framework Composer.