My submission for the Chatbot competition is a service which allows users of the popular annual leave booking system TimeTastic to interact with it's API using Slack.

The motivation for the project was that wherever I've worked, booking holidays has been a pain. I can never remember how many days I have left for the year and getting approvals can be annoying. Timetastic solves some of these problems with a great web site and mobile app but I wanted to enhance it further with a bot, which feels like a natural way of booking time off.

I had to choose between hosting this service myself or allowing users to deploy it to their own AWS account. I went for the latter, because accessing TimeTastic requires an API token and I didn't want to have to store these tokens in my own infrastructure. However, this makes deploying the bot much more complicated. I like a challenge though, and have found a way to deploy all the necessary objects to AWS from a Node.js script. Importantly, the deployment script can also re-deploy the bot if you make any changes to the source (e.g. adding a new intent) without needing to delete the Lex-related objects first.

Functionality

Holibot provides the following intents

• CheckAllowance "How many days holiday do I have?"
• CheckMyHolidays "What holidays do I have booked?"
• RequestTimeOff "I need a holiday from Tuesday to 13th August"
• CheckApprovals "What approvals are outstanding?"
• Approve "Approve all [Alice's|Bob's|Colin's] holidays"
• WhosOutInDepartment "Who's out in sales today?"

Architecture

This repo contains a setup script with accompanying files to create the following objects in AWS:

• 6 Lex intents to cover the functionality above
• A slot type for department names which is gathered from Timetastic upon deployment
• A single Lambda function, which handles all of the intents
• The Lex bot itself and an alias
• Any necessary permissions on AWS

The (Node.js) setup script uses the following technologies to deploy Holibot:

• async to handle executing all the various asynchronous deployment steps synchronously in order
• commander and promptly to handle the command line options and validation
• lodash to perform various filtering and processing of collections
• the serverless framework to package up and deploy all the javascript files which make up the AWS Lambda hander function.
• the AWS Node.js SDK (of course)

Challenges encountered

I was suprised to find that the actual construction of the bot model in Lex was relatively straightforward once I had figured out the best ways to answer the various questions and interact accordingly with the Timetastic API. The hardest challenges in this project came from writing a script to actually deploy the bot. I had chosen the Serverless framework for packaging my Lambda handler function, but unfortunately Serverless does not support deploying Lex related objects. Neither does CloudFormation, so I had to write my own calls using the AWS SDK for Node.js to create the intents, slot types, bot and alias and apply the necessary permissions, as well as taking care of removing previous intents, slot types, aliases and bots in case the user was re-deploying. This re-deployment system was the hardest piece of all because I had to deal with asynchronous calls to AWS and making sure my commands were issued correctly in response to the output of the previous call. I made heavy use of the library 'async' to achieve this.

Testing instructions

• I've invited testing@devpost.com to my slack channel where you should be able to direct message @Holibot to test the interactions below.

• This user is also set up in a Timetastic account that will expire in 90 days.

Below is the original readme from my repo showing a user how to use Holibot.

Background and development info can be see

holibot

A Slackbot for booking annual leave in TimeTastic implemented in AWS Lex and Lambda. This is not a hosted service - everything in this repo allows you to create your own private bot using your own AWS account.

what do I need in order to use Holibot?

• A Slack account
• An AWS subscription
• A TimeTastic account

what can holibot do?

• request annual leave by chatting in Slack
• show your planned holidays
• approve holidays for others
• show your outstanding holiday allowance
• show who's off in various departments on a given day

how do I set it up?

First install the AWS command line utility, and configure it with an appropriate security token that has the permissions:

• lex - full control

• lambda - create / update functions

• In Slack create an application according to instructions here

• Clone this repository and run the command

npm install
node setup -t <your TimeTastic API token> 

You can get your Timetastic token here (having logged in already): here.

When the installation is complete you will have a bot configured for your TimeTastic account that you can proceed to add to Slack.

• In AWS, create a channel association for Slack to your newly created Holibot with the instructions here and here.

• In the Slack page for your bot app under Features > OAuth & Permissions you need to add the following permissions to allow Holibot to read the email addresses of your team: team:read, users:read, users:read.email

• You also need to grab the 'OAuth Access Token' from the same page.

• Add this token as an extra environment variable to the AWS Lambda function holibot-prod-handler called SlackToken.

• Back in your Slack app page under Settings > Manage Distribution click the 'Add to Slack' button.

Note: Users' email addresses must be the same in Slack as they are in Timetastic for Holibot to work.

Built With

• javascript
• node.js
• serverless