Bot Framework Composer — Property management | Part 2

This is the second part of my Bot Framework Composer blog series. If you want to know more about basics of Composer, take a look at the first part

Contents

• Introduction
• Property scopes
• user
• conversation
• dialog
• turn
• Summary

Introduction

All bots built with 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.

Property scopes

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.

Within Composer there are four different property scopes:

Permanent scopes:

• user — a place to store information about individual users
• conversation — a place to store information about ongoing conversations

Ephemeral scopes:

• dialog
• turn

Here are a couple of examples:

· user.name

· dialog.index

· turn.activity

· user.profile.age

· this.value

user

The user scope is tied to the user. This is why properties in the user scope are stored indefinitely for a specific user. Use this scope if you want to store user information such as the following within your bot:

• General information such as name, birthday, age, …
• Location information such as address, street, postal code, country, …
• Contact information such as email address, telephone number, …

To create a new property using the user scope, simply name your property user.propertyName (e.g.: user.name or user.age).

conversation

In contrast to the user scope, the conversation is associated with the conversation id. Properties in the conversation scope have a lifetime of the conversation itself. Properties in the conversation scope may be accessed by multiple users within the same conversation (for example, multiple users together in a Microsoft Teams channel).

If you want to create a new conversation-scoped property just use conversation.propertyName as the property’s name (e.g.: conversation.topic).

NOTE: The conversation scope is not always only bound to one specific user only. For instance, when your bot is used in a Microsoft Teams team or group conversation, multiple users are part of the same conversation and therefore share the same conversationID. So please use this scope accordingly.

dialog

The dialog scope, as the name already suggests, 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.

We usually store external API call response into a dialog scope.

turn

The turn scope is bound to one specific turn within the conversation. A turn is basically described as handling one specific message from the user, therefore this scope is the one with the lowest lifetime as these kind properties are only retained until the bot has successfully handled the user’s message. Thus, turn-scoped properties are often used to cache certain values before persisting them into other scopes, like dialog or user. Three out of the box property within turn scope, however, are:

• turn.activity.from.id holds the user id coming from the app as part of DirectLine token. It could be a GUID or an encrypted string. Maximum 64 characters are supported.
• turn.activity.from.name holds the user name coming from the app as part of DirectLine token
• turn.activity.text holds the user message within the current turn
• turn.activity.type holds the activity type of the current turn (e.g.: message, conversationUpdate, typing, endOfConversation, messageReaction, …)
• turn.activity.locale holds the locale of the locale of the turn.activity.text property (e.g.: en-us, de-de, …)

Reference — Microsoft Tutorial

Reference — Bisser.io

Summary

Properties are an essential part within Bot Framework Composer. They are an easy way to share information across the whole conversation and therefore minimize the effort to implement a bot. It’s useful to establish conventions for your state properties across conversation, user, and dialog state for consistency and to prepare for context sharing scenarios. It's also a good practice to think about the lifetime of the property when creating it.

I hope you’ll find this article useful!

Happy composing 😀