This page last changed on Sep 07, 2009 by smaddox.

On this page:

Purpose of a Plugin Descriptor

When developing a plugin for an Atlassian application such as Confluence or JIRA, you need to create a 'plugin descriptor' for your plugin.

The plugin descriptor is an XML file that tells the application all about the plugin and the modules contained within it. The descriptor must be a single file named atlassian-plugin.xml and must be located at the root of the plugin's jar file.

Example of a Plugin Descriptor

Here is a sample plugin descriptor:

<!-- Every plugin must have a key, which identifies the plugin uniquely to the system -->
<!-- and a name, which is used to display the plugin in menus. -->
<atlassian-plugin key="com.atlassian.confluence.plugins.example" name="Example Plugin" plugins-version="2">

  <!-- The plugin info block allows you to provide more information about your plugin -->
  <plugin-info>
    <description>
      A sample plugin for demonstrating the file format.
    </description>
    <!-- This version is displayed in the application's Plugin Manager. -->
    <version>1.0</version>
    <!-- The versions of the application this plugin is is compatible with -->
    <application-version min="1.3" max="1.3"/>
    <vendor name="Atlassian Software Systems Pty Ltd" url="http://www.atlassian.com/"/>
    <!-- The location of any plugin configuration (optional) -->
    <param name="configure.url">/admin/plugins/example/configurePlugin.action</param>
    <!-- Specifically declare bundle instructions (optional) -->    
    <bundle-instructions>
      <Export-Package>my.external.pkg</Export-Package>
      <Import-Package>com.mylibrary,*;resolution:=optional</Import-Package>
    </bundle-instructions>
  </plugin-info>

  <!-- Here is where you define your modules. The code you use        -->
  <!-- to define a module depends on the module itself. This is just  -->
  <!-- a sample, which will not load if installed into Confluence     -->

  <!-- Modules must have a key that is unique within the plugin, a name -->
  <!-- and an implementing class. -->
  <example key="module1" name="Example Module" class="com.atlassian.confluence.plugins.example.ExampleModule">
    <!-- All modules can optionally have a description -->
    <description>An example module</description>
  </example>
</atlassian-plugin>

Contents of the Plugin Descriptor

Below is a description of the plugin information provided in the descriptor XML file.

atlassian-plugin element

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

<atlassian-plugin key="com.atlassian.confluence.plugins.example" name="Example Plugin" plugins-version="2">
    <!-- ... -->
</atlassian-plugin>
Attribute Description
key Each plugin has a plugin key which must be unique to the plugin. We suggest using the Java convention of reversing your domain name in order to ensure your key is unique.
The plugin key must be defined in lower case in the plugin descriptor. When you call the plugin via a macro in Wiki Markup, you can use any capitalisation, e.g. {module1} or {Module1}.
Within the plugin, each module has a module key. Refer to the information on module types for information about the module key.
name This is a human-readable name, used for display in menus within the application.
state To disable the entire plugin by default, specify <atlassian-plugin state="disabled"/>.
plugins-version To create an OSGi plugin, use plugins-version="2".
The attribute pluginsVersion is still supported but has been deprecated since version 2.1 of the plugin framework.

plugin-info element

This 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.
<application-version> Supply the versions of the application that will support your plugin.
<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.

description element

The body of this element is a description of your plugin. Its parent element is <plugin-info>.

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

version element

The body of this element is the current version of your plugin. Its parent element is <plugin-info>.

Plugin versions are sometimes compared 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.

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

application-version element

Deprecated since Atlassian Plugin Framework 2.2

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 <plugin-info>.

Attribute name Description
min This is the lowest version of the application which your plugin is compatible with.
max This is the highest version of the application which your plugin is compatible with.
<atlassian-plugin ...>
    <plugin-info>
        <!-- ... -->
        <application-version min="2.0" max="2.7" />
    </plugin-info>
</atlassian-plugin>

vendor element

The vendor of the plugin. 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.
<atlassian-plugin ...>
    <plugin-info>
        <!-- ... -->
        <vendor name="Acme Systems Ltd" url="http://acme.example.com/" />
    </plugin-info>
</atlassian-plugin>

param element

Arbitrary parameters for a plugin. These can be nested in many other elements. Attribute 'name' gives the name of the parameter. The body of the element is its value.

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

One commonly used parameter is the URL for your plugin's configuration screen. Its parent element is <plugin-info>. Below is an example.

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

bundle-instructions element

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 <plugin-info>.

<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>
  • <Import-Package>

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.

Elements Describing Plugin Modules

In the rest of the descriptor XML file, you will define any modules that make up your plugin. Please refer to the list of module types for more information.

RELATED TOPICS

Writing Confluence Plugins

Information sourced from Plugin Framework documentation

Document generated by Confluence on Nov 05, 2009 23:34