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

  1. Clone the repository

    git clone https://github.com/microsoft/botbuilder-samples.git
    
  2. In a terminal, navigate to BotBuilder-Samples/Migration/MigrationV3V4/Node/V4V3-user-state-adapter-sample-bot

    cd BotBuilder-Samples/Migration/MigrationV3V4/Node/V4V3-user-state-adapter-sample-bot
    
  3. Run npm install in the following locations:

    root
    /V4V3StorageMapper
    /V4V3UserState
    
  4. Execute npm run build or tsc to build the StorageMapper and UserState modules in the following locations:

    /V4V3StorageMapper
    /V4V3UserState
    
  5. Configure the data base

    1. Copy the content od the .env.example file.
    2. Create a new file called .env and past the previous content into it.
    3. 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.
  6. Set the bot's storage provider

    1. Open the index.js file 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 .env file via Node process.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
          }
      }
      
    2. Specify which storage provider you want your bot to use by passing the storage client instance of your choice to the StorageMapper adapter (~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
      
  7. 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.

Connect to the bot using Bot Framework Emulator

  1. Launch Bot Framework Emulator.
  2. Enter the following URL (end point): http://localhost:3978/api/messages.

Testing steps

  1. Open bot in Emulator and send a message. Provide your name when prompted.
  2. After the turn is over, send another message to the bot.
  3. 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.
  4. The bot should echo back your message.
  5. 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.

Further reading