In the first post of this series I have shown how you can interact with Visual Studio Online using Hubot.

For simplicity, I’ve only shown how you could use hubot from Campfire (since it’s what is installed out of the box) to issue commands against Visual Studio Online.

On this post I will explain how you can do the same, but using Visual Studio Online team rooms instead of campfire.

Using Team Rooms, has some advantages over campfire. It’s integrated with Web Access, you easily integrate automatic posting of messages to two rooms with an easy interface (to be fair, Visual studio online, provides service hooks to achieve the same effects to other chat rooms, but you have to manage them with more work), links are shown on multi lines and you can even use Team rooms directly from Visual Studio with this cool extension

In the previous post I wrote that there were two ways to extend hubot. Scripts and Adapters. Scripts are responsible for implementing commands to interact with external systems and adapters are used to implement the communication between hubot and the chat room (or an IM client).

I guess it’s easy to guess by now, we are going to add a Visual Studio Online team room adapter to our hubot installation.

Operation Model and Requirements

The Visual Studio Online hubot adapter, has a different model of campfire. Hubot Campfire adapter opens a connection to Campfire and continually listens (in streaming mode) to commands on campfire room(s), whereas the Team Room adapters works with events.

The team room adapter opens a http/https listener and receives events from Visual Studio Online via service hooks events.

This means that your hubot needs to be publically available on the internet to be called by Visual Studio Online.

If you can’t or don’t want to have Hubot publically exposed on the internet, you can place it behind a firewall since the adapter is capable of fetching data from an Azure Service Bus queue. If that mode is enabled, the adapter will not work in a event mode but in a polling mode.

Event mode is the recommended model of operation, since it is more efficient. Not only it spends less resources, it’s also faster (and cheaper)

But before going into that, let’s start with some pre requisites.

Setting Hubot Credentials

Note: If you are running Hubot in trusted mode, this account can be shared with Visual Studio Online hubot scripts configured in the first post of this series.

You need create an user for Hubot be able to listen to commands on Team Room and respond to them. I’m going to omit detailed steps to create an account, but in simple terms you need to:

1. Create a Microsoft Account
2. Login to Visual Studio Online and enable alternate credentials
3. Assign a license to the user
• This user requires either an advanced account or an account with permissions to access a team room
• You can get more information how to get a license for an account on Get more user licenses for your account
4. Give permission to all team rooms you want Hubot to be active on.

Tip: When you enable alternate credentials, set the display name to Hubot and the profile image (with an appropriate hubot image)

This way, when Hubot replies, you will see it’s name and image as the avatar

 

Installing the Hubot Visual Studio Online adapter

In order to use Visual Studio Online Team Rooms instead of campfire (the default adapter) you need to install hubot-vsonline.

Since the adapter, is available as an npm package, all you need to do is issue the command

npm install hubot-vsonline

on hubot folder.

Configuring the adapter

In order to configure the adapter you will need to set a bunch of environment variables.

If you have an Eidetic memory and remember my first post, you will notice some of these parameters are shared with the Visual Studio Online Hubot scripts (which is not a coincidence )

General Parameters

These parameters are mandatory

• HUBOT_VSONLINE_ACCOUNT – The name of your account. (don’t include visualstudio.com it’s only the account name)
• HUBOT_VSONLINE_USERNAME – the username of the account you created earlier in section Setting Hubot Credentials (either the primary or the secondary username)
• HUBOT_VSONLINE_PASSWORD – The password you have set up for the alternate credential

Listeners Authentication

Since your HTTP/HTTPS listeners are exposed on the internet, it’s better that they are protected with some form of authentication otherwise anyone who knows your hubot your endpoints could try to inject commands into your hubot (they wouldn’t be able to see the responses but there is potential for harm).

The listeners can be configured with basic authentication. It is recommended you enable basic authentication (in fact it may be mandatory depending on how you configure service hooks. More on that later)

These parameters are optional.

