HipChat Integration

YouTrack supports integration with a HipChat Server. With this integration, you can send notifications to a HipChat room when:

A new issue is created in a specific project.
An existing issue is updated in a specific project.

This integration is designed for use on a per-room basis in HipChat, and is enabled on a per-project basis in YouTrack. For best results, we recommend that you enable this integration for HipChat rooms where users who have permission to view issues in a related YouTrack project meet to discuss their work.

To set up an integration with HipChat, follow these steps:

Install a Per-Room Integration on Your HipChat Server
Customize the HipChat Integration Workflow
Enable the HipChat Integration Workflow in YouTrack

The basic setup described here lets you post updates from a single YouTrack project to a specific room in HipChat. For more complex integrations, see Multi-room and Multi-project Configurations.

Install a Per-Room Integration on Your HipChat Server

The HipChat integration is enabled on a per-project basis in YouTrack. For this reason, it is designed to support per-room integration.

To install a per-room integration:

In your HipChat Server, open the Group admin > Rooms page.
Select a room.
Click Integrations in the left menu bar.
On the Integrations page, select Build your own integration.
Enter a name for your integration and click the Create button.
- HipChat displays the URL you need to send messages to this room.
Copy the post URL for your HipChat room and paste it into a text editor. In the following procedure, you add this URL to your workflow rules in YouTrack.
Click the Save button.

Customize the HipChat Integration Workflow

The next step is to edit the HipChat Integration workflow so it sends notifications to your HipChat room.

This workflow contains two rules: Issue Added and Issue Modified. To receive notifications when issues are added and modified, customize both rules with the URL for your room in HipChat.

To customize the HipChat Integration workflow:

Download the HipChat Integration workflow from the YouTrack Custom Workflow Repository.
Open the YouTrack Workflow Editor.
From the Workflow menu, select Import Workflow from File.
Select the ZIP archive that you downloaded in step 1.
- The workflow is imported into the workflow editor.
Open the first workflow rule that you want to customize.
Locate the URLs variable declaration in the code.
Replace the whole URL with the URL that you copied from your HipChat server in the previous procedure. Specifically, you need to replace the following placeholders in the workflow rule with variables from your HipChat Server:
The workflow rules have placeholders for two URLs.

When you specify the URL for a single HipChat room, set the URL in quotation marks and remove the trailing comma.

Placeholder Value
TEST_INSTANCE Replace with the subdomain of your HipChat Server.
room_number Replace with the ID of the HipChat room.
TOKEN Replace with the auth token for your HipChat room.

Your variable declaration should look something like this:

var URLs = " https://subdomain.hipchat.com/v2/room/1234567/notification?auth_token=AbC4EfGhIjKlMNoPqRsTu1nFrS1tp0w". split(",", opts);
Repeat steps 6 and 7 for the second workflow rule.
From the Workflow menu, select Upload Workflows to Server.
- The customized workflows are uploaded to your YouTrack server.

Placeholder	Value
`TEST_INSTANCE`	Replace with the subdomain of your HipChat Server.
`room_number`	Replace with the ID of the HipChat room.
`TOKEN`	Replace with the auth token for your HipChat room.

Enable the HipChat Integration Workflow in YouTrack

The last step is to attach the HipChat Integration workflow to your project in YouTrack.

To enable the HipChat Integration workflow:

Open the project that you want to integrate with HipChat.
Click the Edit project link.
Select the Workflow tab.
From the Attach workflows list, select jetbrains-youtrack-hipchat.
- The HipChat Integration workflow is attached to your project.
Expand the workflow and select the Issue Added rule.
If the requires setup flag is displayed, click the Configure project button.
- The custom field (State) that is required for the workflow is added to your project.
- The workflow is enabled and ready for use with your project.

When the setup is complete and the workflow is attached to your project:

Notification is sent to the room when an issue is created in the project.
Notification is sent to the room when an issue in the project is updated.

In each notification, the notification subject and YouTrack issue ID are set as direct links to the issue in YouTrack.

Multi-room and Multi-project Configurations

The basic setup lets you post updates from a single YouTrack project to a specific room in HipChat. However, you can easily configure this setup for more complex integration scenarios.

One Project, Many Rooms

The HipChat Integration workflow is scripted to support an integration between one YouTrack project and multiple rooms in HipChat. You can build integrations for different rooms in HipChat and add the URL for each room to your workflow rules.

The following lines of code in the workflow can be customized to send notifications to multiple rooms from a single project:

var URLs = "
    https://TEST_INSTANCE.hipchat.com/v2/room/room_number/notification?auth_token=TOKEN,https://TEST_INSTANCE.hipchat.com/v2/room/room_number/notification?auth_token=TOKEN".
    split(",", opts);

The workflow that you download from the repository contains placeholders for two rooms. The split operation uses the , character to split the string that is set in quotation marks into separate URLs for each room.

With this format, you can continue to add comma-separated URLs for multiple rooms to the workflow.

Many Projects, One Room

If you want to send notifications from multiple YouTrack projects to a single room in HipChat, the setup is relatively simple.

Follow the steps described here to add the URL for your HipChat room to the workflow rules.
Attach this workflow to all of the projects you want to report to HipChat.

Separate Projects, Separate Rooms

In a slightly more complicated setup, you have multiple teams who discuss different projects in separate rooms. You want to direct notifications from specific projects to the rooms where each team meets to discuss their issues.

The easiest way to handle this situation is to create separate workflows for each project and customize the rules accordingly.

To support this use case:

Create a new workflow in the workflow editor. Give the workflow a name that shows its relationship to the project where it will be applied.
Copy the rules from the HipChat Integration workflow and past them to the new workflow.
Update the URLs in the workflow rules to reference the HipChat rooms that you want to notify in this project.
Repeat steps 1 through 3 for every room or set of rooms that you want to notify in each project.
Upload the workflows to your server.
Attach each workflow to the project for which it has been customized.

An alternative approach is to add conditional statements to your workflow rules. With conditional statements, you can identify the project that each issue belongs to and send notifications to dedicated rooms in HipChat. You can then attach the same workflow to all of the projects that are referenced in the workflow and update the same set of workflow rules when you want to enable HipChat integration in a new project.

To support this use case, add a conditional statement to the URLs variable declaration. Use the following sample as a guide:

var URLs = "";
if (issue.project.shortName == "Project_ 1") {
    URLs = "https://TEST_INSTANCE.hipchat.com/v2/room/room_1/notification?auth_token=TOKEN".split(",", opts);
} else if (issue.project.shortName == "Project_2") {
    URLs = "https://TEST_INSTANCE.hipchat.com/v2/room/room_2/notification?auth_token=TOKEN".split(",", opts);
}

To send notifications to multiple rooms in each project, replace the single URL with a comma-separated list of URLs. The split operation splits the string that is set in quotation marks into separate URLs for each room.

Last modified: 2 February 2017