codeforamerica / glossary-bot

A Glossary bot for Slack

Glossary Bot

Glossary Bot is a Slack bot that maintains a glossary of terms created by its users, and responds to requests with definitions.

It is a simple web app designed to be used as a Slack integration. Specifically, it responds to POSTs created by the Slack Slash Commands integration and responds with messages to Slack's Incoming Webhooks integration.

Deploy Glossary Bot

Glossary Bot is a Flask app built to run on Heroku. To deploy the bot using Heroku's automated setup, see below. To deploy or upgrade the bot from the command line, read DEPLOY. To install the bot locally for development and testing, read INSTALL.

Set Up on Slack

Glossary Bot uses two Slack integrations: Slash Commands for private communication between the bot and the user, and Incoming Webhooks for posting public messages.

Set up a Slash Command integration. There are three critical values that you need to set or save: Command is the command people on Slack will use to communicate with the bot. We use /gloss. URL is the public URL where the bot will live; LEAVE THIS PAGE OPEN so that you can fill this in after you've deployed the application to Heroku, as described below. Token is used to authenticate communication between Slack and the bot; save this value for when you're setting up the bot on Heroku.

Set up an Incoming Webhooks integration. The first important value here is Post to Channel, which is a default channel where public messages from the bot will appear. This default is always overridden by the bot, but you do need to have one – we created a new channel called #glossary-bot for this purpose. Save the value of Webhook URL; this is the URL that the bot will POST public messages to, and you'll need it when setting up Gloss Bot on Heroku.

Deploy on Heroku

Click the button above to get started. In the form that loads, add a name for your bot in the App Name field, or leave it blank to have Heroku generate a unique name. You won't see this name in Slack, it'll just be part of the URL that Slack uses to communicate with the bot behind the scenes.

Paste the Token from the Slash Command integration into the SLACK_TOKEN field and the Webhook URL from the Incoming Webhooks integration into the SLACK_WEBHOOK_URL field. Now click the Deploy for Free button to deploy the bot!

When it's done deploying, click the View button at the bottom of the form. A Method Not Allowed error page will load, but don't worry about that. All you're looking for is your bot's URL, which looks something like https://my-glossary-bot.herokuapp.com/. Copy that URL, paste it into the URL field of the Slash Command integration page on Slack, and save the integration there.

And now you're good to get glossing! Open up Slack and type /gloss help to start.

If you installed Gloss Bot on Heroku using the Deploy on Heroku button and you want to upgrade it with the latest changes, follow these instructions.

---

Learn about Code for America

Code for America believes government can work for the people, and by the people, in the digital age, starting with the people who need it most. We build digital services that enhance government capabilities, and we help others do the same across all levels of government. We organize thousands of volunteers across nearly 80 chapters nationwide who improve government in their local communities. Our goal: a 21st century government that effectively and equitably serves all Americans. Learn more at codeforamerica.org.

glossary-bot's Issues

create a heroku button for app deploy

as seen here: https://devcenter.heroku.com/articles/heroku-button

Add the ability to append definitions, to avoid overwriting other distinct valid definitions

If an acronym has more than one use, we currently have to be careful about overwriting preexisting definitions. What if we could just append another one?

/gloss TA

ta
Thanks, pronounced "taah" or "tar", depending on where you're from in the UK.

/gloss TA += TA: Technical Assistance

ta
Thanks, pronounced "taah" or "tar", depending on where you're from in the UK.
TA
Technical Assistance

stop using sqlalchemy

and just use psycopg2 directly

add support for docker deployment

based on @zoek1's fork https://github.com/zoek1/glossary-bot

hook up to travis and engine light

links in definitions not clickable in shh output

Some of our glossary definitions have links to view illustrations or jump to a web we're explaining an acronym for. So say if LMGTFY = Let Me Google That For You letmegooglethatforyou.com

a /gloss LMGTFY would display the definition and the .com at the end would be clickable and take you there.

a /gloss shh LMGTFY shows a italicized grayed-out slackbot response where it doesn't auto-link things.

Is this more of a Slack bug or a Glossbot bug? There's no way to insert clickable links in a Slackbot response is there?

tell who requested the definition

handle getting stats on an empty database

If you request /gloss stats on a completely empty database, you get a nonsensical reply. It should tell you that there are no entries.

Can't set definitions including equals signs in URLs

Gloss Bot rejects definitions that have equals signs in them, so a valid URL with equals signs in it can't be part of a definition. Instead, we could assume the first equals sign in a command is the operator and all following equals signs are part of the definition.

