Integrating JIRA Agile and Hipchat

Recently, I came across Hipchat as a user had created a way to send Opsview notifications into it – and i had no idea what *it* was. After having a brief google, it looks like a very interesting tool – a sort of chatroom meets dev tool blend, whereby development teams can chat and ask questions in amongst messages from other tools including GitHub, JIRA Agile and more.

So, naturally – as JIRA Agile users, and with HipChat being free, I wanted to integrate it so i could test it out. Unfortunately this is a bit difficult if you arent an Atlassian employee, so below are some simple steps to get you from 2 seperate systems, to an integrated setup where messages are sent from JIRA Agile into your Hipchat room of choice.

1. Link them together

In order to link JIRA Agile and Hipchat together, you first need an API key from Hipchat. To do this, navigate to https://*.hipchat.com/admin/api where * is your Hipchat domain. On this page, you will be able to click ‘Create’ new token which will generate an API key for you:

After creating your token, you will be left with an API – like so:

Copy and paste that bad boy, as you’ll be needing it in a moment. Now, login to your JIRA Agile instance – in my case, we are using JIRA On-demand, so if you are using the on-prem version this may slightly differ for you.

Within JIRA Agile, navigate to ‘System’ via the gear cog as below:

And once in here, go to ‘Mail’ and then ‘HipChat configuration’ on the left hand side:

In here..well, you know what im going to say next 🙂 Paste in that API Badboy you copied earlier, and click save. For those using Hipchat ‘on premise’ (if thats even a thing), you might need to modify your URL here – but for me and most other users, just leave it as default:

2. Configure JIRA Agile

Ok, thats the easy part out of the way. JIRA Agile is now setup to talk to Hipchat (trust me, it is!). Now we need to tell JIRA Agile what to tell Hipchat about – to do this, we must edit our JIRA Workflow (scary!). The workflows can be found via the left hand menu under your JIRA Agile project:

Click on ‘Workflows’, and you will be presented with your workflow (or default one, if you’ve never changed it!). Now, we want to edit the workflow in order to tell JIRA Agile when to alert us – so to do this, click the little ‘pencil’ icon on the right hand side:

This will load up your workflow edit view. This is basically the ‘flow’ that your user stories, tasks and whatnot follow – and is comprised of 2 items:

1. Statuses – Statuses are states that a user story or task can ‘be’, for example – a story can be ‘Open’, ‘In Progress’, or ‘Closed’.
2. Transitions – Transitions are what happens when a user or developer changes the status of a user story, i.e. changing from ‘Open’ to ‘In Progess’ has a transition by default of ‘Start progress’.

The item above that we are interested in is ‘Transitions’.

What we therefore need to do, is edit a transition and set what Atlassian refer to as a ‘Post function’, i.e. something that happens when a transition is triggered. By default, the post functions are mainly ‘Send an email to annoy everyone’, or ‘Alert the boss’ – what we are going to do is add another rule, ‘Send a message to HipChat Room X’. (There is a very dandy and technical link here for anyone who wants to learn more).

Configure the post function

So, that sounds all very fancy and technical – how do we actually do it? Well I am glad you asked. Firstly, click on the LINE (the line being the transition), and you will notice a series of options appear on the right hand side, like below:

After clicking on ‘Post functions’, you will see a list like so:

This is ‘the list’ of things that are supposed to happen when the ‘Start progess’ transition is invoked, i.e. someone changes a user story from ‘Open’ to ‘In progress’. What we need to do next, is click ‘Add post function’ which is hidden in the middle right of that above screenshot. Clicking this will give you a a lovely list of options, one of which is, you guessed it, “Notify HipChat”:

Select this line and click ‘Add’, and you will get the edit screen for that particular post function:

This is where you can now specify the parameters – what gets sent, and where to. Use JQL to specify only certain projects to certain rooms, only certain epics, etc etc. In my example i left JQL blank but i ticked ‘All members, Ehertz and Private members room’ rooms (just a few examples I made up), along with the client-side notification – as I am running the dedicated OS X client which is rather nice. After clicking add, that is the configuration done!

Next, and finally, we need to publish our workflow. You’ll notice after clicking add that:

A) Your workflow now has another post function – your HipChat line

B) You have this new ‘Publish’ bar at the top

Go ahead and click ‘Publish draft’, and then save a backup (if you want), and voila – your changes have been made – prepare yourself for the HipChat storm!

So what does it look like?

So now we’ve configured it – what does it look like? Well, this being a sample project and a sample HipChat room its not very interesting, but below is a screenshot of the hipchat client and the messages received when i created a new user story and changed it from ‘Open’ to ‘In progress’:

Cool eh! Now, imagine if you had a room for each development team, and their specific JIRA changes going into the room, along with the GitHub/Bitbucket updates and OTHER items – it would be awesome!

Now, go forth and configure!