Skip to end of metadata
Go to start of metadata

Applicable:

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.

Time estimate:

It should take you approximately 1 hour to complete this tutorial.

On this page:

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.

Icon

If you are already familiar with the Atlassian SDK and just want to learn how to use the Notification API, go straight to Step 5!

Prerequisite knowledge

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.

Plugin source

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:

git clone https://bitbucket.org/atlassian_tutorial/confluence-notification

Alternatively, you can download the source using the get source option here: https://bitbucket.org/atlassian_tutorial/confluence-notification.

About these Instructions

Icon

You can use any supported combination of OS and IDE to construct this plugin. These instructions were written using IntelliJ IDEA Ultimate 11.1 on a MacBook Pro running Mac OS X. If you are using another combination, you should use the equivalent operations for your specific environment.

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.

  1. Open a terminal and navigate to your plugin directory.
  2. Enter the following command to create a Confluence plugin skeleton:

    atlas-create-confluence-plugin
    

    When prompted, enter the following information to identify your plugin:

    group-id

    com.example.plugins.tutorial.confluence

    artifact-id

    tutorial-confluence-notification

    version

    1.0-SNAPSHOT

    package

    com.example.plugins.tutorial.confluence.notification

  3. Confirm your entries when prompted.
  4. Change to the tutorial-confluence-notification directory 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.

  1. Edit the pom.xml file in the root folder of your plugin.
  2. Add your company or organisation name and your website to the <organization>element:

    <organization>
        <name>Example Company</name>
    	<url>http://www.example.com</url>
    </organization>
  3. Update the <description>element:

  4. 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:

  1. Open the pom.xml file.
  2. Scroll to the bottom of the file.
  3. Find the <properties> element.
    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.
  4. Verify that the Confluence version is 4.3 or higher.

  5. Save the pom.xml file.

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.

Icon

Since writing an administration screen is not the point of this particular tutorial, we won't go into the details here. If you are interested in the implementation details, you can:

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

Now that our administration screen is up and running, let's create  a REST resource that will be called by some JavaScript on our admin page.

We will define 2 end points:

URIMethodDescription
/rest/notification/latest/POSTSend a notification to all members of the "confluence-users" group.
/rest/notification/latest/GETList all available notifications sent by this plugin.

Let's start by adding the following REST-related dependencies to our pom.xml:

 

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 atlassian-plugin.xml:

And we can now have it injected and use it in our Resource:

The code to create a notification is extremely simple:

Icon

Notifications are created asynchronously. notificationService.createOrUpdate returns a Future<Notification>

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.  

  1. Make sure you have saved all your code changes to this point.
  2. Open a terminal window and navigate to the plugin root folder (where the pom.xml file is).
  3. Run the following command:

    atlas-run
    

    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:

    [INFO] Confluence started successfully in 71s at http://localhost:1990/confluence
    [INFO] Type CTRL-D to shutdown gracefully
    [INFO] Type CTRL-C to exit
    
  4. Open your browser and navigate to the local Confluence instance started by atlas-run.
    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.
  5. At the Confluence login, enter a username of admin and a password of admin.
  6. Create a notification from the admin screen (http://localhost:1990/confluence//plugins/servlet/notification/admin) and click Notify:
     
  7. 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.

 

And now by calling this URI from our JavaScript, we can display the most recent notifications in a table on the admin page.

 

Icon

If you want to learn more about notifications: