Using Hubot with Visual Studio Online

 

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.

the Hubot

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 Smile) 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

image

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

image

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.

image

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 Smile

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

image

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)

image

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

image

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).

image

After clicking on accept

Your browser window will show you this message

image

and you will see a message on the chat room

image

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

image

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

image

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

image

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”

image

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 Smile)

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.

Team Foundation Task Board Enhancer: version .8.3 released

 

New minor release of Team Foundation Task Board Enhancer

TLDR; Two feature changes and two bug fixes. One of them being a security fix. You are advised to upgrade to this version

New Features in this release

Bug Fix, work item titles were not properly escaped

The work item title where not properly escaped, if someone entered invalid HTML into the work item title the tile might not be correctly displayed.

This is could lead to script injection attacks (even considering the work item title is of limited size).

Just to make this very clear, the vector attack is limited and has to be done by someone who has permissions to create work items.

Basically it needs to be exploited internally. An inside job, so to speak, so the threat seems to be small. Nonetheless the problem exists, so you should upgrade to this version.

t’s there so you should upgrade.

Show the (kanban) State of a Requirement on task board

Maybe this should be named, task board meets kanban board. Smile

This is not exactly a new feature, but a an improvement to an existing one.

Previously the state of a requirement were shown for requirements (to be more correct any work item on the requirement category), this feature has been slightly changed. Now instead of showing the work item state, the kanban state (if you are not customizing kanban columns, then this feature will behave like it always had).

Assume we customized the kanban board and added a ”Ready to be documented” state.

image

If you go to the task board, this state will be shown

image

Allowing you to have a better view of your requirements right from the task board, without the need to go the kanban board. (remember kanban columns are customized by team, and this is respected on this feature, so different teams can see different states, just like in kanban board).

Show the color of a work type type for requirements

This is also a slight change from an existing feature.

Besides showing the work item type (if the board has more than one work item type) we also show the color of work item type.

image_thumb1

Previously the color was only shown IF the board contained more than work item type in the requirement category, starting this version the color is shown if the process template has more than one work item type in the requirements category regardless of the work item types visible on the board.

Bug fix for TFS 2013 Update 2 (RTM)

In the previous version, Support for 2013.2 release candidate was added, when the final version come out, a small change broke support for showing user images on the cards (the pictures were too big and stretched). So this version fixes this issue if you have TFS 2013.2 RTM

Download

TFS 2012 (RTM or Update 1)

The version for 2012 RTM or 2012.1 is no longer under active development, but a new version has been released to fix the security vulnerability Download version 11.0.7.7 of the extension

If you are still running TFS 2012 RTM or with Update 1, you should install version 11.0.7.7

TFS 2012 Update 2 and upwards

This version only works on TFS 2012 with update 2 or 3 or 4.

For Update 2 and upwards Download version 11.2.8.3 of the extension

[Update] A bug has been found in version 11.2.8.3 the board would fail to load, if the grouped by People was enabled . You should Download version 11.2.8.4 of the extension instead

TFS 2013

This version works with TFS 2013 RTM  or Update 2

Download version 12.0.8.3 of the extension

[Update]  A bug has been found in version 11.2.8.4 the board would fail to load, if the Team Members tab was active. You should Download version 12.0.8.4 of the extension instead

Installation

If you are running into this for the first time and you have no idea how to install it, full instructions are provided on Task Board Enhancer page

VSO Enhancer support for the new User Voice Visual Studio Online Integration

 

One of the recent announcements at today’s Teched North America keynote, was a new integration between UserVoice and Visual Studio Online.

This new integration enables the creation of work items associated with uservoice suggestions without having to leave uservoice

image

From inside uservoice’s backoffice you can see which suggestions are linked to work items

image

Comments on both uservoice and VSO will be synched to the other side

image

This integration is still in beta (sorry no direct link, just click on Visual Studio). Visualstudio.com has details how to set up

But this post is mainly not about that integration. It’s about a VSO Enhancer new feature that enables you to easily visualize on work item that are linked to a uservoice suggestion on the Visual Studio Online boards (both kanban and task board) without opening the work item one by one.

If you have a work item on the board that is linked to a uservoice suggestion, you will see on the card (or on the requirement/bug in case of the task board) a little uservoice icon.

 

imageimage

Clicking on the icon, will open a new window to the uservoice suggestion on uservoice’s site.

Off course this feature is optional and can be enabled/disabled on a team by team basis.

image

Team Foundation Task Board Enhancer: version .8.1 released

 

[Update: 24 March] Found a minor bug in 12.0.8.1 (requirement colors were not being shown) so version 12.0.8.2 has been released (no announcement)

Download version 12.0.8.2 of the extension

New release of Team Foundation Task Board Enhancer

This is a very minor release, it brings a new feature and support for TFS 2013 Update 2 (release candidate)

New Features in this release

Show requirements execution summary

In the taskboard, under your sprint details you can now see a summary of the completed requirements.

image

(when I say requirements, it means work items in the requirement category (the first column on the task board). For Example Product Backlog Items for Scrum or User Stories in MSF.

The shown value, is not related to the effort spent on the tasks, but the effort related to the work items in the requirements category.

For example in Scrum it’s the Effort field

image

whereas in MSF Agile it’s the Story Points field

image

The summary shows how many points (let’s call it that for simplification purposes) have been already completed out of the total points for this sprint.

Support for TFS 2013 Update 2 (release candidate)

Two weeks ago Release Candidate for TFS 2013 was released it is not the final release, but it has a go-live license, which means it is fully supported and you can use it on production environments.

Update 2, introduced some minor internal changes and this release has adapted to them. If you want to use task board enhancer on Update 2, you will need to install this version.

If you were using VSO Enhancer you would need to upgrade anything everything is taken cared automatically, update 2 was supported even before it was released. Smile

Download

TFS 2012 Update 2 and upwards

This version only works on TFS 2012 with update 2 or 3, there is no support for for TFS 2012 (RTM or Update 1) in this release. (you can still use the older version though)

For Update 2 and upwards Download version 11.2.8.1 of the extension

TFS 2013

This version works with TFS 2013 RTM

[Update: 24 March] Found a minor bug in 12.0.8.1 (requirement colors were not being shown) so version 12.0.8.2 has been released (no announcement)

Download version 12.0.8.2 of the extension

Download version 12.0.8.2 of the extension