botbuilder-dynamodb-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.

Fork from

https://github.com/sebsylvester/botbuilder-storage

Installation

npm install --save botbuilder-dynamodb-storage

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

• DynamoDB => npm install --save aws-sdk

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.

About time-to-live (TTL)

All of the included adapters have configurable TTL support. This will act as a timeout for the stored data. After the timeout has expired, the state will automatically be deleted. But each time any state object is modified and saved by invoking session.save() in the dialog, that particular state will receive a new, recomputed expiration value based on the configured settings.

As shown in the example below, all values should express the number of seconds the state data should be stored, and a different expiration value can be defined for each type of state the bot manages. Since you would use userData to save state that persists across multiple conversations, you would typically want to assign a large value for that state. On the other hand, for conversationState and privateConversationState the duration could be kept significantly shorter.

store address for notify

const settings: {
    /* other settings */
    ttl: {
        // Assign values that express the number of seconds the date should be stored.
        // Each time state is updated, the affected object will receive a new TTL value.
        userData: 3600 * 24 * 365 // a year, expressed in seconds,
        conversationData: 3600 * 24 * 7 // a week,
        privateConversationData: 3600 * 24 * 7
    }    
}

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: "your_table_name",

    // Required
    primaryKey: "your_primary_key",

    // 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);

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