Using JavaScript v3 user state in a v4 bot
APPLIES TO: SDK v4
This article shows an example of how a v4 bot can perform read, write, and delete operations on v3 user state information.
The code sample can be found in v4 v3 user state adapter sample.
Note
A bot maintains conversation state to track and direct the conversation and ask questions to the user. It maintains user state to track the user's answers.
Prerequisites
npm version 6.9.0 or later (needed to support package aliasing).
Node.js version 10.14.1 or later.
To check the version installed on your computer, in a terminal, execute the following command:
# determine node version node --version
Setup
Clone the repository
git clone https://github.com/microsoft/botbuilder-samples.gitIn a terminal, navigate to
BotBuilder-Samples/Migration/MigrationV3V4/Node/V4V3-user-state-adapter-sample-botcd BotBuilder-Samples/Migration/MigrationV3V4/Node/V4V3-user-state-adapter-sample-botRun
npm installin the following locations:root /V4V3StorageMapper /V4V3UserStateExecute
npm run buildortscto build theStorageMapperandUserStatemodules in the following locations:/V4V3StorageMapper /V4V3UserStateConfigure the data base
- Copy the content od the
.env.examplefile. - Create a new file called
.envand past the previous content into it. - Fill in the values for your storage provider(s). Notice that Username, password and host information can be found in the Azure portal under the section for your particular storage provider such as Cosmos DB, Table storage or SQL database. Table and collection names are user-defined.
- Copy the content od the
Set the bot's storage provider
Open the
index.jsfile in the project root. Towards the beginning of the file (lines ~38-98) you will see configurations for each storage provider, as noted in the comments. They read in the configuration values from the.envfile via Nodeprocess.env. The following code snippet shows how to configure the SQL Database./*----------------------------------------------------------------------------- SQL Database Configuration -----------------------------------------------------------------------------*/ const sqlConfig = { userName: process.env.SQL_USER_NAME, // obtain from Azure Portal password: process.env.SQL_PASSWORD, // obtain from Azure Portal server: process.env.SQL_SERVER_HOST, // obtain from Azure Portal enforceTable: true, // If this property is not set to true it defaults to false. When false if the specified table is not found, the bot will throw an error. options: { database: process.env.SQL_DATABASE_NAME, // user defined table: process.env.SQL_TABLE_NAME, // user defined encrypt: true, rowCollectionOnRequestCompletion: true } }Specify which storage provider you want your bot to use by passing the storage client instance of your choice to the
StorageMapperadapter (~line 107)./*** Pass current storage provider to StorageMapper ***/ /*** possible values: cosmosStorageClient, tableStorage, sqlStorage ***/ const storageMapper = new StorageMapper(cosmosStorageClient);The default setting is Cosmos DB. The possible values are:
cosmosStorageClient tableStorage sqlStorage
Start the application. From the project root, execute the following command:
npm run start
Adapter Classes
V4V3StorageMapper
The StorageMapper class contains the main adapter functionality. It implements the v4 Storage interface and maps the storage provider methods (read, write and delete) back to the v3 storage provider classes so that v3-formatted user state can be used from a v4 bot.
V4V3UserState
This class extends the v4 BotState class (botbuilder-core) so that it uses a v3-style key, allowing read, write & delete to v3 storage.
Testing the bot using Bot Framework Emulator
Bot Framework Emulator is a desktop application that allows to test and debug a bot on localhost or running remotely through a tunnel.
- Install the Bot Framework Emulator, version 4.3.0 or later.
Connect to the bot using Bot Framework Emulator
- Launch Bot Framework Emulator.
- Enter the following URL (end point):
http://localhost:3978/api/messages.
Testing steps
- Open bot in Emulator and send a message. Provide your name when prompted.
- After the turn is over, send another message to the bot.
- Assure that you are not prompted again for your name. The bot should be reading it from the storage and recognize that it already prompted you.
- The bot should echo back your message.
- Go to your storage provider in Azure and verify that your name is stored as user data in the database.
Deploy the bot to Azure
To learn more about deploying a bot to Azure, see Deploy your bot to Azure for a complete list of deployment instructions.