pockybot v1.6.0

Pockybot 📍👏🏆🤖

ARCHIVED

The pockybot project has been superseded by PockyBot.Net. Please visit that project instead.

Webex bot that handles team recognition. A chatbot for pegs & pocky.

What is Pegs & Pocky?

Pegs & Pocky was created within GlobalX as a merit-based system to encourage good behaviour and to continuously improve within our complex environment, so people are motivated to reach their full potential. It started out as a physical system of pegs and cups on everyone’s desk, however as our development team expanded interstate we needed an electronic system to include everyone. Here's how it works:

1. Participating members acknowledge good work by giving virtual "pegs" to other members within a specified time period.
   • Each member has a maximum number of pegs they can give out within that time period.
   • If they do not give at least a minimum number of pegs then they are not eligible for winning.
2. At the end of the time period the pegs are counted (an admin calls "finish" on the bot) and the winners are announced in the chat.
3. The top three peg recipients get physical rewards (Pocky and/or other snacks).

How it works

• Library used to set up a Webex Teams Bot
• Results are stored in a postgres database
• Pegs are viewable via html uploaded to google cloud

Setup

Using npm:

npm i pockybot

Using yarn:

yarn add pockybot

Usage

Environment Variables

The following environment variables must be set so that PockyBot can run properly:

Code

The following is example code showing usage of the bot with express in a typescript project:

import * as express from 'express';
import * as bodyParser from 'body-parser';
import { PockyBot } from 'pockybot';

// Constants
const PORT = 80;
const HOST = '0.0.0.0';

//Startup - note environment variables should already be set up when this is run
PockyBot.RegisterHooks();

// App
const app = express();
app.use(bodyParser.json()); // for parsing application/json

app.post('/respond', async (req, res) => {
    try {
        await PockyBot.Respond(req.body);
        res.status(200).end();
    } catch (e) {
        res.status(400).end();
    }
});

app.post('/pm', async (req, res) => {
    try {
        await PockyBot.PmRespond(req.body);
        res.status(200).end();
    } catch (e) {
        res.status(400).end();
    }
});

app.listen(PORT, HOST);

Database

database/initial-setup includes a number of .sql files to build the database as required by PockyBot.

Table generalconfig is initialised with default values as follows:

Table stringconfig is used to define keywords. Name field is 'keyword' and 'value' is the value of the keyword desired. Default keywords are 'customer', 'brave', 'awesome', 'collaborative', and 'real', shorthands for the GlobalX company values.

Existing roles are 'ADMIN', 'UNMETERED', 'RESULTS', 'FINISH', 'RESET', 'UPDATE', and 'WINNERS'. Users can have more than one role. Any users with the 'ADMIN' role are considered to have all other roles except for 'UNMETERED'. 'UNMETERED' users are not restricted by the usual 'limit' value from generalconfig. All other roles relate to the commands of the same name displayed below.

Commands

All commands related to PockyBot must begin with a mention of the bot, or be sent directly to the bot. In this readme, mentions will be identified by @PockyBot.

General commands

Use any of these commands in a room PockyBot is participating in to perform commands.

• @PockyBot status — get a list of pegs you have given this cycle.
• @PockyBot welcome — display a welcome message.
• @PockyBot ping — verify that the bot is alive.
• @PockyBot help — display a list of available commands.
• @PockyBot peg|to|at|for @OtherPerson <reason> — give a peg to @OtherPerson for <reason>.
  • If comments are required, a reason must be given. Otherwise, reasons are optional.
  • <reason> must include a keyword anywhere within it if keywords are required.
• @PockyBot keywords — display the available keywords.
• @PockyBot rotation — display the rotation of the order in which teams are responsible for buying snacks. This can be configured by adding a stringconfig with the name "rotation" and the value corresponding to a list of comma separated team names.
• @PockyBot unpeg @OtherPerson <reason> — pretend to remove a peg from @OtherPerson.
  • Use @PockyBot unpeg <concept> for <reason> to unpeg abstract concepts that can't be tagged.
• @PockyBot locationconfig get — get the list of available locations.
• @PockyBot userlocation — configure user locations (details below). Note that normal users may not configure locations for people other than themselves, but admins can access the full functionality of this command.
  • @PockyBot userlocation get me|all|unset|@User — get a user's location
  • @PockyBot userlocation set {location} me — set your location
  • @PockyBot userlocation delete me — delete your location

Direct message commands

PockyBot can be messaged directly with certain commands.

• status — get a list of pegs you have given this cycle.
• welcome — display a welcome message.
• ping — verify that the bot is alive.
• help — display a list of available commands.
• keywords — display the available keywords.
• rotation — display the rotation (see above).

Admin-only commands

These commands can only be performed by users with the role of 'ADMIN' or users with a role corresponding to the name of the given command.

• @PockyBot winners — display the current winners
• @PockyBot results — display the current full results
• @PockyBot reset — remove all pegs from the database
• @PockyBot update — update names stored in the database with users' current display names
• @PockyBot finish — complete the cycle by displaying the winners and results before wiping the database
• @PockyBot numberconfig get|set|refresh|delete {name} {number} — get or change config values
• @PockyBot stringconfig get|set|refresh|delete {name} {value} — get or change string config values
• @PockyBot roleconfig get|set|refresh|delete {@User} {role} — get or change user roles
• @PockyBot locationconfig get|set|delete {location} — get or change locations
• @PockyBot removeuser @User|username — remove a user
• @PockyBot userlocation — configure user locations as an admin (details below).
  • @PockyBot userlocation get me|all|unset|@User — get a user's location
  • @PockyBot userlocation set {location} me|@User1 @User2 — set one or more users' locations
  • @PockyBot userlocation delete me|@User1 @User2 — delete one or more users' locations
• @PockyBot locationweight get|set|delete {location1} {location2} {number} — get or change location weight configs

Contributing

For notes on how to contribute, please see our Contribution Guidelines.

Testing

1. npm install
2. npm test