Sending a message to HipChat from VSTS

I’m still working on the end-to-end scenario for a customer to integrate several 3rd party tools into VSTS. See my previous posts for details. This post shows how to send messages to HipChat from VSTS.

To be able to send something to HipChat I want to use the REST API provided by HipChat. I found that the easiest way is to simply do an HTTP Post containing the message. However you need a token first. To get this token open your account settings in HipChat.

Getting a Token for HipChat

Then click API Access on the left. You might have to provide you password to continue.

Create a “send notification” token and copy it. It’s pretty long. Keep it secret.

Here’s a little side note:

I create this token with my user account. This means whoever is using this token will finally be speaking – or writing – in my name. For a real world implementation it would be better to create another account in HipChat for our VSTS service user. It could e.g. be called “VSTSUser”. This way it would be obvious who is actually sending the messages. However it doesn’t really matter for our prototype described in this blogpost.

 

Now we have to figure out which message format is expected and what’s the right URL to post to. If you follow the documentation of HipChat API  you will find this page where you find a sample message and the URL.

If you search a little longer you will find that the full URL for HTTP Post to HipChat Rest API will look like this (in my case I provide the token inline).

https://api.hipchat.com/v2/room/YOURROOMNAME/notification?auth_token=YOURTOKEN

Be aware that you of course have to change YOURROOMNAME and YOURTOKEN to the actual values.

Hint: The name of the room is case sensitive. I didn’t expect this.

We can give it a try using the composer in Fiddler:

Message received:

So we know that the basic setup works.

Little fun story:

You might think: “I don’t like green.” (As I did.) You might think: “I want to post my messages in blue.” And then you might just change “green” to “blue”. (As I did.) Bad idea! It’s always worth trying things like these out in Fiddler before you break your build (as I did) by a little modifcation like this. For some reason blue is not a valid color. Who would have thought.

 

Now let’s integrate with VSTS.

Setting up HipChat communication from VSTS

There’s no Build Task available on the marketplace for HipChat integration. But as we just saw all we really need is Http Post. We can do this very easy with Powershell – and there is a powershell build task available. So let’s just pick that. I really like powershell build tasks.

I’m going to quote myself but commandline or ssh tasks are basically the equivalent to Gaffertape in your toolbox. You will need it and it’s good that we have it. And by the way it fixes everything.

So I add that Powershell step to my build and choose to run an inline script instead of a script file. Why? Because for my end-to-end proof of concept it’s just easier to set up than working with another file. Here’s what it looks like finished. Just don’t choose blue. I chose purple.

Here’s the full Powershell script. Just replace MYROOM with your room and MYTOKEN with your token.

Hint again: The name of the room is case sensitive.

$apiuri = https://api.hipchat.com/v2/room/MYROOM/notification?auth_token=MYTOKEN ”

$body = @{
color =  "purple";
message=  "Something happend in VSTS";
notify=  "false";
message_format= "text"
}
Invoke-RestMethod -Method Post -Uri $apiuri -body (ConvertTo-Json $body) -ContentType "application/json"

 

What are we doing in this script?

We create a variable pointing to the REST endpoint to send messages to HipChat.
We are creating a variable containing the message body. This looks a little like JSON – but it’s not. It’s the way powershell works describes objects.
We’re sending a purple message saying “Something happend in VSTS”.
Then we call Invoke-RestMethod, which is a provided powershell method to do REST calls. We specify the URI, specify that we want to do an HTTP POST, provide the message body which is converted to JSON using ConvertTo-Json and specify the content type.

 

We’re done.  Whenever you want to notify HipChat, just integrate a call like this of course you probably want to use different messages

Recap

This post shows how easy it is to integrate basically any web API into VSTS. With the availabiltiy of Powershell commands in VSTS Build you can any external API that provides REST endpoints. Clearly you might wish for more comfort. More comfort could be provided with custom extensions. If you want you can create your own extensions for VSTS and put them on the marketplace.