Installing add-ons

The Universal Plugin Manager (UPM) makes it easy to install add-ons. With just a few clicks, you can browse the Atlassian Marketplace and install add-ons in your application, all without leaving the administration interface of your Atlassian product.

Alternatively, you can install add-ons by file upload. The file upload procedure installs an add-on as a JAR or an OBR (OSGi Bundle Repository) file. The archive file should contain the plugin code and resource files. File upload enables you to install custom add-ons or any add-on not available on Atlassian Marketplace. You can also use it to install add-ons for applications operating behind a firewall and disconnected from the Internet.

On this page:

A note about add-on safety: Add-ons are very powerful; they can change the behavior of almost any part of the Atlassian application. It is very important that you trust an add-on before you install it. Always be aware of where (and who) an add-on comes from.

Add-on framework versions

Add-ons come in three types: Plugins 1, 2, and Atlassian Connect. The most prominent add-on type is Plugins 2. This version number refers to the version of the underlying Atlassian SDK framework used to build the add-on. This identifier is distinct from the add-on's individual versioning scheme, which identifies updates to the add-on software.

Add-ons built with the Plugin 2 SDK use the internal OSGi framework built into Atlassian applications. In some cases, Plugins 1 add-ons may not be installable in the host application. Instead, you must install them manually. If you attempt to install a Plugins 1 add-on using file upload when not supported, an error message similar to the following appears:

The add-on name-version.jar is a type 1 add-on. Type 1 add-ons cannot be dynamically installed. For more information on installing type 1 add-ons see the UPM documentation.

Learn more about installing Plugins 1 type add-ons in JIRA and Bamboo

Installing add-ons directly from Atlassian Marketplace

If you are connected to the Atlassian Marketplace website from your Atlassian application's administration console, you can install add-ons by clicking the Install button from the Find new add-ons administration page. This single-click installation method is the quickest way to install add-ons, although it's not the only way. You can also install by file upload, as described in the next section.

For more information on installing add-ons from the Find new add-ons page, see Finding new add-ons.

Installing by file upload

You can install most add-ons using the single-click installation method, as described in Finding new add-ons. Alternatively, you can install an add-on by uploading it to your Atlassian application. You must use this method to install add-ons that are not available on the Marketplace, such as a custom add-on you created, or if installing an older version of an add-on.

Add-ons are normally distributed as JAR or OBR (OSGi Bundle Repository) files. These are the only types of add-on distribution files that are accepted by the file upload mechanism.

Note that some add-ons are distributed as ZIP files or other types of files other than JARs. These are typically add-ons that run separately from the host application container, such as the JIRA Client. In Atlassian Marketplace, these entries have a Download button that you click to get the add-on.

If you attempt to install a file that isn't a JAR or OBR file in the 'Manage Add-ons' page, the following error appears:

Could not find a handler capable of installing the add-on at filename. Check that the file is a valid add-on.

You should refer to the installation instructions provided with the add-on in this case.

Before installing by file upload, make sure that the add-on distribution file that you want to upload is accessible to your computer either at a file system location or at a network location by URL.

To upload an add-on:

  1. From the application's administration console, click the Manage add-ons link.
  2. Click the Upload add-on link at the top right side of the page. 
    The following dialog appears.

    Upload add-on dialog

  3. Enter the location of the JAR or OBR file to upload using the file chooser or by specifying a network location by entering a URL.
  4. Click Upload.
    A confirmation message appears when the add-on is successfully installed.
  5. If prompted, restart your application to have your change take effect.

You can now manage the add-on from the user-installed add-on list on the Manage add-ons page. 

Installing Plugins 1 type add-ons in JIRA and Bamboo

A few considerations apply to installing or uninstalling add-ons created with the SDK version 1 framework. These types of add-ons are identified in their Marketplace listing as 'Plugins 1' add-ons.

  • You cannot install Plugins 1 add-ons into JIRA or Bamboo using the Universal Plugin Manager. You must download the add-on distribution and follow its specific installation instructions. Such add-ons have a Download button rather than an Install button in their listing. In most cases you will need to move or download the file to the <INSTALL_DIR>/atlassian-jira/WEB-INF/lib directory.
  • Similarly, Plugins 1 JIRA and Bamboo add-ons do not have an Uninstall button. You must remove the add-on from the file system manually.
  • In Confluence, you can install and uninstall Plugins 1 add-ons using the Universal Plugin Manager. You should see an Install or an Uninstall button with the add-on entry.

Once you have downloaded or created your add-on JAR file, follow these steps to install it to JIRA:

  1. Shut down JIRA.
  2. Copy your JAR file (e.g., example_plugin.jar) into the directory:
    • If you are installing a Plugins 1 add-on, copy the JAR file into your JIRA installation directory under atlassian-jira/WEB-INF/lib/.
    • If you are installing a Plugins 2 (OSGi) add-on, copy the JAR file into your JIRA home directory under plugins/installed-plugins/.
  3. Start JIRA.
  4. Confirm the installation by going to Administration > Manage Add-ons. Your add-on (e.g., example_plugin) should appear in the list as enabled.

If you attempt to install a Plugins 1 add-on by copying its JAR file into the installation directory meant for Plugins 2 add-on (or vice versa), JIRA provides a warning indicating that the add-on has been installed into the wrong directory.

However, there may be a very small number of Plugins 1 add-ons (such as the JIRA RPC Plugin) which, if accidentally installed into the Plugins 2 directory (<JIRA home directory>/plugins/installed-plugins/), do not generate this warning. Nevertheless, the add-on does not function correctly and the 'Manage Add-ons' page typically indicates that this add-on has zero modules.

To resolve this problem, reinstall the JAR file into the correct directory as follows:

  1. Shut down JIRA.
  2. Move the JAR file to <JIRA installation directory>/atlassian-jira/WEB-INF/lib/
  3. Restart JIRA.

Related Topics

Viewing an add-on's details

 

Last modified on Oct 6, 2015

Was this helpful?

Yes
No
Provide feedback about this article

Not finding the help you need?

Ask the community

Powered by Confluence and Scroll Viewport.