test webhook posts with responses library

Use the responses library to test webhook posts, instead of the convoluted HTTMock method I'm using now. See this code snippet for an example of how to do this.

don't assume the command for activiating Gloss Bot is /gloss

We get the command used to invoke Gloss Bot in the values posted by the slash command, so use it instead of hardcoding /gloss.

“shh” doesn’t work with term definitions

“Gloss Bot has set the definition for shh TERM to DEFINITION”

if they aren't already, wrap URLs in angle brackets before saving to database

This'll make them clickable when you receive them in quiet mode.

handle special characters like ™

Better error messages

If GB hits a server error, it should report something more useful to the requester than Error: Internal Server Error to make it easier to diagnose and fix the problem.

Use a google sheet as a datasource?

I was setting this up and it feels like the full postgres db instance is kind of overkill for a few short text phrases in most organizations. So naturally I thought about a single google spreadsheet as a datasource, using javascript to extract info from it.

This would have the following advantages:

• no need to fire up a full db
• easy data entry, most glossaries at companies might already exist in a spreadsheet
• easy updates by anyone on your team, outside of knowing slash command syntax

It carries some disadvantages:

• it's a google product that could vaporize at any time for any reason
• not designed for high traffic (or even medium traffic) uses, but if glossbot is only fired a few times an hour it's likely ok

I got the idea from Darius Kazemi, his site is powered by a Google spreadsheet.

The site: http://tinysubversions.com/projects/
The source data: https://docs.google.com/spreadsheets/d/1EDs10O223Hgm7gfFxTWsJpnKMPkGj7VEEZzZB8-wxfA/pubhtml
The source code for it: https://github.com/dariusk/projects

Seems like something that could reduce some installation friction and make for a more user-friendly way to view data in either Slack or Google Drive, plus make for easier data entry by more of a staff, no?

make set always overwrite the stored definition

...but have it tell you what you overwrote in case you change your mind.

Add support for dynamic information in definitions

It'd be cool to have URLs formatted in a certain way that told Gloss Bot to pull information from that URL and display it in place. For example I could set a definition like this:

