botbuilder-storage

botbuilder-storage

An npm module, to be used with the Bot Builder SDK for Node.js, that adds several storage adapters to your toolkit. Configure your bot to automatically save conversation state data in either MongoDB, DynamoDB and Redis. Auto-cleanup is supported in the form of configurable TTL settings.

Installation

npm install --save botbuilder-storage

In addition, depending on the selected adapter, you will need to install another module to connect to either:

• MongoDB => npm install --save mongodb
• DynamoDB => npm install --save aws-sdk
• Redis => npm install --save redis

General Usage

To use any of the included adapters, you need to follow these three steps:

• Instantiate a client with any of the aforementioned dependencies.
• Create a storage adapter with the client and settings object.
• Configure the bot to use this newly created adapter.

Usage with MongoDB

To enable TTL (time-to-live) when using MongoDB, you will first need to create a TTL index on the "expireAt" field like this:
db.your_collection.createIndex( { "expireAt": 1 }, { expireAfterSeconds: 0 } )
The expireAfterSeconds: 0 means the inserted document will expire at the specific clock time as defined in the expireAt field.

For more information on this topic, visit the MongoDB docs.

// Example usage
// =============

// Import dependencies
const { MongoClient } = require('mongodb'); // v3.x.x
const { MongoBotStorage } = require('botbuilder-storage');

// Instantiate the bot with a connector instance
const bot = new UniversalBot(connector);

// Connect to your host
MongoClient.connect(host, (err, client) => {
        if (err) { throw err };
        
        // Define the adapter settings
        const settings = {
            // Required. This is the collection where all
            // the conversation state data will be saved.
            collection: "your_collection_name",

            // Optional, but recommended:
            // ==========================
            // Declare how long the state should be stored in seconds.
            // Should typically be a large value for the userData,
            // but can be kept small for the conversation related state.
            // Anytime a particular document, holding a specific type of
            // state, is modified, the time-to-live value will be renewed 
            // to avoid automatic deletion by MongoDB.
            ttl: {
                userData: 3600 * 24 * 365 // a year,
                conversationData: 3600 * 24 * 7 // a week,
                privateConversationData: 3600 * 24 * 7
            }
        }
        // Select the datebase with the client
        client = client.db('your_db_name');
        
        // Instantiate the adapter with the client and settings.
        const adapter = new MongoBotStorage(client, settings)
        
        // Configure the bot to use the adapter.
        bot.set('storage', adapter);
    });

Usage with DynamoDB

When using this module with Amazon's DynamoDB, the setup will be a little different compared to MongoDB.
Assuming you already have an AWS account, you will need to:

• create a table
• choose a primary key (just a partition key, no sort key needed)
• provision it with read and write capacity.

The easiest way to do this is through AWS' web-based console.

It is strongly recommended to enable TTL when using this module with DynamoDB. This is because, in DynamoDB, deleting many items at once on a table that only has a primary key without a sort key an no secondary index, is only possible by sending a single delete command per item. This is clearly not an ideal solution.

To enable TTL (time-to-live) when using DynamoDB, define a TTL attribute named "expireAt" like this:

// Example usage
// =============

// Import dependencies
const DynamoDB = require('aws-sdk/clients/dynamodb');
const { DynamoBotStorage } = require('botbuilder-storage');

// Instantiate the bot with a connector instance
const bot = new UniversalBot(connector);

// Create a DynamoDB client and select the AWS 
// region that hosts your instance of DynamoDB.
const client = new DynamoDB({ region: "us-east-1" });
    
// Define the adapter settings
const settings = {
    // Required
    tableName: "Botdata",
    // Required
    primaryKey: "id",
    // Optional but strongly recommended!
    ttl: {
        userData: 3600 * 24 * 365 // a year,
        conversationData: 3600 * 24 * 7 // a week,
        privateConversationData: 3600 * 24 * 7
    }
};

// Instantiate the adapter with the client and settings.
const adapter = new DynamoBotStorage(client, settings)
        
// Configure the bot to use the adapter.
bot.set('storage', adapter);

Usage with Redis

Using this module with Redis does not require any additional setup, but it should be noted that storing your bot's state data in Redis is only recommended when the bot does not need to save any state that should persist across different conversations with the user.

// Import dependencies
const redis = require('redis');
const { RedisBotStorage } = require('botbuilder-storage');

// Instantiate the bot with a connector instance
const bot = new UniversalBot(connector);

// Create a Redis client
const client = redis.createClient({ host, prefix: 'bot:state:' });

// Define the adapter settings
const settings = {
    // Optional but recommended!
    ttl: {
        userData: 3600 * 24 * 365 // a year,
        conversationData: 3600 * 24 * 7 // a week,
        privateConversationData: 3600 * 24 * 7
    }
};

// Instantiate the adapter with the client and settings.
const adapter = new RedisBotStorage(client, settings)

// Configure the bot to use the adapter.
bot.set('storage', adapter);

Further reading

To learn more about how your bot manages its state data and how you can control it, read this page from the Bot Framework documentation.

License

MIT