helpbot

README

helpbot

• helpbot
  • Current features
  • All available commands
  • Work in progress
  • Setup
    • Discord server setup
      • Bot Permissions
    • Creating a discord application and bot user
    • Inviting the bot to your server
    • Obtaining Discord IDs
    • Obtaining a GitHub access token
    • Configuring the bot
      • Automatic registration
      • Autograder support
      • Global configuration

A discord bot to help teaching assistants keep track of students who need help.

This bot manages a queue of students who request help from teaching assistants.

UiS Courses

We are hosting bot instances for courses on the UiS autograder (https://uis.itest.run/app/home). Please contact john.i.olsen@uis.no if you want to use this bot for your course.

Current features

• Students can request help using "!gethelp" or request approval of an assignment using "!approve"

• Students can cancel their request using "!cancel"

• Students receive a message when a teaching assistant is ready to help.

• Teaching assistants can get the next help request using "!next"

  • If the queue is empty, the teaching assistant will receive a notification when the next student requests help.

• Teaching assistants can view the queue.

• Teaching assistants can clear the queue.

All available commands

All roles:

• help - displays help text and a list of commands

No role:

• register - assigns the user a nickname and student role based on info from GitHub/Autograder

Student role:

• gethelp - assigns a teaching assistant to help the student, if available. Otherwise the student is put at the back of the queue.
• approve - same as gethelp, but meant to be used for assignment approvals.
• status - shows the student's current position in the queue
• cancel - cancels the help request (student is removed from the queue)

Teaching assistant role:

• next - the teaching assistant is assigned the next student in the queue. If empty, the teaching assistant will be "waiting", and will be assigned the next student who needs help.
• cancel - the teaching assistant can remove their "waiting" status.
• length - Returns the number of students waiting in the queue.
• list (n=10) - Returns the "n" next students in the queue.
• clear - removes all students from the queue.
• unregister (@mention student) - unregisters the mentioned student.

Work in progress

• Registration is halfway implemented:
  • Currently, new users can become "registered" by using the command "!register" and typing their GitHub username. The bot will then check if that GitHub username has access to the course's GitHub organization. If enabled, the bot will also get the student's real name from autograder.
  • In the future, this should be properly authenticated using Oauth either using the GitHub API, or by using Discord connections.
  • When the bot has confirmed that the user has access to GitHub/autograder, the bot will automatically assign a nickname and roles.

Setup

Discord server setup

Your discord server needs to provide two different roles: one for students, and one for teaching assistants. You should also ensure that the bot has read access to all of the text channels that it needs to be able to monitor. The bot can, however, operate entirely through direct messages (DMs), and this is the intended way for the bot to be used.

Bot Permissions

The bot needs to have the Manage Nicknames and Manage Roles permissions in order to support automatic registration.

Note: If your bot has a specific role in your server, you need to ensure that the bot role is above the students role, otherwise, the bot will not be able to manage roles and nicknames of students, and you will get permission errors. You can read more about the Role Hierarchies in the discord documentation.

Creating a discord application and bot user

Go to the Discord Developer Portal and create a new application. Next, click on the "bot" page and add a bot user. Here you can set the bot username and icon. You will also find the bot token, which is needed to start the bot.

Inviting the bot to your server

To invite your bot to your server, go to the Oauth2 page and check the bot scope. Then, enable the permissions as needed. Finally, copy the generated url and open the url in your browser. You will then be able to add the bot to your server.

Obtaining Discord IDs

The bot uses Discord IDs for configuration. You can find these by turning on developer mode in Discord settings:

You can then copy discord IDs by right clicking a role or a channel, for example:

You will need to copy the following IDs:

• The ID of the server itself - Right click the server name in the top-left corner of the discord window.
• The ID of both the student and teaching assistant roles - Right click the name of the role in the server settings.

Obtaining a GitHub access token

A github access token is needed for the bot to verify github organization memberships. To create a token, go to https://github.com/settings/tokens and click "Generate new token". Then, under scopes, select the read:org scope. Then click generate on the bottom of the page. Remember to copy the access token that is generated.

Configuring the bot

A config file must be named .helpbotrc. The default syntax is TOML. You may specify a different file extension, for example ".yml" or ".json" if you prefer a different markup language.

Discord IDs are obtained as explained above.

The following configuration variables must be set:

[[instances]]
db-path = "<path to sqlite database file>" # if empty, an in-memory database will be used
token = "<discord bot token>"              # the token that you got from the Discord Developer Portal
prefix = "!"                               # the prefix used before each command, for example !help
guild = <discord id>                       # the id of the server
student-role = <discord id>                # the id of the student role
assistant-role = <discord id>              # the id of the teaching assistant role

Automatic registration

The following configuration variables are needed to allow students to register by providing a github username associated with the course's github organization:

gh-token = "<github access token>" # github access token with `read:org` access to the relevant github organization
gh-org = "<github org name>"       # the name of the course's github organization

Autograder support

The follwing configuration variables are available to enable autograder support: Currently, we have to run the bot on the same physical server as autograder for this to work.

autograder = true             # enable autograder support for this instance
course-code = "<course code>" # the course code to use with autograder
course-year = 2020            # the year of the course

You can create multiple bot instances by adding several configurations, each beginning with [[instances]].

Global configuration

The following configurations apply to all instances

autograder = true             # enable autograder support

The following environment variable should be set before running the helpbot. This variable must the same as the token used by the QuickFeed server.

QUICKFEED_AUTH_TOKEN = "<quickfeed auth token>" # quickfeed auth token

Documentation

Index

• func OpenDatabase(path string) (db *gorm.DB, err error)
• type Assistant
• type Autograder
  • func NewAutograder(authToken string) (*Autograder, error)
  • func (s *Autograder) Close()
• type Config
• type HelpBot
  • func New(cfg Config, log *logrus.Logger, ag *Autograder) (bot *HelpBot, err error)
  • func (bot *HelpBot) Connect(ctx context.Context) error
  • func (bot *HelpBot) Disconnect() error
• type HelpRequest
• type Student

Functions

func OpenDatabase

func OpenDatabase(path string) (db *gorm.DB, err error)

Types

type Assistant

type Assistant struct {
	UserID      disgord.Snowflake `gorm:"primary_key"`
	Waiting     bool
	LastRequest time.Time
}

type Autograder

type Autograder struct {
	agpb.AutograderServiceClient
	// contains filtered or unexported fields
}

func NewAutograder

func NewAutograder(authToken string) (*Autograder, error)

func (*Autograder) Close

func (s *Autograder) Close()

type Config

type Config struct {
	Token         string            `mapstructure:"token"`
	DBPath        string            `mapstructure:"db-path"`
	GHToken       string            `mapstructure:"gh-token"`
	Prefix        string            `mapstructure:"prefix"`
	Guild         disgord.Snowflake `mapstructure:"guild"`
	StudentRole   disgord.Snowflake `mapstructure:"student-role"`
	AssistantRole disgord.Snowflake `mapstructure:"assistant-role"`
	GitHubOrg     string            `mapstructure:"gh-org"`
	CourseCode    string            `mapstructure:"course-code"`
	CourseYear    uint32            `mapstructure:"course-year"`
	Autograder    bool              `mapstructure:"autograder"`
}

type HelpBot

type HelpBot struct {
	// contains filtered or unexported fields
}

func New

func New(cfg Config, log *logrus.Logger, ag *Autograder) (bot *HelpBot, err error)

func (*HelpBot) Connect

func (bot *HelpBot) Connect(ctx context.Context) error

func (*HelpBot) Disconnect

func (bot *HelpBot) Disconnect() error

type HelpRequest

type HelpRequest struct {
	gorm.Model
	StudentUserID   disgord.Snowflake `gorm:"index"`
	Student         Student
	AssistantUserID disgord.Snowflake
	Assistant       Assistant
	Type            string `gorm:"index"`
	Done            bool
	Reason          string
	DoneAt          time.Time
}

type Student

type Student struct {
	UserID      disgord.Snowflake `gorm:"primary_key"`
	GithubLogin string
	Name        string
	StudentID   string
}