Adding a Custom Action to Confluence
|Level of experience||BEGINNER|
|Atlassian application||CONFLUENCE 4.X+|
This tutorial shows you how to create a plugin to add a custom action to Confluence. The custom action adds a "draft" label to a Confluence page accessible from the Tools drop-down menu.
Concepts covered in this tutorial:
- Creating a plugin skeleton for Confluence
- Adding a
XWorkmodule to your plugin
- The Confluence
PageAware, Label, Labelableand
To complete this tutorial, you should understand basic Java development – classes, interfaces, methods, and how to use the compiler.
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 Downloads page here: https://bitbucket.org/atlassian_tutorial/confluence-custom-action-tutorial/downloads
Step 1. Create and prune the plugin skeleton
In this step, you'll create a plugin skeleton using
atlas- commands. Since you won't need some of the files created in the skeleton, you'll also delete them in this step.
- Open a terminal and navigate to your Eclipse workspace 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 with
Your terminal notifies you of a successful build:
Change to the project directory created by the previous step.
Delete the test directories.
Setting up testing for your macro isn't part of this tutorial. Use the following commands to delete the generated test skeleton:
Delete the unneeded Java class files.
You'll build a single class for your custom action in later steps.
- Edit the
Remove the generated
Save and close
Import your project into your IDE
Make your project available to Eclipse.
You'll see a successful build message:
You can open a new terminal window to perform this action.
- Click File > Import.
Eclipse starts the Import wizard.
- Expand the General folder tree to choose Existing Projects into Workspace.
- Click Next.
- Click Browse and enter the root directory of your workspace.
Your Atlassian plugin folder should now appear under Projects.
- Ensure your plugin checkbox is ticked and click Finish.
Eclipse imports your project, and it's now visible in your Package Explorer view.
Step 2. Create an
AddDraftLabelAction stub class
You've created the plugin skeleton. Here you'll create a stub class in Java called
AddDraftLabelAction. This class uses the existing class,
ConfluenceActionSupport , to leverage existing methods for managing page labels like
LabelManager . This class also implements
PageAware interface methods to ensure your custom action only engages with current, valid pages.
This step uses Eclipse, but you should be able to use any comparable features in your IDE.
- In Eclipse, locate the
- Right-click the package and choose New > Class.
- Name the class
- Under Superclass, choose
- Under Interfaces, add
Tick the checkboxes to create method stub code with Constructors from superclass and Inherited abstract methods.
AddDraftLabelActionwith stub code.
Here's an example of the class with stub code:
Step 3. Modify the stub code and add an
You've built the foundation for your class, now you'll flesh out the stub code. Your class foundation is built from
PageAware, so it inherits methods that deal with validating or identifying a specific Confluence page. Here you'll add additional interfaces –
Label, Labelable, and
LabelManager– so that your custom action can add a label to a page.
LabelManagerinterfaces to your class.
These interfaces provide access to methods and fields for managing and creating labels in Confluence.
labelManageras instance variables.
Complete the stub code for
getPage()obtains the current Confluence page, and sets the
setPage()defines which page your custom action should interact with.
Modify the stub code to
return truefor methods with a boolean
These methods are all inherited from the
PageAwareinterface. Now your custom action will only execute if the Confluence page is within the scope of user permissions, is defined as a page, and is the most recent version.
executemethod to instantiate a new draft label.
executemethod returns the "success" message as a
String, which your
XWorkmodule in the
atlassian-plugin.xmlfile uses to trigger a page refresh.
Save your changes.
Here's what your finalized
AddDraftLabelAction.javafile should look like:
Step 4. Add a
web-item module to the
atlassian-plugin.xml plugin descriptor
You've built the skeleton for your plugin and finalized a Java class. Now you'll modify the
atlassian-plugin.xml file to describe how Confluence should interact with your code. This file bases these dependencies on your
pom.xml . The
atlassian-plugin.xml file was generated when you created your plugin skeleton.
In this step you'll add a
Web Item module to your plugin. This module type allows you to customize application menus in Confluence with links to your custom action. You can add modules to Confluence with the command
atlas-create-confluence-module, but in this particular case it's more convenient to simply modify the
atlassian-plugin.xml file directly.
- In your IDE, open
This file is located under
- Locate the closing
Add the following directly after the closing
This section defines the
<label>users will see in the Tools menu, and when the custom action is accessible (
system.content.action/primary). There are four sections in the Tools menu: primary, marker, secondary and modify. Designating your plugin's location as primary will place it at the top of the menu.
- Save your changes.
Step 5. Add a
XWork-Webwork module to
Now, you'll add an XWork-Webwork module. Your
Web Item component module defines the label and placement of the custom action. In this step you'll define what the custom action should do within Confluence using an
XWork-Webwork module. The
xwork module will rely on your Java class,
AddDraftLabelAction. This module informs Confluence to reference your Java class to execute on the page. After the draft label is applied,
ApplyDraftLabelAction.java returns a String literal value of "success". This module then uses that message to trigger a "redirect" to the current page; which is the same as a refresh.
atlassian-plugin.xmllocate the closing tag for your newly-added
Add the following on the line after
- Save your changes and close the file.
Update your project changes. If you're an Eclipse user, your directions are as follows:
Here's an example of the complete
Step 6. Build, install, and run your plugin
In this step you'll install your plugin and run Confluence. Then, to test your custom action, you'll add a page and add a "draft" label to the page from the Tools menu.
Open a terminal window and navigate to the plugin root folder.
Start up Confluence from your project root using the
This command builds your plugin code, starts a Confluence instance, and installs your plugin. This may take a few minutes.
Locate the URL for Confluence.
Your terminal outputs the location of your local Confluence instance, defaulted to http://localhost:1990/confluence.
- Open your browser and navigate to your local Confluence instance.
- Login with
- Click Create.
- Choose Blank Page and click Create.
- Add some content and click Save.
- Click Tools > Add 'draft' label.
- Verify that the 'draft' label was applied.