Prism

What is Prism? A framework that leverages the Microsoft bot framework to accelerate chatbot development. Prism dynamically generates dialogue flows, schedule tasks and CLI styled commands based on content originated by the Prism IDE. Prism uses an open source node-NLP library to make intent recognition simpler and provides the feature to use external NLPs with very little coding.

Prism is currently used to prototype chatbots internally. We are continuing to enhance Prism and developing a unit test suit. Please use it as you see fit. We'd love to have you participate in enhancing the asset and help develop unit test cases for Prism!

Low code
Easy to publish
Scheduler for running tasks at a specified time

Using Prism

Currently the prism library is not in npm so if you wish to make changes to it and build your own implementation you will have to install from a tgz. After cloning this repo you can run npm pack which will create a prism-${version}.tgz from your implementation project, you can run npm i ${prism-location}/prism-${version}.tgz

Prism Bot directory layout

.
├── package.json
├── prism-bot                   # Common folder containing prism-bot structure
├──── data.json                 # File containing prism-bot configuration
├──── main.js                   # Optional file to run when the bot starts
├──── interceptor.js            # Optional file to run between all received messages
├──── intents                   # Folder containing intents
├────── intent-x                # Folder containing intent-x data
├──────── data.json             # File containting intent-x configuration
├──────── code                  # Folder containing code relevant to the intent-x
├────────── node-x-before.js    # Code to be ran before node-x
├────────── node-y-after.js     # Code to be ran before node-y
├────── intent-y                # Folder containing intent-y data
├──────── data.json             # File containting intent-y configuration
├──────── code                  # Folder containing code relevant to the intent-y
├────────── node-a-before.js    # Code to be ran before node-a
├────────── node-a-after.js     # Code to be ran after node-a
├──── tasks                     # Folder containing tasks
├────── task-x                  # Tools and utilities
├──────── data.json             # Folder containing task-x data
├──────── code.js               # Code to be ran when the task is executed
├──── commands                  # Folder containing commands
├────── command-x               # Folder containing intent-x data
├──────── data.json             # File containting command-x configuration
├──────── code.js               # Code to be ran when the command is executed
└── README.md

Bot

prism-bot/data.json

Field	Type	Description
speakSlow	`boolean`	If true, the bot will type at a rate based on the length of the message
isMainEnabled	`boolean`	Whether the bot should load in `main.js`
isInterceptorEnabled	`boolean`	Whether to intercept all messages or not
isIntentsEnabled	`boolean`	Whether to use intents
isUtterancesEnabled	`boolean`	Whether to use utterances within intents
isCommandsEnabled	`boolean`	Whether to use commands
isCommandsHelpEnabled	`boolean`	Whether commands should use the default `!help` command
commandPrefix	`string`	The prefix for all commands, i.e. `!`
isTasksEnabled	`boolean`	Whether to use tasks
defaultIntentId	`string`	Id of the intent to use if the bot doesn't know how to respond
triggerOnJoinIntentId	`string`	Id of the intent to use when the user joins the conversation

Interceptor Code Example

console.log('Intercepted!');

if (session.message.text == 'chicken') {
    await send('chicken is great!');
    return reject(); // prevents the bot from processing this message
} else if (session.message.text == 'bacon') {
    await send('bacon is great!');
    session.endConversation(); // cancels existing conversation
    return reject(); // prevents the bot from processing this message
}
return resolve(); // allows the bot to see the message and to attempt processing it further

Main Code Example

This code is ran once after the bot has been inialized.

console.log('Main!');

const express = require('express');
const app = express();
const port = 9443;

app.get('/', (req, res) => {
    res.send('Hello!');
});

app.listen(port, () => {
    console.log(`Server running on port ${port}!`);
});

Main Code Variable

variable	purpose
intentDialog	See Microsoft Bot Builder 3.7.0
universalBot	See Microsoft Bot Builder 3.7.0
commander	If you want to add more advanced commands using the `bot-commander` library
cwd	The directory of `prism-bot`
recognizer	You can do more advance nlp traing using the `node-nlp` library

Intent

prism-bot/intents/${name}/data.json

Field	Type	Description
id	`string`	Identification for the intent
name	`string`	Name of the intent
isEnabled	`boolean`	Whether the intent should be used
triggers	`Trigger[]`	Array of triggers to use,
utterances	`Utterance[]`	Array of utteranecs to use,
nodes	`Node[]`	Array of nodes to use

Intent 🡢 Trigger

Triggers are regular expressions to force an intent to run

Field	Type	Description
id	`string`	Identification for the trigger
name	`string`	Regular expression for the trigger. i.e. `quit`

Intent 🡢 Utterance

Utterances are used to train the node-nlp library for determinging the intent to use

