Creating your Plugin Descriptor
On this page:
atlassian-plugin.xmlfile. This is a single file also known as the plugin descriptor. The plugin descriptor is an XML file that describes a plugin and the modules contained within it for the host application. In a plugin project, the file is resides in the
resourcesdirectory. In a plugin submission, the descriptor is located at the root of the plugin's jar file.
The following is a basic descriptor file:
The following sections describe the basic elements in the descriptor XML file.
The root element for your plugin descriptor. For example, the plugin descriptor file should have this structure:
A String identifying the plugin module. This attribute is required and must be unique within the plugin. You should use the reverse domain name notation to ensure your key is unique. In other contexts, you may need to uniquely identify a module. You should use the complete module key.
This is a human-readable name, used for display in menus within the application. By default, the SDK generation commands sets the key for you by referencing the add-on
To create an OSGi plugin, use
The localization key for the human-readable name of the plugin module.
The class that implements this plugin module. The class you need to provide depends on the module type. For example, Confluence theme, layout and colour-scheme modules can use classes already provided in Confluence. So you can write a theme-plugin without any Java code. But for macro and listener modules you need to write your own implementing class and include it in your plugin.
Indicates whether this plugin module is a system plugin module (value='true') or not (value='false'). Only available for non-OSGi plugins.
Contains plugin information displayed by the application for administrators, plugin parameters, and OSGi bundle instructions. Its parent element is
<atlassian-plugin>, and it supports several nested elements.
A human-readable description of your plugin.
The version of your plugin. This number is displayed in the application's plugin manager.
The Java version required for this plugin module. This is an optional value. It is not used consistently among the host applications.
Supply the versions of the application that will support your plugin. Deprecated.
Supply information about the developer of the plugin.
Supply parameter values if required by your plugin.
Declare plugin dependencies and shorten your export package lists by specifying OSGi bundle instructions directly in the plugin XML (OSGi plugins only).
These nested elements are described in more detail below.
Describes your plugin. Its parent element is
The current version of your plugin. Its parent element is
<plugin-info>. The UPM sometimes compares the plugin version value within an application to determine the newer version, particularly when performing automated upgrades. Versions are compared by splitting the version number into components and comparing them numerically first and alphabetically second.
Following are some sample version numbers in ascending order: 0.99, 1.0, 1.0.1-alpha, 1.0.1-beta, 1.0.1-beta2, 1.0.1, 188.8.131.52, 1.1, 1.2, 1.10, 2.0.
Describe which versions of the host application are compatible with this plugin. Enforcement of this property varies between applications: some applications strictly enforce compatibility, while others ignore the value.
Its parent element is
Lowest application version that your plugin is compatible with.
Highest application version that your plugin is compatible with.
The plugin vendor. Provides a link in the plugin administration screens. Its parent element is
Supply your name or the name of the company you work for.
Supply a web site address.
Arbitrary parameters for a plugin. Its parent element is
<plugin-info>. These can be nested in many other elements. Attribute
name gives the parameter name. The element's body is its value.
The name of the parameter.
The value of the parameter.
A common example of a
param element the URL for your plugin's configuration screen. Below is an example.
This element allows you to declare plugin dependencies and shorten your export package lists by specifying OSGi bundle instructions directly in the plugin XML. The element's parent element is
As seen in the above example, the
bundle-instructions element allows child elements, including:
Alternatively, you can declare these instruction sets inside your
The Atlassian Plugin Framework uses the bnd tool to generate OSGi bundles. This tool is available as the Bundle Plugin for Maven. For details of the bnd directives, please refer to the bnd documentation.
Plugin module elements
In the rest of the descriptor XML file, contains any modules that make up your plugin. You can add these modules through the
atlas-* commands or manually. The following illustrates the addition of a
For more information about the modules a plugin can contain, refer to the list of module types for your plugin's host application.
- Creating your Plugin Descriptor
- Accessing Confluence Components from Plugin Modules
- Adding Plugin and Module Resources
- Adding a Configuration UI for your Plugin
- Using Standard Page Decorators
- Making your Plugin Modules State Aware
- Form Token Handling
- Converting a Plugin to Plugin Framework 2
- Enabling TinyMCE Plugins
Information sourced from Plugin Framework documentation