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:

Variable Name	Purpose	Example Value
BUILD_NUMBER	Allows PockyBot to display the build number that is running when you ping it	102
VERSION_BRANCH	Allows PockyBot to display the version of the app that is running when you ping it	1.0.0
WEBEX_ACCESS_TOKEN	Used so that the app can connect and post to Webex Teams as the Bot	DFsSdfsdFhgiFg
BOT_ID	Used to filter the webhooks so that the Bot only responds to messages where it has been mentioned	Y2lzY29zcGFyadsdfEREr
BOT_NAME	Used to provide a human-readable name for the Bot and to name the webhooks	PockyBot
POST_URL	The url that the webhook will hit when a message that mentions the bot is created	https://example.com/pocky/respond
PM_URL	The url that the webhook will hit when a private message is sent to the bot	https://example.com/pocky/pm
PGUSER	The username of the database user set up for the bot	pockybotuser
PGPASSWORD	The password used to connect to the database	password
PGHOST	The url of the database for the bot information	postgres.example.com
PGDATABASE	The name of the database	pockydatabase
PGPORT	The port of the database	5432
GCLOUD_PROJECT_ID	The ID of the gcloud project where the bucket used to store results information is found	project-123
GCLOUD_PRIVATE_KEY_ID	The ID of the gcloud private key	a23c87b7127ab7d2
GCLOUD_PRIVATE_KEY	The private key required to connect to the gcloud bucket	-----BEGIN PRIVATE KEY-----\nMItestingtestingtesting23423\n-----END PRIVATE KEY-----\n
GCLOUD_CLIENT_EMAIL	Required to connect to the gcloud bucket	pockybot@project-123.iam.gserviceaccount.com
GCLOUD_CLIENT_ID	Required to connect to the gcloud bucket	382348239123
GCLOUD_CLIENT_CERT_URL	Required to connect to the gcloud bucket	https://www.googleapis.com/robot-/v1/metadata/x509/pockybot%40project-123.iam.gserviceaccount.com
GCLOUD_BUCKET_NAME	The name of the gcloud bucket being used to store the pockybot results	pockybucket

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:

Value	Default	Explanation
limit	10	The number of pegs each user is allowed to give out each cycle
minimum	5	The minimum number of pegs each user is required to give out to be eligible to win
winners	3	The number of winners displayed (using a dense ranking)
commentsRequired	1	Boolean value of whether a reason is required to give a peg
pegWithoutKeyword	0	Boolean value of whether the "peg" keyword is required to give a peg (if true, pegs can be given with @PockyBot @Person <reason>)
requireValues	1	Boolean value of whether a keyword is required in the reason for a peg to be given

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