The 5 Steps in a Build-to-Learn Project: MDNbot’s coding journey

Table of Contents:

1. Intro
2. Planning
3. Environment setup
4. Development
5. Deployment

1 — Intro

This is the story of 3 belugas: Jasmina Babic, Erik and myself, Veronica Mihai (4 initially, but one of us unexpectedly left the team) and their adventure in the land of chatbots. How did it all start? In a Chingu Cohort of course

CHINGU

If this is your first time hearing about this, do check them out. Especially if you already are a freecodecamper.

Learn to code and help nonprofits

They make for a wonderful remote study group. And if you are not, then maybe you’ll want to become one after you learn about their projects and the role they play in the world of free online education for aspiring web developers.

Project Idea

The homework was to build something similar to the GFDA slackbot and replace the profanity design advice with a content to our own liking. After receiving precious instructions about how to:

• coordinate our remote team meetings using spacetime
• approach our first planning session
• ensure the project livelihood by assigning one or two of us in the role of project facilitator (something like a junior Project Manager, project manager was too frightening of a title :D)

we proceeded to choosing our chatbot’s purpose in life.

Without further ado, let’s dive right into what this challenging experience of building a chatbot has been like for each one of us.

2— Planning

First meeting

There were a few hurdles to overcome before actually getting to have our first meeting. Too many notifications going around in the cohort’s slack team made my question about when to have a meeting pass unnoticed by some of my colleagues. We got on the same page eventually and set up a day and an hour. Luckily the time difference between our time zones was of only 1 hour and we didn’t have to do complicated math to figure out when each of us would be online.

After one colleague asked me a day before the meeting if we were having the meeting now because she rushed home to join us, I felt a bit guilty for not making the day and hour of the meeting clearer and decided to send meeting invites using google calendar from now on. That was pretty neat because google calendar automatically converts the meeting time to each user’s timezone, so I was at peace knowing no one will show up at the wrong time of the day :).

Then there was the question of what remote meetings technology to use for the meeting. Will we use Google Hangouts, Screenhero or something else? Screenhero doesn’t work on Linux and not everyone had google accounts and besides how do you have a voice conference with more than two people on google hangouts anyway? We used slack chat for our first meeting because of logistics issues and afterwards one of our colleagues suggested we use talky.io. This suited us well because it works out of the box without any need for passwords. We could all hear each other and share our screens. Plus I got to play landing a space rocket while waiting for people to join the meeting :D.

Chatbot purpose

While I was still confused about whether we still need to keep the design advice theme or not, Jasmina came with the idea of using the MDN search API ,which we all instantly agreed to without objections. I agreed too, but only after I figured out what MDN actually meant ( not that I didn’t use it before or anything).

How to build it

We were given a few links about what technologies could be used to build a slackbot. Basically the options were to use Node.js with Express and the Realtime messaging API from slack. There were some frameworks built around this API to make our lives easier, some of them were botkit and node-slack-sdk. Jasmina proposed claudia bot builder as an option and as a good agile team in the becoming we decided we’ll do more research for the next meeting and gave ourselves a lot of flexibility around deciding which technology to go with.

We made some other decisions around tasks management tools. Whether to use kanbanflow or trello. We decided to go with kanbanflow thanks to the simpler UI, even if everyone already had signed up for accounts on more tools than they could keep track of.

We discussed a bit also which chat platforms to target, whether there’d be any use for our MDN Bot on platforms like facebook and twitter that aren’t used specifically for development. And we concluded we’ll start with slack first and decide afterwards if we want to have it on other platforms as well. We made a quick summary of what we discussed and decided the time for our next meeting. I also got assigned the task of writing up our User Stories.

Github repository

I proceeded to creating a new github repo where we would be able to collaborate on the code. As I haven’t been working in open source teams before, the only way of collaborating on projects on Github that I was aware of was by creating a repo in my own account and inviting people as collaborators. There is another way, as one of my colleagues gently pointed out, and that is by creating a Github Organization. So Jasmina took care of creating it and she also came up with our team name from our first names two initial letters, VEJATHER.

