PockyBot.NET

A C# .NET Standard implementation of PockyBot.

Getting started

Bot Library

In order to use this bot, an implementation of GlobalX.ChatBots.Core is required. Install the library alongside this library and follow its configuration instructions.

Configuration

In order to use this bot, some configuration is required. This can either be done through appsettings.json, or at the time of configuring the bot.

Example Configuration

// In appsettings.json
{
    "PockyBot.NET": {
        "BotId": "id",
        "BotName": "BotName",
        "DatabaseConnectionString": "Host=postgres.host.com;Port=5432;Username=user;Password=pass;Database=pockybot;"
    }
}

Using Dependency Injection

In the ConfigureServices method of your Startup.cs file, add the following:

using PockyBot.NET;

public IServiceProvider ConfigureServices(IServiceCollection services)
{
    // Add other service registrations here
    services.ConfigurePockyBot(Configuration);
    return services;
}

If you have not provided your configuration inside appsettings.json, you may do so when you configure the bot:

using PockyBot.NET;
using PockyBot.NET.Configuration;

public IServiceProvider ConfigureServices(IServiceCollection services)
{
    // Add other service registrations here
    var settings = new PockyBotSettings
    {
        BotId = "id",
        BotName = "BotName",
        DatabaseConnectionString = "Host=postgres.host.com;Port=5432;Username=user;Password=pass;Database=pockybot;"
    };

    services.ConfigurePockyBot(settings);
}

You will also need to provide an implementation of IResultsUploader to upload the generated results to a location such as Google Cloud and return the link where those results are accessible.

using PockyBot.NET;

public IServiceProvider ConfigureServices(IServiceCollection services)
{
    // other service registrations
    services.AddTransient<IResultsUploader, MyResultsUploader>();
}

You will also need to inject logging classes. See this documentation for details.

Without Dependency Injection

You can get a concrete implementation of the library by calling the PockyBotFactory.CreatePockyBot method.

using GlobalX.ChatBots.Core;
using PockyBot.NET;
using PockyBot.NET.Configuration;

// Some code here

IChatHelper chatHelper; // An implementation of GlobalX.ChatBots.Core.IChatHelper
IResultsUploader resultsUploader; // An implementation of PockyBot.NET.IResultsUploader

var settings = new PockyBotSettings
{
    BotId = "id",
    BotName = "BotName",
    DatabaseConnectionString = "Host=postgres.host.com;Port=5432;Username=user;Password=pass;Database=pockybot;"
};

ILoggerFactory factory = new LoggerFactory().AddConsole(); // add any providers you want here
IPockyBot pockybot = PockyBotFactory.CreatePockyBot(settings, chatHelper, resultsUploader, factory);

Using The Bot

Once you have an instance of IPockyBot, you can use it to respond to a message like so:

using GlobalX.ChatBots.Core;
using PockyBot.NET;

Message message; // input from somewhere
IPockyBot pockybot; // initialised elsewhere

pockybot.Respond(message);

Database

PockyBot requires a postgres database. The database folder in this repository contains a number of .sql files you can use to set this up.

Table generalconfig is initalised 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', 'collaboration', 'amazing', 'integrity', and 'improvement', shorthands for the Dye & Durham company values.

Table stringconfig is also used to define linked keywords. Name field is 'linkedKeyword' and 'value' is the value of the keyword and a linked word, separated by a colon (e.g. 'amazing:awesome'). These are used to define other words that will act as one of the main keywords for validation and results purposes.

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 ping — verify that the bot is alive.
• @PockyBot peg @Person <reason> — give someone a peg.
• @PockyBot status — get the list of pegs you have given.
• @PockyBot help — get help with using the bot.
• @PockyBot rotation — get the snack buying rotation.
• @PockyBot welcome — welcome users.
• @PockyBot locationconfig get|add|set|delete <location> — manage locations.
• @PockyBot userlocation:
  • @PockyBot userlocation get me|all|unset|@User — get users' locations.
  • @PockyBot userlocation set <location> me — set your location.
  • @PockyBot userlocation delete me — delete your location.

Admin-only commands

These commands require special permissions to use.

• @PockyBot finish — get the results of the cycle.
• @PockyBot reset — clear all pegs from the last cycle.
• @PockyBot userlocation:
  • @PockyBot userlocation set <location> @User1 @User2 — set one or more users' locations.
  • @PockyBot userlocation delete @User1 @User2 — delete one or more users' locations.

Direct Message Commands

PockyBot can be messaged directly with certain commands.

• ping
• status
• help
• rotation
• welcome

Contributing

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