• HUBOT_VSONLINE_ADAPTER_BASIC_AUTH_USERNAME – The username for the adapter HTTP/HTTPS listener
• HUBOT_VSONLINE_ADAPTER_BASIC_AUTH_PASSWORD – The password for the adapter HTTP/HTTPS listener
• HUBOT_URL  –The url where the listener is configured. You shouldn’t really need to change this (by default it’s /hubot/messagehook)

 

Rooms

• HUBOT_VSONLINE_ROOMS – The list of rooms (names separated with commas) of the rooms you wish Hubot to join.

Note: Joining a room doesn’t mean hubot will listen to commands. It only means hubot wlll be visible to users (more on that later)

Parameters to configure SSL

Note: If you have installed Hubot in which node is NOT setting up it’s own listener and the host provides you a reverse proxy (with HTTPS capabilities), this step is not necessary. For example this happens when node is hosted inside IIS (using IISNode) or a PaaS provider like Heroku or AppHarbor, in that case you can skip this step.

SSL is not mandatory, but it is off course it recommended that you use it.

Those are the minimum set of parameters you need to enable SSL

• HUBOT_VSONLINE_SSL_ENABLE – Set this variable to true to enable SSL
• HUBOT_VSONLINE_SSL_PRIVATE_KEY_PATH – The file path to your SSL private key
• HUBOT_VSONLINE_SSL_CERT_KEY_PATH – The file path to your certificate

These parameters are optional

• HUBOT_VSONLINE_SSL_PORT – SSL port. By default it’s set to 443
• HUBOT_VSONLINE_SSL_CA_KEY_PATH – The path the certificate authority certificate (default is null)
• HUBOT_VSONLINE_SSL_REQUESTCERT – If we should request a client certificate (default is false)
• HUBOT_VSONLINE_SSL_REJECTUNAUTHORIZED  -  Check certificate against CA list. (Defaults to false)

Note: There is a caveat in using SSL, you must use a valid certificate, in other words a certificate that is signed with a known certificate authority.

Launching Hubot with Visual Studio Online adapter

We are now ready to launch Hubot.

To use another adapter you either set environment variable HUBOT_ADAPTER with the value hubot-vsonline or when you launch hubot daemon pass the variables “-a  vsonline”

Setting up Service Hooks.

Hubot commands are sent to hubot via service hooks. So before hubot can respond to commands issued on Team Rooms, you need to set up at least one service hook.

You have to configure one service hook per room. Go to visual studio online backoffice and create a new service hook on the Service Hooks tab.

With SSL

There are two ways, to configure a service hook. If you are using SSL (recommended) then you have a service hook that is specific to Hubot.

Press Next and select the Team Room on the FILTERS section and then press Next.