User Stories and Other Requirements

These are the user stories I came up with for our next meeting.

1. As a user I can access a random MDN page with the command /mdn-bot (or by clicking a “next” button in the chat user interface ? ). Optional allow user to select skill level, Beginner, Intermediate or Advanced, and resource type Example, Guide, or Tools.
2. As a user I can access the summary of a specific MDN page within a specific topic with the command /mdn-bot searchTerm searchTopic (skill level resource Type -optional, default everything ) and get a link to the full page.
3. As a user I can access help information with the command /mdn-bot
4. As a user I can install the bot from a platform apps page which would also show information about the app, privacy policy and support options.

Other requirements were to have a logo and come up with a wireframe for how the /mdnbot-search slack command results will be displayed in the chat.

These were our starting points for discussion. We reconsidered some of them when we started developing, others we found out we didn’t need. For example we figured out that there is not much difference between the MDN skill level or resource type filtered results and we dropped that requirement.

Second Meeting

During our second meeting we used talky.io, but kept losing Jasmina because of internet connection troubles. We did manage to successfully discuss all of the User Stories and decided to go with Claudia Bot Builder as our technology stack. Its ease of use and awesome documentation turned it into love at first sight or first read… The only concern was that it worked only with AWS lambda functions and we weren’t sure if the AWS free tier model would allow us enough flexibility. We soon discovered that AWS has an always free plan available which allows you to have 1,000,000 lambda requests per month. That seemed more than enough for us. And we always had the option to migrate our bot’s code to Node.js and Express so we can deploy it on Heroku for example, if we exceeded our AWS requests limit.

3 — Environment setup

Setting up an AWS free tier account seemed like a daunting task at first, I needed to give my credit card info details and go through a funny robot voice call where I had to type in some access code. But AWS does not charge you if you do not exceed the free tier offer and you can easily set alarms to be notified in case that happens so I rested assured and proceeded with confidence.

Once in the AWS console management, following claudia-bot-builder documentation, I’ve created an IAM role with minimum permissions requirements and set it up as deploying account on my local computer to work with the aws-cli. I’ve shared the config file with my colleagues so they can set it up on their computer too. And that was that for the AWS setup part. Now on the slack app side, I had to create a slack app to get the Client Id, Client Secret and Verification Token that claudia needed to configure the lambda function. This was very easy to do as the slack app management panel is very intuitive. I still needed to integrate it in our slack team so we could test how our bot code behaved and the chingu-central team that we were using to coordinate didn’t allow anymore integrations on its free plan. So I ended up creating a new slack team which was very easy to do as well.

I followed the hello world tutorial from claudia and pushed a very polite but not yet functional bot to AWS.

We were up and running in just one day. Pretty impressive and very encouraging. We were definitely on the right track to completing this project.

Jasmina came up with a few versions for our logo and Erik wowed us with his design skills by creating a very cute looking chatbot mascot.

We discussed coding guidelines like naming variables and whether to use ES6 or stick to ES5. We also got some clarity on the github collaboration workflow and we decided to use slack threads for our discussion topics from now on so we can orientate ourselves better in the chat conversation. I also pinned them to the channel so we can always find them with as little effort as possible.

And from here we went straight to the coding part.

4 — Development

I was caught up with another project when that happen so I was a bit slow on picking up tasks from our Kanban board. Jasmina was the one who dove in the first and did almost the whole functionality by herself in the span of one week or so. That consisted of handling four slack commands:

• /mdnbot-search
• /mdnbot-show [searchTerm] [searchTopic] [itemNumber]
• /mdnbot-random
• /mdnbot which displays the welcome message.

She updated us daily with her progress and we gave her feedback on what improvements could be done. In the meantime, since we had a better picture on what our bot was going to do, Erik picked up the task of designing and coding the landing page for the bot. We had a separate github repo for that because we didn’t want to mix it up with the code for the lambda function.