Field	Type	Description
id	`string`	Identification for the Utterance
name	`string`	Value for the utterance. i.e. `How are you today`

Intent 🡢 Node

Nodes are used for determining the conversational flow

Field	Type	Description
id	`string`	Identification for the Node
type	`string`	The Node Type ie. `start` or `input.date` See below for more options.
variable	`string`	Used to store the input value. This is basically the same as calling `setVariable('key', 'value');` and the variable can be accessed later via `var x = getVariable('key');`
defaultNodeId	`string`	The next node to run unless specified otherwise in the on after/on before code
text	`string`	The text to ask/say unless changed within the `on before code`
referenceIntentId	`string`	Value for the utterance. i.e. `How are you today`
states	`State[]`	Array of states to use.
answers	`Answer[]`	Array of answers to use
codeBeforeFile	`string`	Code file to run before the node runs. This is referred to as `on before code`. This is relative to the `prism-bot/intents/intent/${name}/code` folder. ie. `node-x-before.js`
codeAfterFile	`string`	Code file to run after the node runs. This is referred to as `on after code`. This is relative to the `prism-bot/intents/intent/${name}/code` folder. ie. `node-x-after.js`
isCodeBeforeEnabled	`boolean`	Whether to use `on before code`
isCodeAfterEnabled	`boolean`	Whether to use `on after code`

Intent 🡢 Node 🡢 type

Node Types

Type	value	Description
Start	`start`	The entry point of a conversation
Plan	`plain`	Useful for just running code
Reference	`reference`	Moves to another intent
Input Date	`input.date`	Gets a date value from the user
Input Multiple Choice	`input.multipleChoice`	Makes the user answer a multiple choice question
Input Number	`input.number`	Retrieves a number from the user.
Input Text	`input.text`	Retrieves text from the user.
Input Yes/No	`input.yesNo`	Forces the user to answer a question
Output Text	`output.text`	Sends text to the user

Intent 🡢 Node 🡢 Answer

Node Answer

Field	Type	Description
id	`string`	Identification for the Answer
name	`string`	Display value of the answer
nextNodeId	`string`	Node to run if this answer is chosen
order	`number`	How to order the answers, otherwise they will be sorted alphabetically

Intent 🡢 Node 🡢 State

Node State

Field	Type	Description
id	`string`	Identification for the State
name	`string`	name of the state, this can be used in `on before code` or `on after code` by using `resolve('stateName')` or `reject('stateName')`
nextNodeId	`string`	Node to run if this state is chosen

Intent 🡢 Node 🡢 `on before code` + `on after code`

These functions are wrapped in the vm library and called using runInNewContext. As such, the code is wrapped in an asynchronous function declarataion so you can call await and run your call linearly without additional setup.

- Make sure to call resolve() or reject() within any on after or on before code, otherwise the bot will not be able to move on.
- Also make sure to only call resolve or reject once within your code, otherwise strange things might happen.

Function	Description
`reject()`	Ends the conversation and calls `session.endDialog()`
`setVariable(name:string, value:any)`	Set a variable about the user with a conversation context
`getVariable(name:string)`	Get a variable about the user with a conversation context
`setConversationVariable(name:string, value:any)`	Set a variable about the conversation without a user context
`getConversationVariable(name:string)`	Get a variable about the conversation without a user context
`setUserVariable(name:string, value:any)`	Set a variable about the user without a conversation context
`getUserVariable(name:string)`	Get a variable about the user without a conversation context
`send(value:any)`	Sends an object or string to the user. If you wish to time messages, this function returns a promise so be sure to use `.then` or an `await`
`email(value:any)`	Built in function to email somebody using nodemailer assuming you can talk directly to a mail relay. This can be set with `process.env.MAIL_HOST` or you can override the transporter with `PrismUtil.setMailTransport(transporter)`
`promiseGet`	Helper function for turning a `request.get` into a promise
`promisePost`	Helper function for turning a `request.post` into a promise

Variable	Description
session	See Microsoft Bot Builder Session 3.7.0
userData	The object representing what we remembered about the user equivalent to session.userData
builder	Reference to `require('botbuilder')`

Intent 🡢 Node 🡢 `on before code`

Function	Description
`resolve(stateName?:string)`	Moves on to the next node. `stateName` can be used to direct the next node.

For an input node, you can resolve() or resolve(stateName/answerName) and declare skip = true; to skip the input portion of a question. For an input node, you can dynamically set the prompt using prompt = 'This is a question'; For an input node of type multipleChoice, you can dynamically set the answers by using results = ['red', 'blue', 'green'];

Intent 🡢 Node 🡢 `on after code`

Function	Description
`resolve(stateName?:string)`	Moves on to the run portion of a node.
`getResponse()`	Used for Input nodes in the on after portion. This lets you get the value without declaring a variable

Send Example

await send('Hello, lovely weather we are having!');
await send('this is a really really really really really really really really really really really really really really really long message.');
await send('well then');
return resolve();

Email Example

await email({
    from: '"John Doe" <john.doe@mail.com>',
    to: 'jane.doe@mail.com',
    subject: 'Hello',
    text: 'Hello world?',
    html: '<b>Hello world?</b>'
});

await send('Email was sent!');

return resolve();

Set Variable Example

setVariable('food', 'bacon');
return resolve();

Get Variable Example

var x = getVariable('food');
send('Food:' + x);
return resolve();

Get Response Example

// On After of an input node
var answer = getResponse();
console.log(answer);
return resolve();

promiseGet Example

The raw flag will return the actual response with error, response, and body objects. otherwise it is always just the body.

let response = await promiseGet({
    url: 'https://some made up url/api/resource',
    json: true
}).catch(()=>{});
console.log(response);
// { "id" : "pretend-id" }

let response = await promiseGet({
    url: 'https://some made up url/api/resource',
    json: true,
    raw: true
}).catch(()=>{});
console.log(response);
// { error : OBJECT, response : OBJECT, body : OBJECT }

promisePost Example

let response = await promiseGet({
    url: 'https://some made up url/api/resource',
    json: true,
    body: {
        data: {
            id: '123'
        }
    }
}).catch(()=>{});
console.log(response);
// { "id" : "pretend-id" }

Command

This functionality extends the node library bot-commander

If you wish to use more advanced commands, you can initialize then in the main.js file by referencing the variable commander.

prism-bot/commands/${name}/data.json

Field	Type	Description
id	`string`	Identification for the command
name	`string`	Name of the command
description	`string`	Description to show up when the user types `!help`
isEnabled	`boolean`	Whether the command should be enabled
isHelpEnabled	`boolean`	Whether the command should show up when the user types `!help`
options	`Option[]`	Array of options to use
codeFile	`string`	Name of the code file relative to `prism-bot/commands/${name}` ie. `code.js`

Command 🡢 Option

Option are regular expressions to force an intent to run

Field	Type	Description
id	`string`	Identification for the option
flags	`string`	Check out `Option parsing` within `bot-commander` ie. `-c, --cheese [type]`
description	`string`	Description to show up when the user types `!help`
defaultValue	`string`	Value to use for a flag if the user does not specify otherwise

Command 🡢 `code`

This code has access to the same variables and funtion as the on before code and on after code with the exception that you do not have to call resolve or reject

Code Example

send('You just ran me!');

Task

This functionality extends the node library node-schedule

prism-bot/tasks/${name}/data.json

Field	Type	Description
id	`string`	Identification for the task
name	`string`	Name of the task
schedule	`string`	This field uses Cron-style Scheduling. ie `/5 * * *` will run every 5 minutes
isEnabled	`boolean`	Whether the command should be enabled
codeFile	`string`	Name of the code file relative to `prism-bot/tasks/${name}` ie. `code.js`

Task 🡢 `code`

This code is not tied to a users session although you do get access to the universalBot and intentDialog objects so you could load the users session and do some more complicated logic.

Code Example

console.log('task was ran');

Loading a users session when not in the session

let address = {
    channelId: 'rocket',
    user: {
        id: 'some-user-id' 
    },
    conversation: {
        id: 'some-conversation-id'
    }
};

universalBot.loadSession(address, (err, session) => {
    session.send('This long task finally finished!');
});

User

In the code that has a session, ie. on before code, on after code and commands you can access the user id via session.message.address.user.id.

You can also access the user value by just calling user from within the code.

If you want to access the raw user object, do so by session.message.address.user

var userId = session.message.address.user.id; // some-id
var userId2 = user.id; // some-id

If Active Directory is enabled, you also get access to the whole user object from active directory via session.message.address.user.ad

Note that the user variable in the session code has been replaced with the active directory user instead of the channel user.

var userCN = session.message.address.user.ad.cn; // doeJohn
var userCN = session.message.address.user.id; // some-id
var userCN2 = user.cn; // doeJohn
var userId = user.id; // undefined

Sample AD User Object

 {
     dn: '...',
     cn: '...',
     sn: '...',
     postOfficeBox: '...',
     telephoneNumber: '...',
     givenName: '...',
     distinguishedName: '...',
     displayName: '...',
     memberOf: [
         '...',
         '...'
     ],
     department: '...', 
     displayNamePrintable: '...', 
     name: '...', 
     '...': '...'
 }

Prism Development

npm i installs the dependencies locally npm dev runs a live reloading bot that lives in examples/server/index.ts using ts-node-dev

varnem2/prism