atlassian-plugin.xml element reference

The atlassian-plugin.xml file describes your plugin to Atlassian applications like Jira or Confluence. For this reason, you'll often see this file referred to as the descriptor. This file describes important elements like your plugin component modules and visual resources that the Universal Plugin Manager (UPM) uses.

The following sections describe some of the basic elements in the descriptor XML file.

The atlassian-plugin element

This is the root element for your plugin descriptor. The plugin descriptor file should have this structure:

1
2
<atlassian-plugin key="com.atlassian.confluence.plugins.example" name="Example Plugin" plugins-version="2">
    <!-- ... -->
</atlassian-plugin>

Attribute	Description
`key`	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. By default, the SDK generation commands sets the key for you by referencing and concatenating the `groupId` and `artifactId` from the `pom.xml`.
`name`	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 `name` from the `pom.xml`. You should not use the words 'plugin' or 'add-on' in this value.
`state`	This is `enabled` by default. To disable the entire plugin, specify `disabled`.
`plugins-version`	To create an OSGi plugin, use `plugins-version="2"`. NOTE: The attribute `pluginsVersion` was deprecated in version 2.1 of the plugin framework.
`i18n-name-key`	The localization key for the human-readable name of the plugin module.
`class`	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.
`system`	Indicates whether this plugin module is a system plugin module (value='true') or not (value='false'). Only available for non-OSGi plugins.

The `plugin-info` element

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.

Nested element	Description
`<description>`	A human-readable description of your plugin.
`<version>`	The version of your plugin. This number is displayed in the application's plugin manager.
`<java-version>`	The Java version required for this plugin module. This is an optional value. It is not used consistently among the host applications.
`<vendor>`	Supply information about the developer of the plugin.
`<param>`	Supply parameter values if required by your plugin.
`<bundle-instructions>`	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.

The `description` element

Describes your plugin. Its parent element is <plugin-info>.

1
2
<atlassian-plugin ...>
    <plugin-info>
        <!-- ... -->
        <description>New macros for integration with Acme Corp. web services</description>
    </plugin-info>
</atlassian-plugin>

The `version` element

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, 1.0.1.0, 1.1, 1.2, 1.10, 2.0.

1
2
<atlassian-plugin ...>
    <plugin-info>
        <!-- ... -->
        <version>1.2</version>
    </plugin-info>
</atlassian-plugin>

The `vendor` element

The plugin vendor. Provides a link in the plugin administration screens. Its parent element is <plugin-info>.

Attribute name	Description
`name`	Supply your name or the name of the company you work for.
`url`	Supply a web site address.

1
2
<atlassian-plugin ...>
    <plugin-info>
        <!-- ... -->
        <vendor name="Acme Systems Ltd" url="http://acme.example.com/" />
    </plugin-info>
</atlassian-plugin>

The `param` element

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.

Attribute	Description
`name`	The name of the parameter.
(body)	The value of the parameter.

A common example of a param element the URL for your plugin's configuration screen. Below is an example.

1
2
<atlassian-plugin ...>
    <plugin-info>
        <!-- ... -->
        <param name="configure.url">/admin/plugins/example/configurePlugin.action</param>
    </plugin-info>
</atlassian-plugin>

The `bundle-instructions` element

**This element should not be used when using Spring Scanner transformerless plugins as it will be ignored. The preferred way to set OSGi instructions is the <instructions> element in the pom..xml.

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 list is used to generate the OSGi manifest. If you do not specify bundle instructions in the plugin descriptor or, alternatively, in the POM, the SDK generates one for you.

The element's parent element is plugin-info.

1
2
<atlassian-plugin ...>
    <plugin-info>
        <!-- ... -->
        <bundle-instructions>
          <Export-Package>my.external.pkg</Export-Package>
          <Import-Package>com.mylibrary,*;resolution:=optional</Import-Package>
        </bundle-instructions>
    </plugin-info>
</atlassian-plugin>

As seen in the above example, the bundle-instructions element allows child elements, including Export-Package and Import-Package.

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 web-item module:

1
2
<web-item name="Radio Paradise" i18n-name-key="radio-paradise.name" key="radio-paradise" section="client-sites-link/my-section" weight="1000">
    <description key="radio-paradise.description">The Radio Paradise Plugin</description>
    <label key="radio-paradise.label"></label>
    <link linkId="radio-paradise-link">http://www.radioparadise.com</link>
  </web-item>

For more information about the modules a plugin can contain, refer to the list of module types for your plugin's host application.