Skip to content
A Webex Teams Bot that handles team recognition
TypeScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.dependabot
.github/ISSUE_TEMPLATE
@types
database
src
.editorconfig
.gitignore
.travis.yml
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
README.md
commitlint.config.js
jasmine.json
package-lock.json
package.json
tsconfig.build.json
tsconfig.json

README.md

Pockybot 📍👏🏆🤖

Pockybot npm package Pockybot on Travis CI dependabot semantic-release Commitizen friendly

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
You can’t perform that action at this time.