/gloss FPL = Federal Poverty Level (currently $http://c4a.me/autofpl)

The $ in front of that URL would tell Gloss Bot to pull whatever text it found at that URL and display it as part of the definition:

FPL: Federal Poverty Level (currently $7,610 plus $4,160 per person in a family/household in the 48 contiguous states and DC; $9,520 plus $5,200 per person in Alaska; $8,770 plus $4,780 per person in Hawaii)

a new command to have Gloss Bot report on recent definitions?

You could /gloss recent to see the n most recently set definitions.

add a way to get all terms and definitions out of gloss bot's database

Suggested by Matt Grieser (twitter), who says he'd like to see the full list for curiosity's sake, and possibly to display on a plain markdown page in github.

fix static assets error in heroku push process

remote: -----> Preparing static assets
remote:        Collectstatic configuration error. To debug, run:
remote:        $ heroku run python ./manage.py collectstatic --noinput

add support for multiple definitions

Currently, Gloss Bot only allows you to set one definition per term. Instead, we could save multiple definitions per term and offer a relatively simple interface for manipulating them. So

/gloss EW = Eligibility Worker

Would get you the definition

EW
Eligibility Worker

Then

/gloss EW = Entertainment Weekly

Would show

EW
1. Eligibility Worker
2. Entertainment Weekly

Move a definition

/gloss move EW 2 to 1

EW
1. Entertainment Weekly
2. Eligibility Worker

Delete a definition

/gloss delete EW 1

EW
1. Eligibility Worker

Replace a definition

/gloss EW 1 = Entertainment Worker

EW
1. Entertainment Worker

Is it too complicated?

feature request: list-all action

I'd love it if there was a /gloss list-all feature that simply returned a comma delimited list of all defined words within glossary-bot.

nicer formatting for definition output

using message attachments

Bugs when trying to set definitions for command words – should it be possible?

Command words are set, delete, help, stats and shh and variations...any number of s's followed by any number of h's.

Right now you can successfully set the definition for help with /gloss help = testing but there's no way to retrieve it. Same thing with set and /gloss set set = testing; delete and /gloss set delete = testing; stats and /gloss set stats = testing; shh and /gloss set shh = testing.

It'd be easy enough to throw an error when trying to set the definition of a command word, but it feels weird to just have no way to set & get definitions for these words. But it'd also be weird to have some elaborate way of escaping command words when setting & getting definitions.

Proposed solution – formalize the behavior above: /gloss set <command> = <definition> will set a definition for a command word. The bot will tell the user how to do that if they seem to be trying to define a command word.

To get definitions, it will either understand from context (i.e. a command like /gloss set, /gloss delete or /gloss shh which don't make sense as commands) or require an explicit get, like /gloss get stats or /gloss get help.

Heroku deploy error when running scripts

Traceback (most recent call last):
  File "manage.py", line 40, in <module>
    manager.run()
  File "/app/.heroku/python/lib/python3.6/site-packages/flask_script/__init__.py", line 412, in run
    result = self.handle(sys.argv[0], sys.argv[1:])
  File "/app/.heroku/python/lib/python3.6/site-packages/flask_script/__init__.py", line 383, in handle
    res = handle(*args, **config)
  File "/app/.heroku/python/lib/python3.6/site-packages/flask_script/commands.py", line 216, in __call__
    return self.run(*args, **kwargs)
  File "/app/.heroku/python/lib/python3.6/site-packages/flask_migrate/__init__.py", line 244, in upgrade
    command.upgrade(config, revision, sql=sql, tag=tag)
  File "/app/.heroku/python/lib/python3.6/site-packages/alembic/command.py", line 254, in upgrade
    script.run_env()
  File "/app/.heroku/python/lib/python3.6/site-packages/alembic/script/base.py", line 427, in run_env
    util.load_python_file(self.dir, 'env.py')
  File "/app/.heroku/python/lib/python3.6/site-packages/alembic/util/pyfiles.py", line 81, in load_python_file
    module = load_module_py(module_id, path)
  File "/app/.heroku/python/lib/python3.6/site-packages/alembic/util/compat.py", line 82, in load_module_py
    spec.loader.exec_module(module)
  File "<frozen importlib._bootstrap_external>", line 678, in exec_module
  File "<frozen importlib._bootstrap>", line 205, in _call_with_frames_removed
  File "migrations/env.py", line 72, in <module>
    run_migrations_online()
  File "migrations/env.py", line 55, in run_migrations_online
    poolclass=pool.NullPool)
  File "/app/.heroku/python/lib/python3.6/site-packages/sqlalchemy/engine/__init__.py", line 466, in engine_from_config
    return create_engine(url, **options)
  File "/app/.heroku/python/lib/python3.6/site-packages/sqlalchemy/engine/__init__.py", line 425, in create_engine
    return strategy.create(*args, **kwargs)
  File "/app/.heroku/python/lib/python3.6/site-packages/sqlalchemy/engine/strategies.py", line 81, in create
    dbapi = dialect_cls.dbapi(**dbapi_args)
  File "/app/.heroku/python/lib/python3.6/site-packages/sqlalchemy/dialects/postgresql/psycopg2.py", line 584, in dbapi
    import psycopg2
  File "/app/.heroku/python/lib/python3.6/site-packages/psycopg2/__init__.py", line 50, in <module>
    from psycopg2._psycopg import (                     # noqa
ImportError: /app/.heroku/python/lib/python3.6/site-packages/psycopg2/.libs/libresolv-2-c4c53def.5.so: symbol __res_maybe_init version GLIBC_PRIVATE not defined in file libc.so.6 with link time reference

I've triple checked the SLACK_TOKEN and SLACK_WEBHOOK_URL values and both are correct and valid.

I tried deploying via command line but seem to have also encountered the same error:

➜  glossary-bot git:(master) heroku run python manage.py db upgrade -a glossary-bot
Running python manage.py db upgrade on ⬢ glossary-bot... up, run.7068 (Standard-1X)
Traceback (most recent call last):
  File "manage.py", line 40, in <module>
    manager.run()
  File "/app/.heroku/python/lib/python3.6/site-packages/flask_script/__init__.py", line 412, in run
    result = self.handle(sys.argv[0], sys.argv[1:])
  File "/app/.heroku/python/lib/python3.6/site-packages/flask_script/__init__.py", line 383, in handle
    res = handle(*args, **config)
  File "/app/.heroku/python/lib/python3.6/site-packages/flask_script/commands.py", line 216, in __call__
    return self.run(*args, **kwargs)
  File "/app/.heroku/python/lib/python3.6/site-packages/flask_migrate/__init__.py", line 244, in upgrade
    command.upgrade(config, revision, sql=sql, tag=tag)
  File "/app/.heroku/python/lib/python3.6/site-packages/alembic/command.py", line 254, in upgrade
    script.run_env()
  File "/app/.heroku/python/lib/python3.6/site-packages/alembic/script/base.py", line 427, in run_env
    util.load_python_file(self.dir, 'env.py')
  File "/app/.heroku/python/lib/python3.6/site-packages/alembic/util/pyfiles.py", line 81, in load_python_file
    module = load_module_py(module_id, path)
  File "/app/.heroku/python/lib/python3.6/site-packages/alembic/util/compat.py", line 82, in load_module_py
    spec.loader.exec_module(module)
  File "<frozen importlib._bootstrap_external>", line 678, in exec_module
  File "<frozen importlib._bootstrap>", line 205, in _call_with_frames_removed
  File "migrations/env.py", line 72, in <module>
    run_migrations_online()
  File "migrations/env.py", line 55, in run_migrations_online
    poolclass=pool.NullPool)
  File "/app/.heroku/python/lib/python3.6/site-packages/sqlalchemy/engine/__init__.py", line 466, in engine_from_config
    return create_engine(url, **options)
  File "/app/.heroku/python/lib/python3.6/site-packages/sqlalchemy/engine/__init__.py", line 425, in create_engine
    return strategy.create(*args, **kwargs)
  File "/app/.heroku/python/lib/python3.6/site-packages/sqlalchemy/engine/strategies.py", line 81, in create
    dbapi = dialect_cls.dbapi(**dbapi_args)
  File "/app/.heroku/python/lib/python3.6/site-packages/sqlalchemy/dialects/postgresql/psycopg2.py", line 584, in dbapi
    import psycopg2
  File "/app/.heroku/python/lib/python3.6/site-packages/psycopg2/__init__.py", line 50, in <module>
    from psycopg2._psycopg import (                     # noqa
ImportError: /app/.heroku/python/lib/python3.6/site-packages/psycopg2/.libs/libresolv-2-c4c53def.5.so: symbol __res_maybe_init version GLIBC_PRIVATE not defined in file libc.so.6 with link time reference
➜  glossary-bot git:(master)

Gloss Bot shouldn't suggest that you can set definitions for terms that contain equals signs

Instead of:

Sorry, but Gloss Bot has no definition for Dave = Corgi Nut. You can set a definition with the command /gloss set Dave = Corgi Nut = definition

it should say:

Sorry, but Gloss Bot has no definition for Dave = Corgi Nut. Gloss Bot cannot define terms that contain equals signs.

Do something useful on `/gloss` with no command

My first hunch upon hearing about /gloss is just to run it with no arguments. Ideally this would do something useful, like be an alias for /gloss help, perhaps?

extended help for individual commands

The learnings command has some modifiers that are currently undocumented and too numerous to document in the standard /gloss help response. There should be a modifier to help that lets you get extended help for individual commands, like /gloss help learnings

internal server error when trying to fetch

Definitions/stats/anything that requires fetching results in "Error: Internal Server Error" message

flesh out the readme with installation and running instructions

write tests

add database migrations

show helpful information when accessing bot's URL via web

Right now you get a Method Not Allowed error if you load Gloss Bot's URL in a web browser. Instead it should have some helpful info:

• next steps for people following the deploy instructions in the README
• basic 'what is gloss bot' info
• a link to this repo

more detailed logging

We should keep more detailed logs and use them to generate more interesting stats.

add link to these issues in Gloss Bot's help output

use newer features of Slack's slash command integration

Slack released some enhancements to its slash command integration a few months ago. You can now:

• style private messages
• respond publicly in a channel without requiring the incoming webhook integration

I definitely like the ability to style private messages and will add that. It may also fix the unclickable links bug.

A public response from a slash command makes you echo the command you typed publicly as well, which I think is uglier than the straightforward incoming webhook, so I may not change the way I'm doing it now.

if there's no exact match in the database, try a fuzzy search

Glossbot not respecting image and name overrides

Feature request: allow users to make an alias

Sometimes a company can have three names to describe the identical feature or functionality in an application. It would be nice if I could make a definition for a phrase like "direct message" also correspond to the phrase "DM" in the glossary.

Currently, I just make a duplicate entry for both phrases, but I wish there was a command to keep track of only one definition I can update/delete later rather than maintain multiple copies of the definition under different terms.

Ability to bulk import definitions?

Is there a way to manually insert definitions in bulk - through accessing the database directly?