The following week I was freed from my other project and rushed to the board only to discover that indeed there wasn’t much left to be done :(. So I started refactoring the code and added the ES6 babel compilation task. After what looked like my best refactoring work ever, I declared myself satisfied with my contribution to the bot’s functionality code. Erik got a chance to add his two cents too, by adding the footer with the Github and landing page links to the welcome message.

And this was our first development iteration cycle, also known as sprint in the agile management world.

Next up on our goals was getting the bot to be installed on other slack teams as well, i.e. making it a distributed app.

5 — Deployment

This is it, our final step before the finish line. Slack makes app distribution very easy by automatically generating the install button for you and by giving you a field in the oAuth and Permissions tab where you can input your redirect URL. The redirect URL matches an endpoint in your code that is in charge of the authentication process. I wasn’t very familiar with how the authentication token exchange worked and even after I’ve read their instructions on the whole setup, I’ve spent a lot of time wondering if it was really necessary to exchange the tokens and what would I do with the authentication token afterwards… It’s not like I’ll be signing any requests with it, because I am not making any requests to the realtime messaging Slack API, right ? Didn’t get to elucidate that question but it seems that you do need to get the authorization token to make the installation to work, even if you don’t do anything with it afterwards.

And then we started the discussion of how to actually implement this token exchange. So we needed an endpoint, that meant a back end… probably in node.js or php… in the landing page repo? Or maybe we could create another lambda function endpoint in the current bot lambda function? Soon enough we discovered that you cannot have multiple endpoints in a lambda function. Feeling a bit lazy, I started wondering: why isn’t claudia-bot-builder already taking care of this ? Maybe it does, so at Jasmina’s suggestion I posted a question on their gitter community. I also found this nice tutorial about redirecting to the slack team URL after authentication. So I didn’t stop trying while waiting for a reply on gitter. I had another fallback, a separate lambda function, that I had already started to build using the claudia-api-builder. I did get that to work in a separated github repo, though I later discovered that you could have them in the same github repo and just add separate deploy tasks for each of them in your package.json file.

The team from claudia.js gitter community replied pretty fast to my question, in less than a working day. So apparently claudia bot builder does handle this process if you add append /slack to the command URL you get when you configure the bot lambda function for slack.

Since we already got the redirect to work with the separate API lambda function, I said we’ll leave this for the enhancement cycle.

Fun fact

Before getting the separate API lambda function to work, we managed to break the slack app management panel :D. The slack app wasn’t responding to any updates anymore and this is what we got when we tried to save any updates to the slack commands:

We solved this by deleting the app and re-creating it..

Publishing it to the slack store

Slack has a very cool review process for submitting apps. You get a list of checkpoints your app needs to meet and in a few day after your submission, they show you which checkpoints you failed (or not :p) to meet. After we quickly put together some disclaimers about any use of data in the Privacy Policy and styled the page, we made the first submission of the bot. There were three issues that were pointed out to us:

1. Our app requested team:read permissions and it didn’t seem to make use of them ( though, after I did removed the permission and got it published I discovered that the redirect to the slack team after installation doesn’t work anymore and we’ll have to fix that in the second version).
2. The cancel installation action wasn’t handled in the redirect lambda function so the app failed to provide a clean User Experience.
3. We used the github repo issues page for the support URL they required, and as it turns out you need a github account to create issues, doh. So it failed to pass the support page checkpoint.

We had this fixed in a few days and we got our app published after the second submission.

Celebration day!

We got it submitted on thereisabotforthat too and Chance Taken, our Chingu leader, helped us tell the world about it by mentioning it in the Chingu weekly Newsletter. Also the team from Claudia bot builder loved our work and added it to their bot examples:

We had a quick look at our AWS lambda usage stats in anticipation of our success and…

It hasn’t gone viral (yet :p) but we learnt a lot and we had a lot of fun building it. And here is where our journey ends. Or is it just starting ? Only time will tell, but we did talk about building other projects together. So we’ll see how that goes. We’ll keep you posted.

Thank you for reading!