Skip to end of metadata
Go to start of metadata

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

 

29 Comments

  1. Anonymous

    What is the process for upgrading your own developed plugin?  upgrade tab only talks to atlassian repo it appears.  

    Do you remove the plugin, then install it?

    Or perhaps you can just install it again with new version or overwrite the existing one with same version when iterating?

    Currently I am deleting it, then installing it (via upload).   

     

     

    1. Great question...would love to hear the answer.  Atlassian?

      1. So long as the artifact keys match, just install over it.

  2. You can always upload a plugin by loading the JAR file directly with the Upload Plugin button.  UPM uses the key of the plugin and the version number to distinguish between plugin versions. If you upload a JAR for a plugin and later change the plugin but not its key or version, UPM cannot distinguish between the installed plugin and the one you are trying to upload. IOW, you should change the version between revisions of your plugin. Or, yes, you can always just uninstall the old plugin and upload a new one.

    For information on constructing plugins for use with the UPM — for example an explanation of the metadata found in a plugin JAR — see https://developer.atlassian.com/display/UPM/Coding+for+the+Universal+Plugin+Manager.

    The best place to look for information about programming plugins is Atlassian Developers. 

  3. Anonymous

    I'm trying to upload a confluence language pack JAR file so my team calendar displays with Sunday as first day of the week (similar to Exchange).  I am following all of the instructions but the "Upload Add-on" button is not available in my Administration > Confluence > Add-ons page.  I am using Confluence On-demand – do you think this may be the problem?

    Thanks in advance,

    Mike

    1. Hi Mike,

      Yep, that's the problem. Customers are not currently able to install or remove add-ons in OnDemand. For more about this policy, as well as what the future might hold for add-ons in OnDemand, see the Add-ons in OnDemand page.

       

       

  4. Anonymous

    Thank you Steve.  Do you know of any other way to configure on demand for US languages so I can make the configuration change that I am interested in?

    Thanks,
    Mike 

    1. You can change the default first day of the week from the Team Calendars configuration in OnDemand. Go to Confluence Admin and then choose Team Calendars from the Administration Menu on the left. The "First day of the week" setting is there in the Global Settings tab. Is that what you had in mind?

  5. Great. How do you install a type 1 add-on in Confluence?

    1. For a type 1 add-on in Confluence, try using the file upload method documented above. Unlike JIRA and Bamboo, nothing prevents this from working in Confluence.

  6. In can't find the option "Finding new Add-Ons! 

    1. Hi Pablo, Did you see this page: Finding New Add-ons?  As mentioned there, to see the menu item for finding new add-ons, the UPM must be able to connect to the Marketplace.

      Also, you must be an administrator and you must be using UPM version 2.7 or later (although note that the link was labelled "Find New Plugins" for 2.7).

  7. Iam new to Confluence , After installing the addon how to run it ?

    For Eg : i installed the search replace but not sure how to run same.

     

    1. Welcome to Confluence!

      There are quite a few search and replace type add-ons for Confluence, so I'm unable to provide specific help there, but in general, if the add-on is available on the Atlassian Marketplace (https://marketplace.atlassian.com/), check whether its listing on the Marketplace includes a link to documentation for using that add-on. Look for a Documentation link in the "Resources" section of the listing. Of course, usage information will vary greatly between add-ons, and not all add-ons come from the Marketplace. In that case, the add-on developer may have provided separate documentation for the add-on. Short of that, a  search of http://answers.atlassian.com/ may also turn up some help.

  8. Anonymous

    We have attempted to upgrade our Agile plugin from 5.6 to 5.8.7 for our JIRA 4.4.5 install. We tried the Plugin Manager upgrade and it said the install was successful however the "Greenhopper is unavailable" banner appeared and it was not functional. We got 'nullpointer exception" errors in the log. We then tried moving the .jar to the installed-plugins directory and restarting the server. Same issue. Any ideas on who to contact for a walk-through on this upgrade.

  9. Please contact support@atlassian.com and they will help you.

  10. I can't find the upload add-on link in my Manage Add-ons page.

    What am I missing?

    1. Hi Maurizio,

      You won't normally see this option for Atlassian-hosted OnDemand (cloud) instances with UPM, just with local (server) instances. If you've been given a I hope that helps! I'll update the docs too. 

      However, you will see "Upload add-on" in the Manage add-ons page if you're developing an add-on for Atlassian Connect, and if you have Enable private listings checked under Settings. If this applies to you, check out our Connect documentation here: https://developer.atlassian.com/static/connect/docs/developing/cloud-installation.html.

  11. Hi, we're using OnDemand.

    when i try to upload a file, i do not see the link to browse to local file from my computer, only the URL field.

    I do have the UPM installed.

    Any thoughts please?

    Thanks you in advance. 

    1. Hi Motti Paz Lazar,

      As mentioned in comments above, you are not able to upload a file to UPM in Atlassian Cloud (formerly OnDemand). You can use the URL field to install new Connect add-ons, however.

  12. Hello!

    I can not find the "from my computer field". If I should use the "From this url" field, where can I find the right url? I am trying to add this plugin: https://marketplace.atlassian.com/plugins/eu.softwareplant.bigpicture

    Thanks for your help,

  13. Hi there,

    Is it possible to edit or append the INSTALLATION panel in Marketplace listing? Our add-on requires some additional steps after the initial install.

    Thanks for your the help!

  14. I cannot find any "Upload" link. In fact cannot find that text on the page https://somecompany.atlassian.net/plugins/servlet/upm, except only in the "You can install, update, enable, and disable add-ons here" label

  15. Where is the upload button???

    All I see is a Build new add-on.

    I do see a redmine plugin in the system plugins, but how do you use it or enable it???

    Come on, seriously???

    1. I have the same problem.

      Still, I don't see any feedback from Atlassian team.

  16. We're trying to install an add-on on our server installation of JIRA. We have purchased the add-on and installed it manually (our servers have a firewall preventing internet access). We tried entering the license key for the add-on, but the key is being called invalid because the JIRA server cannot reach the internet (we checked the logs and it's trying to contact the marketplace). How can we enter the license key for the plugin without having JIRA go out to the internet to validate the license key?

  17. I am not able to see "upload add-on" option. Why is that?

  18. Is there a way to enable an add-on for a specific project or projects only? I'm interested in trying the User Story Map add-on but don't want to enable it for all projects until we've had a chance to try it out on a closed project.

  19. Hi - having trouble with "Upload Add On" - I've enabled both Developer Mode and Private Listings Modes and I'm still only able to upload an add-on from a URL. I'm not seeing an option to Browse for a file.