botbook/01 - Overview.md

Package Quick Reference

Whatsapp	Web	Core	KB
whatsapp.gblib	default.gbui	core.gbapp	kb.gbapp

The bot development stack

The Bot Factory

GeneralBots aims to delivery bots in azure in a very easy and fast fashion. Use Office tools like Word or Excel to edit your Bot - using code (JavaScript or TypeScript) just to empower custom requirements.

Use Excel for (Hierarchical) Knowledge Base Editing

Use Visual Studio for a complete .gbai package building system

How To

Run the server locally

1. Install Node.js the current generation General Bot code execution platform;
2. Open a Terminal on Linux and Mac or a Command Prompt window on Windows;
3. Type npm install -g botserver and press ENTER;
4. Type gbot to run the server core.

Notes:

• nodejs.install Chocolatey Package is also available.
• The zip source code of General Bot is also available for Download;

Configure the server to deploy specific directory

1. Create/Edit the .env file and add the ADDITIONAL_DEPLOY_PATH key pointing to the .gbai local parent folder of .gbapp, .gbot, .gbtheme, .gbkb package directories.
2. Specify STORAGE_SYNC to TRUE so database sync is run when the server is run.
3. In case of Microsoft SQL Server add the following keys: STORAGE_SERVER, STORAGE_NAME, STORAGE_USERNAME, STORAGE_PASSWORD, STORAGE_DIALECT to mssql.

Note:

• You can specify several bots separated by semicolon, the BotServer will serve all of them at once.

Setup development environment (Windows)

1. [Optional] Install Chocolatey, a Windows Package Manager;
2. Install git, a Software Configuration Management (SCM).;
3. Install Node.js, a Runtime system. (https://www.npmjs.com/get-npm) (suggested: LTS 8.x.x);
4. Install Visual Studio Code, Brackets or Atom as an editor of your choice;
5. Fork by visiting https://github.com/pragmatismo-io/BotServer/fork
6. Clone the just forked repository by running git clone <your-forked-repository-url>/BotServer.git ;
7. Run npm install -g typescript;
8. Run npm install on Command Prompt or PowerShell on the General Bot source-code folder;
9. Enter './packages/default.gbui' folder;
10. Run npm install folled by npm run build (To build default Bot UI);
11. Enter the On the downloaded folder (../..);
12. Compile the bot server by tsc.
13. Run the bot server by npm start.

Note:

• Whenever you are ready to turn your open-source bot ideas in form of .gbapp (source-code) and artifacts like .gbkb, .gbtheme, .gbot or the .gbai full package read CONTRIBUTING.md about performing Pull Requests (PR) and creating other public custom packages repositories of your own personal or organization General Bot Community Edition powered packages.

Running unit tests

1. Enter the BotServer root folder.
2. Run tests by npm test.

Just copy the source code to your machine

1. [Download] the Zip file of (https://codeload.github.com/pragmatismo-io/BotServer/zip/master)

Updating the Bot Knoledge Base (.gbkb folder)

The subjects.json file contains all information related to the subject tree and can be used to build the menu carrousel as well give a set of words to be used as subject catcher in the conversation. A hierarchy can be specified.

Creating a new Theme folder (.gbtheme folder)

A theme is composed of some CSS files and images. That set of files can change everything in the General Bot UI. Use them extensively before going to change the UI application itself (HTML & JS).

Package Types

.gbai

Embraces all packages types (content, logic & conversation) into a pluggable bot directory. A sample .gbai is available.

.gbapp

The artificial intelligence extensions in form of pluggable apps. Dialogs, Services and all model related to data. A set of interactions, use cases, integrations in form of conversationals dialogs. The .gbapp adds the General Bot base library (botlib) for building Node.js TypeScript Apps packages.

Four components builds up a General Bot App:

• dialogs
• models
• services
• tests

Dialogs

All code contained in a dialog builds the flow to custom conversations in built-in and additional packages .

Models

Models builds the foundation of data relationships in form of entities.

Services

Services are a façade for bot back-end logic and other custom processing.

Tests

Tests try to automate code execution validation before crashing in production.

.gbot

An expression of an artificial inteligence entity. A .gbot file defines all bots dependencies related to services and other resources.

.gbtheme

A theme of a bot at a given time. CSS files & images that can compose all UI presentation and using it a branding can be done. A sample .gbtheme is available

.gbkb

A set of subjects that bot knows in a form of hierarchical menu-based QnA. A sample .gbkb is available.

.gblib

Shared code that can be used across bot apps.

Reference

GeneralBots admin commands

General Bot can be controlled by the same chat window people talk to, so here is a list of admin commands related to deploying .gb* files.

Command	Description
deployPackage	Deploy a KB package. Usage deployPackage [package-name]. Then, you need to run rebuildIndex.
undeployPackage	Undeploy a KB. Usage undeployPackage [package-name].
redeployPackage	Undeploy and then deploys the KB. Usage redeployPackage [package-name]. Then, you need to run rebuildIndex.
setupSecurity	Setup connection to user directories.

Discontinued commands:

Command	Description	Reason
rebuildIndex	Rebuild Azure Search indexes, must be run after deployPackage or redeployPackage.	Now it is called automatically

Credits & Inspiration

• Rodrigo Rodriguez (me@rodrigorodriguez.com) - Coding, Docs & Architecture
• David Lerner (david.lerner@hotmail.com) - UI, UX & Theming
• Eduardo Romeiro (eromeirosp@outlook.com) - Content & UX.
• Jorge Ramos (jramos@pobox.com) - Coding, Docs & Architecture
• PH Nascimento (ph.an@outlook.com) - Product Manager

Powered by Microsoft BOT Framework and Azure.

General Bot Code Name is Guaribas, the name of a city in Brasil, state of Piaui. Roberto Mangabeira Unger: "No one should have to do work that can be done by a machine".