In our post on ChatOps bot frameworks we discussed Hubot and how this widely forked project is a readily extensible mechanism for creating your own ChatOps bots. In this post we take a look at building such an extension in the form of a Hubot to help administer the Amazon API Gateway. We’ll walk through setting up a Hubot instance ready for the development of an extension, connecting the Hubot to Flowdock, and building an example integration with the Amazon API Gateway.

Goals

If you’re unfamiliar with the term, ChatOps is a philosophy to bring your productivity tools into a team chat environment, often through the use of a helpful bot framework like Hubot. There are many reasons why an organization might create such an extension; automating operational tasks, simplifying administration, creating easy-to-use interfaces for new applications, and so on. In the case of the Amazon API Gateway the goal of creating a bot is to implement a simple administration mechanism for managing API keys and assigning the keys to APIs. While these administrative functions obviously exist in both the API Gateway management console and the AWS CLI, they are somewhat unintuitive and could benefit from being “wrapped” in an easy to use management layer. In this context it’s worth noting a few details on the functionality of the Amazon API Gateway:

• Some navigation is required to find out information on your APIs and API keys via the console, and it’s not straightforward to gather that information onto one screen;
• The Amazon API Gateway has the concept of ‘stages’, designed to represent an internal promotional model with stages such as development, pre-production, and production. Like APIs and API Keys, navigating between stages and finding out information on each can be cumbersome;
• Dependent on the modularity of your API design the number of APIs defined in the API Gateway can grow quickly. Enabling API keys “in bulk” for a number of APIs can be manually intensive or time consuming unless you create scripts that call the CLI.

Creating a bot can therefore meet the objective of simplifying these administration features in a straightforward manner without creating a new user interface or multitude of scripts that require distribution and maintenance. Moreover, Amazon also offers a Node.js SDK, making the integration between the Hubot and the API Gateway very straightforward.

Getting Started

The first step in creating an extension is to generate a Hubot project in which to work, as described in the Hubot getting started guide. You can accomplish this by installing and running the Yeoman Hubot generator (assuming you already have node and npm installed):

npm install -g yo generator-hubot
mkdir gateway_bot
cd gateway_bot
yo hubot

The generator asks a number of questions to set up the Hubot (which can also be sent as command line arguments), such as the name of the Hubot and the adapter required. Adapters are the means by which Hubot connects to team collaboration and messaging platforms such as Slack and Yammer with the default shell adapter also available for working with a Hubot instance locally. In our walkthrough we are connecting Hubot to Flowdock in order to demonstrate an integration with a team collaboration tool. Similar to other team collaboration tools, there are a number of prerequisites for using Flowdock:

• A user profile must be available on Flowdock that allows the Hubot to connect with permission for the flows that the Hubot is required to listen to;
• The name of the user must match the name of the Hubot, otherwise the Hubot will not know it is being addressed in a conversation;
• You must set the username and password the Hubot will login with using the HUBOT_FLOWDOCK_LOGIN_EMAIL and HUBOT_FLOWDOCK_LOGIN_PASSWORD environment variables.

With these dependencies met you can execute the hubot script, passing the argument -a flowdock and the Hubot will listen to the flows that the account has permissions for:

$ ./bin/hubot -a flowdock --name gateway
[Tue Aug 16 2016 10:38:32 GMT+0100 (BST)] INFO Ignoring all messages from user ids 0
...

[Tue Aug 16 2016 10:38:34 GMT+0100 (BST)] INFO Flowdock: listening to flows: Test Gateway Bot

In the flow itself, you can now execute the help command, using the name gateway to address Hubot and see the list of default commands:

Help screenshot

Each of these commands references a module listed in either the npm packages.json file or external-scripts.json file in the root directory of the Hubot project: Along with the scripts directory, these are the mechanisms for controlling what Hubot modules are loaded (the load order and best practices of dependency management is documented in full here. You are obviously welcome to tailor these dependencies as required for your implementation (as not every organization wants pictures of pugs in their conversations :) ).

Building the Bot

With a working Hubot in place the next step is to start scripting. Hubot offers an easy-to-use CoffeeScript extension mechanism with clear guidelines on its use and a huge number of examples available in both Node Package Manager and the (now deprecated) Hubot Scripts project. As mentioned above, scripts are automatically loaded from the scripts subdirectory and an example (example.coffee) is provided to help guide you in your endeavors: Whilst there is a mechanism to turn anything you create into a package, editing a script directly in the scripts directory is almost certainly the easiest way of getting a feel for scripting Hubot extensions (using the packaging mechanism gives you the opportunity to write unit tests for your script so it may be a more appealing starting point if you are already familiar with Hubot).

The key to successfully implementing a Hubot extension is to ensure that your bot can react to the questions asked of it; this is accomplished using one of two methods:

• Hubot can “`hear“` messages said in a room and respond to the room;
• Hubot can also respond to messages asked directly by a single user.

The hear and respond methods also implement regular expression support, allowing you to be as explicit as you see fit in terms of the interactions the Hubot listens to and the code you implement to react to an interaction. With our API Gateway use case, the goal is to turn calls to the Node SDK into easy to use commands in Hubot; we directly address Hubot using the respond mechanism, reducing the scope of the integration to explicit commands from given users only. For example, to list all API keys a team member might ask gateway list api keys: To accomplish this the Hubot script needs to export a function that calls the getApiKeys method on the Node SDK and loops over the result, sending a message back to the user with the name, value, and state of each API key:

AWS = require('aws-sdk')

credentials = new AWS.SharedIniFileCredentials {profile: 'default'}

GTWY = new AWS.APIGateway({
  region: 'eu-west-1',
  credentials: credentials
})

module.exports = (robot) ->
  # List all API Keys
  robot.respond /list api keys/i, (msg) ->
    GTWY.APIGateway.getApiKeys (error, data) ->
      if error
        console.log error
        return msg.reply 'Error listing API keys, check the bot logs'

      else
        names = ('**' + k.name + '**: value = ' + k.id + ', enabled = **' + k.enabled + '**' for k in data.items)
        return msg.reply '\n' + names.join('\n') + '\n'

When addressed from Flowdock the results are displayed in the Flow:

List APIs screenshot

In this case Hubot has responded only to the user asking the question in an effort to limit the data visible across the flow for reasons of security.

Extending the Walkthrough

Moving from this simple example to a fully-fledged bot relies primarily on mapping the commands that make sense in the flow with the relevant AWS SDK functions. The Amazon API Gateway Hubot extension used in this walkthrough comes from an extension created by Ebury that is available on GitHub and from the Node Package Manager. The following commands are supported in the first release:

# Commands:
#   gateway list api keys - List all API keys for the gateway
#   gateway list api key  - List an API key with assigned APIs and stages
#   gateway create api key  - Create an API key with name of 
#   gateway [enable|disable] api key  - Enable or disable the API key with the name of 
#   gateway delete api key  - Delete the API key with the name of , requires confirmation
#   gateway confirm delete api key  - Delete API keys in list
#   gateway assign  to  for  stage - Assign an API key to an API for a given stage
#   gateway remove  from  for  stage - Remove an API key from an API for a given stage

Final Thoughts

Creating a Hubot extension for the Amazon API Gateway was a relatively trivial task, with the first working version completed in less than a day. It is an example of how a small development effort coupled with a feature-rich ChatOps framework can reap great rewards. The empowerment a bot can deliver in an operational environment is significant, allowing users to easily and efficiently automate or complete tasks with limited training or documentation, turning those tasks into part of their daily conversations.