Global versus room installations
A HipChat group represents a team in HipChat, for example in HipChat Cloud, the following represent 2 HipChat groups:
Each group has its own user base, rooms, configuration, etc.
You can choose for your add-on to be installable by users globally for their HipChat group, on a per-room basis, or both.
- If the add-on is installed globally, it works in all rooms in the HipChat group
- If the add-on is installed in a HipChat room, it only works in this room. It can be installed in multiple rooms in the same group (each installation will be a different OAuth client)
One OAuth client per installation
Anytime your add-on is installed by a user, HipChat creates an OAuth client, and sends information about the installation to your add-on via the method you declared in the "installable" section of the capability descriptor. You need to save this information, as it will be required to make calls to the HipChat REST API.
- oauthId: OAuth client ID
- oauthSecret: OAuth shared secret
- roomId (optional, for room installations only): ID for the room the add-on was installed in
- groupId: ID for the HipChat group the add-on was installed in
- capabilitiesUrl: URL for a capabilities document which lists the URL for endpoints you can use to make REST calls to this installation
The following sections provide more details on how to implement the installation process:
The installation of an add-on can be triggered:
- In the HipChat administration screen for integrations, from a listing in the Atlassian Marketplace or a descriptor URL
- From your application, by redirecting the user to HipChat
Once the installation is triggered, the following installation flows are available:
This is the most commonly used installation flow.
Once the installation is completed in HipChat, HipChat makes a REST POST to your add-on containing the installation and security context for the tenant.
This installation flow works well when HipChat can contact your add-on, for example if it is a publicly available service.
If your add-on is hosted in an application behind a firewall, HipChat cannot contact your add-on directly to send the installation and security context for the tenant.
In this case, you need to implement the client-side installation flow: post installation, HipChat redirects the user's browser to your application, with information about how to retrieve the installation and security context.