Adding new Confluence to HipChat notifications
This tutorial applies to Confluence 5.8 or higher
(or Confluence 5.5 and higher, if the HipChat for Confluence plugin (6.14.0 or greater) is installed)
Level of experience:
This is an intermediate tutorial. You should have completed at least one beginner tutorial before working through this tutorial.
It should take you approximately 1 hour to complete this tutorial.
On this page:
This tutorial shows you how to add support for a new HipChat space to room notification in Confluence. In this tutorial we'll add a new notification type, which sends a notification to a HipChat room when a comment is created.
To complete this tutorial, you must already understand:
- The basics of Java development: classes, interfaces, methods, how to use the compiler, and so on.
- How to create an Atlassian plugin project using the Atlassian Plugin SDK.
We encourage you to work through this tutorial. If you want to skip ahead or check your work when you are done, you can find the plugin source code on Atlassian Bitbucket. To clone the repository, use the following command:
Alternatively, you can download the source using the get source option here: https://bitbucket.org/atlassian/tutorial-confluence-hipchat-notification/downloads
Step 1. Create the plugin project
In this step, you'll use the
atlas-create command to generate stub code for your plugin. The
atlas- commands are part of the Atlassian Plugin SDK, and automate much of the work of plugin development for you.
- Open a terminal and navigate to your plugin directory.
Enter the following command to create a Confluence plugin skeleton:
When prompted, enter the following information to identify your plugin:
- Confirm your entries when prompted.
- Change to the
tutorial-confluence-hipchat-notificationdirectory created by the previous step.
Step 2. Review and tweak the generated stub code
It is a good idea to familiarise yourself with the stub plugin code. In this section, we'll check a version value and tweak a generated stub class. Open your plugin project in your IDE and follow those steps.
Add plugin metadata to the POM
Add some metadata about your plugin and your company or organization.
- Edit the
pom.xmlfile in the root folder of your plugin.
Add your company or organisation name and your website to the
- Save the file.
Verify your Confluence version
When you generated the stub files, the Confluence version you chose was added to your
pom.xml file (Project Object Model definition file). This file is located at the root of your project and declares the project dependencies. Take a moment and examine the Confluence dependency:
- Open the
- Scroll to the bottom of the file.
- Find the
This section lists the version of the Confluence version you selected in Step 1 and also the version of the
atlas-commands you are running.
Verify that the Confluence version is 5.8 or higher.
- Save the
Review the generated plugin descriptor
Your stub code contains a plugin descriptor file
atlassian-plugin.xml. This is an XML file that identifies the plugin to the host application (Confluence) and defines the required plugin functionality. In your IDE, open the descriptor file which is located in your project under
src/main/resources and you should see something like this:
Step 3. Create a new HipChat notification type
First, let's add some dependencies to the
pom.xml file that are needed to implement a new notification type.
You will also need to add the
hipchat.notifications.version property in the properties section of the
Now to define the notification type that we are adding, we'll need to add it to the
component-import declaration. This is required if you're implementing the default message rendering provided by the API, which we'll be doing in this tutorial.
hipchat-notification-type is what defines a new notification type:
|key||Unique id within the plugin.|
|class||The implementation of the notification type, this should extend the
|.value||This is the unique value representing this notification type.|
|name||A name for this type.|
|i18n-key||The i18n key in the i18n properties file for the text that will be displayed on the configuration page.|
|context||The context where this notification type is used. Currently only spaceis available.|
Here's the code to create a notification type for when a comment is created:
Finally, we need to add the i18n messages to our i18n properties file, not the parameterised format for the
hipchat.notification.message.comment.added message that is sent to HipChat:
And that is all there is to it ! Let's run our plugin and create some notifications.
Step 4. Build, install and run the plugin
Follow these steps to build and install your plugin, so that you can test your code.
- Make sure you have saved all your code changes to this point.
- Open a terminal window and navigate to the plugin root folder (where the
Run the following command:
This command builds your plugin code, starts a Confluence instance, and installs your plugin. This may take several seconds. When the process is complete, you'll see many status lines on your screen concluding with something like:
- Open your browser and navigate to the local Confluence instance started by
If you used the settings in the instructions, the default port is 1990.
- Navigate to your local Confluence, enter http://localhost:1990/confluence/ in your browser.
- At the Confluence login, enter the username
- Integrate Confluence with HipChat by navigating to http://localhost:1990/confluence/plugins/servlet/hipchat/configure and following the prompts. Create a test group in HipChat, if required.
- Configure space to room notifications and enable your new notification:
- Comment on a page, and you should see your notification appear in HipChat:
Step 5. Expand the plugin by using a custom message format and icon
You can introduce custom messages by overriding
getMessagein your implementation class. The message is expected to be in HTML format, so be sure to escape any parameterised content. The HipChat API documentation describes the restrictions on the supported HTML element.
Similarly you can provide custom icons for display in messages by implementing your own version of the
com.atlassian.hipchat.api.icons.Icon interface, or creating an instance of
The icon instance can be returned from the
getIcon method, if you're using the default message rendering, or you can use it within your own implementation of