Select “Post a message” on the Perform this action section, and enter your hubot url (unless you changed the default value it should be https://<hubot address>/hubot/messagehook) and the username and password you configured in the section Listeners Authentication)

Click finish and you are now ready to start issuing commands on the configured team room.

Remember you should configure the service hooks for all team rooms you wish Hubot to listen to commands.

Without SSL

If your hubot doesn’t has SSL capabilities (off course this service hook also supports SSL), you can use as an alternative the generic “Web Hooks”  and use the following parameters

• Trigger on this type of event – Team room message posted
• Team room – select the team room
• URL – Hubot listener URL
• Resource details to send – All
• Messages to send – None
• Detailed Message to send – None

Basic authentication is optional (not recommended at all )

Next Post

In the third and last post of this series, I will explain how you can install an Hubot instance running on an Azure Web Site

 

If you have read Brian Harry post Visual Studio Online Update – Sept 4th you may have noticed that with last week’s update (sprint 70) it is now possible to integrate Visual Studio Online with Hubot.

Although that is not 100% correct, it was already possible before, the fact is currently there is not too much information how to do it.

it is my intention with this post (the first from a series of three posts) to try to disseminate some information how to integrate Visual Studio Online with Hubot.

In this post I will try to show you, how can you perform Visual Studio Online tasks with an almost vanilla Hubot installation, on a second another post I will show you how to configure Hubot to use Visual Studio Online Team Rooms and finally on a third post, how you can run your Hubot installation from an Azure Web Site.

Hubot

Hubot has been developed by GitHub and it is a robot (or company’s robot has they put it) that allows automation of tasks from your chat room.

Hubot is extensible. It contains two extensibility points

• Scripts – Scripts are responsible to implement integration with other systems, to automate tasks. A script is a group of commands that implement that automation. You can add more scripts to automate tasks from other systems. There is a bunch of scripts kept by GitHub, but you can found a lot of scripts on the internet.
• Adapters – Out of the box, Hubot only supports Campfire as a chat room. But you can make it work it other systems, by installing another adapter. An adapter is responsible to implement the communication between Hubot and your chat room (in fact it doesn’t need to be a task room it can be IM systems like GTalk or any IM client which implements XMPP). GitHub maintains the “full” list of third party adapters and I’m sure others that are not on this list can be found on the internet.

Adapters and scripts are decoupled. The scripts just integrate with the external system, you can use any adapter you want and the scripts will just work.

Flunky would be a much better name for Hubot. He is allways ready to take orders from people issuing commands in chat rooms. Out of the box Hubot can do important stuff like show you Pug pictures, mustachify images, translate phrases and a lot of other stuff, but you can install a bunch of optional scripts to do even more stuff.

Visual Studio Online Hubot Script running modes

By now, you must have guessed that in order to integrate Hubot with Visual Studio Online we are going to use a script.

The script can be executed in two different modes.

• Trusted Mode – In trusted mode, all commands executed on Visual Studio Online (on behalf of the users) will be done with the Hubot user credentials. This mode is simpler to configure, but it has three disadvantages.
  • This account needs permission (on the team projects) to perform all the operations you wish your users to issue. This may be extra work to administer or requires you to give permissions to access all team projects (an Über user so to speak)
  • All operations will be performed with this account, thus you will lose auditability and the capability to understand who performed the operations (like work item changes and triggering builds)
  • The user may be able to perform operations for which he doesn’t has permissions (as long as the hubot user can perform the requested operation)
• Impersonation Mode – On this mode all commands will be executed as if the user has executed it himself. But don’t worry Hubot doesn’t know the user credentials and before any command is executed as the user, the user will have to authorize hubot to execute comannds on behalf  of the user (the user will only need to authorize this once and can ask Hubot to forget about him anytime). As you probably guessed by now, impersonation mode uses OAuth. Although this mode takes a little longer to configure (10 more minutes ) it has advantages.
  • Since the operations will be executed as the user who issued the command, it means permissions will be checked by Visual Studio Online, therefore the user will be allowed to performed operations for which he has permissions
  • The operations will be logged with the name of the user who issues the command, so operations will be auditable and more traceable (eg: if you see work item changes, they appear as performed by the user who issued the command).

Keep in mind that in order to use impersonation mode you will need to configure SSL on Hubot, this requires you to have certificate (there are some exceptions though)

I would recommend that you use Impersonation mode

Setting up Hubot Credentials

If you intend to use impersonation mode, then you can skip this step.

You need create an user in order to execute commands on Visual Studio Online. I’m going to omit detailed steps to create an account, but in simple terms you need to

1. Create a Microsoft Account
2. Login to Visual Studio Online and enabled alternate credentials
3. Assign a license to the user
4. Give permission to all team projects you want your users to issue commands against

Noticed that if you resort to the newly free stakeholder license the commands your users will be able to perform will be limited. (another reason to use OAuth no extra licenses needed)

Setting up OAuth

If you intend to use trusted mode, then you should skip this section.

Impersonation mode, requires the use of OAuth, to use OAuth on Visual Studio Online, you need to register an application in Visual Studio Online

In order to register an application go your Visual Studio Online profile page (you need to be logged) and click the Create a new Application link

Fill in at least the mandatory fields.

The Authorization callback should point to the URL:

https://<your hubot host name>/hubot/oauth2/callback

After you have saved your application, you will have a screen similar to this one

Later on you will need some of the values (App Id and App Secret) provided on this screen.

Install Visual Studio Integration on Hubot

I’m not going describe the details, how to install Hubot, that is well explained on Hubot deployment documentation

The simplest way to run, Hubot is to install it on Un*x machine, it took me less than 10 minutes to configure Hubot on a Ubuntu Linux instance running as an Azure Virtual machine.

To make things simpler, I have configured it to run on Campfire (since it’s supported by default), but you could configure an adapter to work with other popular group chat systems like Flowdock or HipChat (I will explain how to integrate with Visual Studio Team Rooms on another post).

BTW did you know Visual Studio integrates nicely with Campfire, Flowdock and HipChat. You can easily configure Visual Studio Online to send events (about builds, work item changes, source control….) to your chat rooms. You can read more about it on Integrate with other services

In order to add support for Visual Studio Online, you have to install hubot vso scripts you can do it by issuing the command

npm install hubot-vso-scripts

on the hubot folder and add it to your external-scripts.json as documented in the scripting section of reference Getting Started With Hubot guide

This may sound complicates, but you only need to edit the external-scripts.json and make sure it contains the Visual Studio Online hubot scripts referenced.

The file contains one array with the module name(s) of the external scripts.

Since I only have one external script, I just add one element to the array with the name NPM hubot vso script module.

After installing the module, you have to ensure the following environment variables are set before starting hubot daemon. The way you do id, depends how you are configuring hubot to start automatically, so I will just mention the variable names and it’s value, it’s up to you as a sysadmin to set them in the right place

General Parameters

• HUBOT_VSONLINE_ACCOUNT – The name of your account. (don’t include visualstudio.com it’s only the account name)

Parameters for trusted mode

If you see these parameters, the script will run in trusted mode.

• HUBOT_VSONLINE_USERNAME – the username of the account you created earlier in section Setting Hubot Credentials (either the primary or the secondary username)
• HUBOT_VSONLINE_PASSWORD – The password you have set up for the alternate credential

Parameters for Impersonation mode

• HUBOT_VSONLINE_APP_ID – The application Id. You can get this value from the application you have registered in Visual Studio Online
• HUBOT_VSONLINE_APP_SECRET – The application secret. You can get this value from the application you have registered in Visual Studio Online
• HUBOT_VSONLINE_AUTHORIZATION_CALLBACK_URL – The url you configured in section Setting up OAuth (it should be something like https://<your host name>/hubot/oauth2/callback)

Parameters to configure SSL

Note: If you have installed Hubot in which node is NOT setting up it’s own listener and the host provides you a reverse proxy (with HTTPS capabilities), this step is not necessary. For example this happens when node is hosted inside IIS (using IISNode) or a PaaS provider like Heroku or AppHarbor, in that case you can skip this step.

Remember you will need to configure SSL if you are using impersonation mode.

Those are the minimum set of parameters you need to enable SSL

• HUBOT_VSONLINE_SSL_ENABLE – Set this variable to true to enable SSL
• HUBOT_VSONLINE_SSL_PRIVATE_KEY_PATH – The file path to your SSL private key
• HUBOT_VSONLINE_SSL_CERT_KEY_PATH – The file path to your certificate

These parameters are optional

• HUBOT_VSONLINE_SSL_PORT – SSL port. By default it’s set to 443
• HUBOT_VSONLINE_SSL_CA_KEY_PATH – The path the certificate authority certificate (default is null)
• HUBOT_VSONLINE_SSL_REQUESTCERT – If we should request a client certificate (default is false)
• HUBOT_VSONLINE_SSL_REJECTUNAUTHORIZED  -  Check certificate against CA list. (Defaults to false)

If you haven’t done it yet, now you should configure campfire adapter.

You are now ready to launch your hubot daemon

Using Hubot

[note: I have configured Hubot with impersonation mode]

We are now ready to enter a campfire chat room, and start issuing commands to hubot.

On the right top corner you can see the persons who are in the chat room

You can notice, in this room called “hubot” (how original), right under the “Who’s here?” there are two persons. Me and Hubot.

Hubot is here listening to our commands, we can now start giving him orders. All commands start with the hubot keyword (unless you have configured a different one)

We can can start by issuing the hubot help command, to get a list of all available commands, or hubot vso help to get the list of the commands that really interest us. (all Visual Studio Online commands start with hubot vso)

This is the list of currently available commands on Visual Studio Online

Hubot vso assign <work item list> to @me | <user name> – Assigns one more or more work item(s) to you (@me) or a user name specified
Hubot vso build <build definition number> – Triggers a build
Hubot vso builds – Shows a list of build definitions
Hubot vso checkins [last <number> days] – Shows a list of TFVC checkins you have made in the last day (or specified number of days)
Hubot vso commits [last <number> days] – Shows a list of Git commits you have made in the last day (or specified number of days)
Hubot vso create pbi|requirement|bug|feature|impediment|task <title> with description <description> – Creates a work item, and optionally sets a description (repro step for some work item types)
Hubot vso forget credentials – Removes the access token issued to Hubot when you accepted the authorization request
Hubot vso help <search text> – Get help from VS related forums about the <search text>
Hubot vso me – Shows info about your Visual Studio Online profile
Hubot vso projects – Shows a list of projects
Hubot vso room default <key> = <value> – Sets a room default project, etc.
Hubot vso room defaults – Shows room defaults (e.g. project, etc)
Hubot vso status – Shows status for the Visual Studio Online service
Hubot vso today – Shows work items you have touched and code commits/checkins you have made today
Hubot vso update work remaining <work item id> to <hours remaining> – Updates work remaining on a work item

Our first command

I don’t intend to describe all commands. But let’s start with a simple one

I will issue the hubot vso me command. This will give me information about how hubot seems me in Visual Studio Online

Hubot says it doesn’t know me yet, and requires me to authorize him to do operations on my behalf,.

It’s nice enough to give me a link so I can authorize him. Clicking on the link will lead us to an authorization page (you don’t need to issue this command in particular, any command that requires interaction with Visual Studio Online will trigger (for the first time) the authorization request).

After clicking on accept

Your browser window will show you this message

and you will see a message on the chat room

with your name (your display name) and your email.

We are now ready to issue commands against Visual Studio Online.

If you wish to revoke your authorization, you can issue the command hubot vso forget me

Setting Room Defaults

Some commands operate over a team project or one or more Git repository. In order not to make users to keep writingt he same values over and over, you have to set default value for a room (these values will be automatically picked up by the commands)

You can set the room default values (you can change them anytime) with the command

Hubot vso room default <key> =  <value>

Where key is the key name for which you want to see the <value>

Possible values for key

• project – The name of the default team project (for example for work item creation)
• repositories – the list of Git repositories (separated by commas).

This value is set per room, so each team can have it’s own room and have it’s own defaults

So let’s set a team project for later

You can get the default values for a given room with the command

Hubot vso room defaults

Creating a Work Item

Let’s now create a requirement in our default team project “tst CMMI”

hubot vso create requirement I can create work items from hubot with description It works

noticed hubot created a work item, replied with the work item id and a link to the work item.

Getting the list of changes I performed today

the vso today command, is great for stand ups. It shows the work items I’ve (as the user who issued the command) changed today and also my commits (if the team project is using Git) or checkins if using TFVC

Notice the work item it has been created on the previous command is listed

Assigning work items

You can also assign one or more work items (to assign more than one work item separate the ids with a comma) to your self or to another user

Hubot vso assign <work item list> to @me | <user name>

Note: The user name is the user display name

Update remaining work

Another command that is useful for daily stands ups is the

Hubot vso update work remaining <work item id> to <hours remaining> 

Getting help from Visual Studio related MSDN forums

Another cool command, is the Hubot vso help <search text>

let’s try to get help about “how to list active bugs”

It shows the top 5 hits from MSDN forums and if you want the full list of results there is also a link to it.

Unfortunately campfire, doesn’t automatically make links clickable when the response contains more than one line (team rooms  don’t have this issue )

Close up

I have not described all the available commands (remember you can issue at any time hubot help vso to get the full list of Visual Studio Online commands). I hope I have successfully shown you, how to configure Hubot to issue commands against Visual Studio Online and some of its potential.

On my next post, I will explain how you can configure Hubot to use Visual Studio Team rooms instead of Campire and on the third post of this series will show you, how you can configure Hubot to run on an Azure Web Site.