united

Slack channel overbooked? Make room for higher paying customers and crew in Slack.

© 2017 Jonathan Ballands

Usage

In the Slack channel you want to free up space in, invoke this slash command:

/united

This will call up the authorities to remove a random user from the Slack channel,
freeing up one spot. No need to feel bad about it! You’re just doing your job.

Installation

This repo is code for two AWS Lambda functions.
If you want to integrate this into your Slack team, follow the following steps:

Prerequisites

• An account with Amazon Web Services (AWS)
• Access to a (willing) Slack team where you can create internal integrations

Architecture

The following diagram illustrates from a high-level what we are trying to accomplish:

Setting Up Slack

united will be a simple Slack app that utilizes a slash command. We start by
creating the app and setting the correct permissions.

Note
You won’t be able to use united unless you are in a private channel if you
are not an admin for your team. If you would like to use this in a public
channel, ask your admin to perform this step.

1. In the Slack API, choose “Your Apps”, then “Create
   New App”. Name it something sensible (like “United”), choose a team, then choose
   “Create App”.

2. In the side bar, choose “OAuth & Permissions”. Under “Permission Scopes”, select
   the following permissions, then choose “Save Changes”:

   • Access information about user’s public channels. (channels:read)
   • Modify your public channels. (channels:write)
   • Access information about user’s private channels. (groups:read)
   • Modify your private channels. (groups:write)

Create Two New Lambdas

The next step is to take the code in this repository and upload it to AWS Lambda.
We will create two lambda functions, one called united-alert and one called
united-kick (but the names don’t exactly matter).

1. In AWS,
   under “Compute”, choose “Lambda”.

2. Choose “Create a Lambda Function”. You will do the next steps twice, once for
   each Lambda function:

   1. In the side bar, choose “Configure function”. Name your function something
      sensible (like united-alert or united-kick, as long as you can distinguish
      between the alert Lambda and the kicking Lambda). Ensure the runtime is set to
      “Node.js 6.10”.

   2. Under “Lambda function code”, in the “Code entry type” dropdown, choose
      “Upload a .ZIP file”. Choose “Upload”, and select the .zip file found in this
      repo from the file picker. If you would like, you can zip the code yourself by
      running the following Bash command within this repository:

       $ yarn && zip -r ./united.zip *

   3. Under “Lambda function handler and role”, choose an appropriate role that
      has at least the following policies (if you don’t have any AWS IAM roles,
      you’ll need to create one in AWS IAM that has these policies attached):

      • CloudWatchLogsFullAccess
      • AWSLambdaRole
      • AmazonAPIGatewayInvokeFullAccess

   4. If you don’t have any AWS IAM roles, you’ll need to create one in AWS IAM that
      has these policies attached.

   5. Uncollapse “Advanced settings”. Under “Timeout”, if this Lambda will be
      equivalent to united-alert, choose “5 secs”, and if this Lambda will be
      equivalent to united-kick, choose “15 secs”.

   6. Choose “Next”. Review your settings, then choose “Create function”.

Give Access To AWS Lambda Via AWS API Gateway

When someone invokes /united in Slack, Slack will send a POST request to
whatever backend you specify and expect a result. Here, we will use AWS API
Gateway to forward POST requests to your Lambda.

1. In AWS,
   under “Application Services”, choose “API Gateway”.

2. Choose “Create API”. Name it something sensible that you can use for all of
   your future Lambda microservices, then choose “Create API”.

3. Choose the root of the API. Create resources under the root until you have a
   structure resembling /slack/united:

   • Choose “Actions”, then “Create Resource”.
   • Name your resource “Slack”, then choose “Create Resource”.
   • Select the /slack resource, and create another resource called /united.

4. Choose the /united resource, choose “Actions”, then “Create Method”.
   Choose “POST” from the dropdown, then choose the tick.

5. Ensure “Integration type” is set to “Lambda Function”, and choose the region
   your united-alert Lambda function is located from the dropdown (it’s usually
   us-east-1). A new text box will appear. Type the name of the united-alert
   Lambda function, then choose “Save”. Your resource tree should look like this:

   

6. When Slack sends a POST request, it’s going to do so using
   application/x-www-form-urlencoded, which is something API Gateway can’t handle
   out of the box. Let’s fix this:

   1. From the flowchart, choose “Integration Request”.
   2. Decollapse “Body Mapping Templates”, under “Request body passthrough”,
      choose “When no template matches the request Content-Type header”.

   3. Under “Content-Type”, choose “Add mapping template”. Paste the following
      code into the text field (this will allow you to access the url encoded arguments
      via postBody in your Lambda function, where you can use snazzy Node libraries
      to parse it):

       {
           "postBody" : $input.json("$")
       }

   4. Choose “Save”.

7. Choose the / resource, then choose “Actions”, then choose “Deploy API”.

8. Under “Deployment stage”, choose “[New Stage]”. Name the new stage something
   sensible (like “prod”), then choose “Deploy”.

9. You’ll be taken to the “Stages” tab in the side bar. Note the URL. This is the
   URL you’ll use to hit your Lambda function.

Allow Slack & AWS Lambda To Talk

Your access token is a special string of characters that allows access to your app
using the permissions we described above. In this step, we will configure an
environment variable for your Lambda functions that contain the encrypted access
token.

WARNING
Never share your access token with anyone. Never commit or hardcode access
tokens. Always encrypt access tokens and secrets, even ones stored in an
environment variable.

1. In the Slack API, choose “Slash Commands”. Choose
   “Create New Command”.

2. Type “/united” for the new command. If you followed my steps perfectly, your
   URL will be the base that was given to you at the last step of the last section,
   plus /slack/united. Adjust this to how you set it up.

3. Give a good description (I like “Make room in an overbooked Slack channel for
   higher paying customers and crew.”), then choose “Save”.

4. In the side bar, choose “Install App”, then choose “Install App”. This will
   perform the OAuth within Slack. Authorize the app.

   

5. You will be given an access token. Copy it to your clipboard.

6. In AWS, go
   to AWS Lambda and for both Lambda functions:

   1. Under the “Code” tab, under “Environment variables”, create a new variable
      whose key is ACCESS_TOKEN and whose value is your access token.

   2. Tick the “Enable encryption helpers” box. Under “Encryption key”, choose an
      appropriate KWS key, then choose “Encrypt”. If you don’t have a key, you will
      need to access AWS IAM to make one.

   3. If this is the united-alert Lambda function, create a second variable
      whose key is KICK_LAMBDA_NAME and whose value is the ARN of your united-kick
      Lambda function.

   4. Choose “Save”.

Test

You should now be able to use /united in a Slack channel and watch it work.
Congrats! If it doesn’t work, here are some common reasons:

You didn’t encrypt your access token correctly.
You must encrypt your access token for both Lambda functions using a KWS key from
IAM.

You didn’t set up your API correctly in API Gateway.
Ensure the method for your endpoint is set to POST and that the you used the
mapping template described in this README.

Your Slack permissions aren’t correct.
Use the Slack permissions described in this README.

Your IAM role has the wrong policies attached.
Use only the policy templates described in this README.