This tutorial applies to Confluence 4.3 or higher
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:
- Overview of the tutorial
- Step 1. Create the plugin project
- Step 2. Review and tweak the generated stub code
- Step 3. Create a basic administration screen
- Step 4. Creating a REST resource
- Step 5. Create some notifications
- Step 6. Build, install and run the plugin
- Step 7. Expand the plugin by listing past notifications on the admin screen
Overview of the tutorial
This tutorial shows you how to use the Notification API in Confluence. The completed plugin will consist of a simple administration page that is used to send notifications to all users of the wiki. One typical use case is to announce a scheduled maintenance.
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. Bitbucket serves a public Git repository containing the tutorial's code. To clone the repository, issue the following command:
Alternatively, you can download the source using the get source option here: https://bitbucket.org/atlassian_tutorial/confluence-notification.
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-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 4.3 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 basic administration screen
For this tutorial, we will need a basic administration screen where the notification message to be sent to all wiki users is entered.
This is what the administration screen used in this tutorial looks like:
Pretty simple, but it will serve the purpose!
Step 4. Creating a REST resource
We will define 2 end points:
|/rest/notification/latest/||POST||Send a notification to all members of the "confluence-users" group.|
|/rest/notification/latest/||GET||List all available notifications sent by this plugin.|
Let's start by adding the following REST-related dependencies to our
Then let's add the REST module to our
atlassian-plugin.xml, note that the path to access our REST resource is "/notification" in this case.
And finally let's create the NotificationResource class:
You can now try to access your 2 REST resources using curl:
- curl --user admin:admin http://localhost:1990/confluence/rest/notification/latest/
- curl --user admin:admin -X POST http://localhost:1990/confluence/rest/notification/latest/
Step 5. Create some notifications
Ok, now that we have our REST endpoints up and running, let's add some code to the "create notification" URI. To do this, we need to add the Notification API dependency to our pom.xml:
We also need to import the NotificationService component to
And we can now have it injected and use it in our Resource:
The code to create a notification is extremely simple:
Now let's iterate on all users of the "confluence-users" group and send a notification to each of them:
Finally, let's call the last method from our createNotification URI:
And that is all there is to it ! Let's run our plugin and create some notifications.
Step 6. 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 in it. This may take several seconds or so. When the process completes, you will see many status lines on your screen concluding with something like the following lines:
- 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. To navigate to the local Confluence, enter http://localhost:1990/confluence//plugins/servlet/notification/admin in your browser.
- At the Confluence login, enter a username of
adminand a password of
- Create a notification from the admin screen (http://localhost:1990/confluence//plugins/servlet/notification/admin) and click Notify:
- All your users will receive a new notification in their inbox!
Step 7. Expand the plugin by listing past notifications on the admin screen
Now you have a basic plugin that you can use to send notifications to all your users. You can expand its functionality so that administrators can see the most recent sent notifications (so that no duplicate notification is sent by mistake for example).
Let's implement the
findAllNotifications() method that we declared earlier in this tutorial.