How to write and host a HipChat addon?

[Deleted user]

I'm not quite sure I understand the whole process of writing addons for HipChat. Assuming that I would like to implement a notifier addon (something similar to what is described here: https://issues.jenkins-ci.org/browse/JENKINS-41976), do I need to host that addon somewhere in order to have the capabilities url available?

Whilst searching around, I could find a HipChat integration in the marketplace that I could add globally to a HipChat deployment, but it is not really clear whether the token generated was a v1 API token, or if it was an OAuth2 access token for that addon? I'm guessing that addons would have client_id and client_secret associated with them instead and the oauth2 tokens would need to be retrieved by the addon itself.

Additionally, I can't really tell whether this addon thing is something that everybody can host on their own if they'd like, or whether the addon needs to be implemented as if it was a SaaS ready application and hosted by the author of the addon.

Any help on these subjects would be greatly appreciated. 

[Nick Turskyi]

Hi Peter,

For a simple functionality like posting notifications to HipChat room, you may also use the "BYO Integration" in the room integrations list:

Screenshot 2017-03-03 12.00.44.png

It will generate an API token with the necessary scope and provide instructions for sending notifications to the room.

While Chris' answer is a lot more comprehensive, I hope this could also be helpful for somebody!

Nick

[Deleted user]

Just to clarify:

would this mean that anyone who wants to send notifications to multiple rooms would need to use their own BYO extension with the associated credentials? Or would it be possible to just create an addon without any backend whatsoever and have access to a proper OAuth2 access token (or client credentials)?

The Jenkins integration on the marketplace seems to expose a token on the interface, but it's difficult to tell if that's an OAuth2 access token or a v1 API token.

[Nick Turskyi]

@Peter Major, once you configure a BYO integration for a room, it generates an "add-on" APIv2 token, which can be used to send messages to this room (token scope is limited to send_notification and view_room for this particular room). This token can also be created manually on the the Room -> Tokens page.

You may also want to generate a personal access token, which may have any permission your user has and does not expire.

None of the above requires you to run the actual infrastructure for the addon, you may just use the token against HipChat API from any code.

Further reading on API tokens: https://developer.atlassian.com/hipchat/guide/hipchat-rest-api/api-access-tokens

Jenkins for HipChat is a 3rd party integration, but their documentation states it supports both v1 and v2 with the former being deprecated in future versions.

[Deleted user]

Thanks for the note. I'm aware of the Jenkins integration since I'm the maintainer of the Jenkins plugin, but I have not been involved with the Jenkins add-on on the Marketplace in any shape or form.

I wasn't really able to add BYO addon to all rooms, it looks like that adding BYO is limited to particular rooms - well that kind of prevents people from using those access tokens to notify multiple rooms at the same time.

[Nick Turskyi]

Yeah, the BYO is limited to the room it's installed to.

For this kind of tasks I would recommend creating a user token with the proper scope - it will have access to all the room this user is a part of.

As of the Marketplace question, can you provide a link to the plugin so I could check?

[crivers]

It sounds like you've already looked through some of the documentation, but just in case... a good place to start would be https://developer.atlassian.com/hipchat/getting-started. If you're looking to build an addon yourself, it indeed would need to be hosted somewhere public so that the client can load the appropriate data and the server can communicate back to the addon for stuff like webhooks.

None of the addons in marketplace use v1 API tokens (the v1 API is deprecated and we don't recommend building anything on top of it). All tokens made via the v2 API and going forward and done via oauth. When the clients make requests to your addon, they will include a JWT identifying themselves (including some group and user information) which your addon can use to pull and server appropriate data back to the user.

The best way to get familiar is probably going through the step-by-step guide at https://developer.atlassian.com/hipchat/tutorials/getting-started-with-atlassian-connect-express-node-js. It will explain how to setup a local node server and a tunnel via ngrok so you can play with things.

Hopefully that helps clear things up and get you started building something that makes your HipChat experience better!