The CrowdCurio Bot Builder SDK

The CrowdCurio Bot Builder SDK provides the functionality necessary for building bots on the CrowdCurio platform. The primary purpose of the CrowdCurio Bot Builder SDK is to generalize the communication bridge between CrowdCurio and bot instances. The CrowdCurio Bot Builder SDK is built around the Microsoft Bot Framework.

Installation

The SDK is available through NPM:

    npm install crowdcurio-bot-builder

The CrowdCurioBot Class

The CrowdCurio Bot Builder library provides the CrowdCurioBot class, a lightweight and inheritable class implementation that handles the burden of interfacing with CrowdCurio and otherwise writing a range of boilerplate code.

One major feature of the CrowdCurio class is that it automatically keeps track of conversational state (i.e., task, experiment, condition, and data). In order for this to occur, CrowdCurio must send a POST request to /api/context specifying the necessary relational attributes. For more information, refer to /lib/bot-builder.js.

As a by-product of keeping track of conversational state, the CrowdCurioBot class affords developers with the ability to easily track and manage user's interface state with two attributes in a given conversation: state and meta. The state attribute should be used to reflect the global state of a shared interface. The meta attribute should be used to collect meta-information about the shared information.

Using the CrowdCurio Bot Builder

The one and only use-case for the CrowdCurio Bot Builder is supplying the CrowdCurioBot class as an extendable component. Extensions should primarily occur for two reasons:

1. Bot-specific dialog implementations.
2. Bot-specific handling of the state and meta fields.

For example, the creation of a simple "Hello World!" bot might look like the following:

// file: timbot.js
const CrowdCurioBot = require('crowdcurio-bot-builder');

// create a new Bot class that extends the CrowdCurioBot class 
class TimBot extends CrowdCurioBot {

    constructor() {
        super(); // *note*: this must be called!
    }

     // return a promise to ensure we know when the bot is ready to go.
    init() {
         const that = this;
         return new Promise(((resolve, reject) => {
         that.initialize().then(() => {
         // define a simple dialog that always responds with a static message.
             that.bot.dialog('/', (session) => {
             session.send('Hello World! I wish I was a Timbit.');
             });

             // start listening for messages
             that.serve();
             resolve();
         });
         }).bind());
     }
}

module.exports = TimBot;

And in a separate file:

// file: app.js
require('dotenv'); // to read environment vars from '.env'
const TimBot = require('timbot.js');

function main(){
    let timbot = new TimBot({
         // General Bot Instantiation Info.
         name: 'Tim',
         env: process.env.BotEnv,

         // Azure DB Authentication
         azureDBLogin: {
         host: process.env.AZURE_DB_HOST,
         user: process.env.AZURE_DB_USER,
         password: process.env.AZURE_DB_PASSWORD,
         },

         // CrowdCurio Bot Authentication Info.
         crowdCurioLogin: {
         username: process.env.CROWDCURIO_USERNAME,
         password: process.env.CROWDCURIO_PASSWORD,
         },

         // Microsoft Bot App ID and Password
         appId: process.env.MICROSOFT_APP_ID,
         appPassword: process.env.MICROSOFT_APP_PASSWORD,
    });

    // initialize and print a message when ready.
    timbot.init().then(function(){
        console.log("We're ready to go!");
    });
}  

 // kick off the main function
main();

With these two files, we can start the application with:

npm install
node app.js

Note: A functional bot will print a message or two indicating that it is, in fact, listening for incoming messages. For practical testing, please use the Microsoft Bot Framework Emulator.

Local Development

The CrowdCurio Bot Builder SDK makes heavy use of the Microsoft Bot Framework's DirectLineAPI to directly interface with bot applications. The DirectLineAPI is statically coded with web URLs that must be used to interface with any bot applications.

If you wish to have the CrowdCurio system interface with a locally running version of your bot, you should use ngrok. The ngrok CLI can be installed via npm:

npm i -g ngrok

After installation, you can start the ngrok service to get a valid URL for your locally running bot application.

ngrok http 9000

Testing

The repository uses Mocha, Chai, and Istanbul for unit-testing and code coverage metrics. Tests can be executed with: npm test.

Contact

Please direct all questions or comments to Alex Williams.