Last updated Dec 28, 2017

Rate this page:

Bamboo Development : Differences between Plugins1 and Plugins2


Plugins Framework

Bamboo uses a library called the Atlassian Plugin Framework to manage its plugins. This library is developed separately to Bamboo (it is a shared library used by all the Atlassian products) and therefore has its own versioning.

For example, Bamboo v2.4 uses Plugin Framework v2.3, Bamboo v2.3 uses Plugin Framework v2.2.

Plugin versions

Before Plugins Framework v2 (Bamboo 2.2 and earlier), plugins were installed in Bamboo by adding the plugin JAR file to Bamboo's classpath (WEB-INF/lib). This style of plugin is referred to as "Plugins1".

Plugins Framework v2 (Bamboo 2.3 and higher) introduced a new way to install plugins. Plugins can be installed in Bamboo's "installed-plugins" directory (under the Bamboo home directory) this sub-folder doesn't exist? from where they will be installed and managed by an OSGi Container. This type of plugin is referred to as "Plugins2".

It is important to note that Plugins2 is not considered a replacement for Plugins1. Each provides some advantages and disadvantages. Plugin developers should consider their particular plugin, and choose which plugin type to use accordingly.


Plugins1 was the original way to install and manage plugins. In Bamboo, these are installed by placing the plugin JAR in your WEB-INF/lib/ directory. (This is a "static plugin". The framework also has another form called a "dynamic Plugins1 plugin", but these are not supported in Bamboo). This means the Java classes in your plugin live in the core application classpath, and are loaded just the same as the core Bamboo classes. If you install two Plugins1 plugins (A and B) in JIRA, then plugin B will be able to use the classes from plugin A as all the classes live in the same ClassLoader. However, Plugin B has no way to declare that it relies on Plugin A. If Plugin A is not installed, then this will cause ClassNotFound exceptions to occur at runtime.


Plugins2 plugins are not installed in the core ClassLoader. They are installed and managed by an OSGi container. This means each Plugin has its own child ClassLoader that loads the classes of that plugin. By default, plugins cannot use the classes of another plugin. However, one plugin can explicitly export some of its packages, and then other plugins can import these dependencies. In this way, the interdependencies can be much better managed.

In addition, a Plugins2 plugin can create its own custom extension points. Effectively, you can allow plugin points for your plugin.

Development and Installation


The JAR file for a Plugins1 plugin looks exactly the same as one for Plugins2 with one difference in the configuration file. The atlassian-plugin.xml for a Plugins2 plugin must declare it is Plugins2 in the <atlassian-plugin> tag.

<atlassian-plugin key="${atlassian.plugin.key}" name="${}" plugins-version="2">


A Plugins1 plugin must be on the application classpath, and therefore is installed in WEB-INF/lib. On the other hand, a Plugins2 plugin must not be on the standard classpath. They are installed in a special subfolder of the Bamboo Home directory - <bamboo-home>/plugins/installed-plugins/.

Java packages

OSGi exports and imports dependencies based on Java packages. Only one ClassLoader can export classes from any given package. Under Plugins2 this means it is even more important to not duplicate package names of core Bamboo classes, or other plugins.

Is there an equivalent Bamboo example Of particular interest is the Webwork plugin module. In JIRA v3.13 and earlier, most Plugin developers probably followed the example in the documentation that showed an Action class in the com.atlassian.jira.web.action package. This meant they could declare a Webwork module with a "simple" class name. This is anyway a bad idea as it allows for possible name-space clashes. Furthermore, it will simply not work under Plugins2. A plugin developer must create an action that lives in a unique package, and include the fully qualified class name of the action in the configuration file. eg:

<webwork1 key="qquserissue" name="Quick Create User Issue" class="java.lang.Object">
<action name="com.atlassian.jira.toolkit.action.QuickCreateUserIssueAction" alias="QuickCreateUserIssue">
<view name="createuserissue">/templates/quickcreateuser.vm</view>

Rate this page: