Managing JIRA's Plugins

About 'Version 1' Plugins and 'Version 2' Plugins

There are two types of Atlassian plugins:

• 'Version 1' Plugins — These plugins are compatible with the 'old' plugin framework that was used in JIRA prior to version 4.0, and also with the 'new' plugin framework used in JIRA version 4.0 and later. 'Version 1' plugins are installed into your JIRA Installation Directory under atlassian-jira/WEB-INF/lib/. 'Version 1' plugins must be installed manually (see below) and uninstalled manually (see below).
• 'Version 2' Plugins — These plugins are compatible with the 'new' plugin framework used in JIRA version 4.0 and later. 'Version 2' plugins are installed automatically, using the JIRA administration interface (see below). They are installed into your JIRA Home Directory under plugins/installed-plugins/. 'Version 2' plugins are deployed in an internal OSGi container to isolate the plugin from the core code and other plugins, and to allow sophisticated dependency management. 'Version 2' plugins have to be specifically declared as such, using the plugins-version="2" attribute in the plugin's configuration file (atlassian-plugin.xml).

How do I tell if a Plugin is 'Version 1' or 'Version 2'?

Go to https://plugins.atlassian.com and look at the plugin's details. The 'Plugin System' field will show 'ONE' for Version 1 plugins and 'TWO' for Version 2 plugins.

Installing a JIRA Plugin

Installing a plugin from the Atlassian Plugin Exchange

To find and add a plugin from the Atlassian Plugin Exchange:

1. Click the Install tab in the UPM. You will see a list of featured plugins.
2. Search for your plugin as follows:
   • Enter some keywords that describe the plugin in the Search the Plugin Exchange search box and press Enter.
   • Alternatively, browse to the desired plugin in the list. You can choose Featured, Popular, Supported (by Atlassian) or All available from the Plugins to show dropdown to see a different list of plugins.
3. Click the Install button for the desired plugin to add it to your application. A confirmation message and the plugin details will appear when the plugin is installed successfully.
   Note: You may need to restart your application for your change to take effect. The Universal Plugin Manager will inform you if this is the case.
   Note: Not all plugins can be automatically installed. Some required manual installation. These plugins will have a Download button instead of an Install button. In these cases, you should read and follow the plugin's installation instructions.

Screenshot: Finding a new plugin from the Atlassian Plugin Exchange

UPM-InstallPlugins.png

Installing your own plugin

To upload your own plugin:

1. Click the Install tab in the UPM.
   The system displays a list of featured plugins.
2. Click the Upload Plugin link.
   The system displays the Upload Plugin window.
3. Specify the location of your plugin:
   • If the plugin you want to install is on your computer, use the Browse dialogue to choose the plugin JAR file.
   • If you want to install a plugin from a remote location, enter the URL of the plugin JAR file in the From this URL text box.
4. Click the Upload button to upload and enable your plugin. A confirmation message will appear when the plugin is successfully installed.
   Note: You may need to restart your application for your change to take effect. The Universal Plugin Manager will inform you if this is the case.

Screenshot: Uploading a new plugin

UPM-InstallPlugins-UploadPlugin.png [updated as per https://studio.atlassian.com/browse/UPM-1031]

Installing a plugin manually

You will need to install plugins manually if:

• you are installing a 'Version 1' plugin; or
• your JIRA server does not have access to the internet (in which case the Universal Plugin Manager will be unable to access http://plugins.atlassian.com).

Viewing Installed Plugins

Screenshot: Finding installed JIRA plugins, using the Universal Plugin Manager
Some tabs will not be visible if you do not have the JIRA System Administrators global permission

upm_manage_plugins.png

Updating a JIRA Plugin

To upgrade a plugin:

1. Click the Manage my plugins tab. You will see a list of plugins that are available for upgrading, under the heading 'Available Updates'.
   
   • If there is a later version of a plugin that you have already installed, this page will show the latest compatible version of the plugin.
   • You can click the plugin name to expand the row and see more information about the plugin.
   • You can filter your list by entering keywords in the Filter visible plugins text box.
2. Click the name of the plugin that you want to upgrade, to see more information about the plugin.
3. Click the Update button next to the plugin to update it to the version shown.

To upgrade all available plugins:

1. Click the Manage my plugins tab. You will see a list of plugins that are available for upgrading, under the heading 'Available Updates'.
   
   • If there is a later version of a plugin that you have already installed, this page will show the latest compatible version of the plugin.
   • You can click the plugin name to expand the row and see more information about the plugin.
   • You can filter your list by entering keywords in the Filter visible plugins text box.

2. Click the Update All button to upgrade every plugin to the plugin versions shown.

   Note: Not all plugins can be installed or upgraded via the Universal Plugin Manager. There are some plugins that you must manually install and upgrade.

Disabling a JIRA Plugin

To disable a plugin:

1. Click the Manage Existing tab. You will see a list of the plugins installed in your application. Enabled plugins will have this icon: UPMIcon-EnabledPlugin.png
2. Locate the plugin that you want to disable and click the title to expand the plugin details section.
3. Click the Disable button.
4. Once a plugin has been disabled, you may need to restart your application for your change to take effect. If so, you will see a message for the plugin, Disabled, requires restart.
   Once the plugin is fully disabled, you will see an Enable link for the plugin.

Also note that JIRA can automatically disable plugins if they cause errors on startup or initialisation. This is usually caused by having an old version of the plugin that is not compatible with your current version of JIRA. If this occurs, it will be indicated on the 'Current Plugins' page (shown above). You will need to stop JIRA, install the newer version of the plugin and restart JIRA.

Enabling a JIRA Plugin

Note: newly installed plugins are enabled by default.

To enable a plugin:

1. Click the Manage Existing tab. You will see a list of the plugins installed in your application. Disabled plugins will have this icon: UPMIcon-DisabledPlugin.png
2. Locate the plugin that you want to enable and click the title to expand the plugin details section.
3. Click the Enable button.
4. Once a plugin has been enabled, you may need to restart your application for your change to take effect. If so, you will see a message for the plugin, Enabled, requires restart.
   Once the plugin is fully disabled, you will see a Disable link for the plugin.

Disabling/Enabling all User Installed Plugins (Safe Mode)

Running JIRA in Safe Mode disables all user installed plugins at once. All plugins that were disabled when you entered Safe Mode will be re-enabled when you exit Safe Mode.

To enable Safe Mode:

1. Click the Manage Existing tab.
   The system displays a list the installed plugins.
2. Click the Enable Safe Mode link.
3. Click the Continue button in the confirmation window.
   All user installed plugins will be disabled and your application will now be running in safe mode.
4. Make changes to your installed plugins as desired.
   For example, you may want to enable/disable specific plugins or plugin modules.
5. Exit safe mode by clicking one of the links in the Safe Mode banner:
   • Click Exit Safe Mode and restore the previous configuration to restore your plugin configuration to its state before you entered Safe Mode.
   • Click Exit Safe Mode and keep the current configuration to keep all changes made to your plugin configuration during Safe Mode.

Uninstalling a JIRA Plugin

Note: If you only want to temporarily remove a plugin, you may wish to disable it instead of uninstalling it.

To uninstall a plugin:

1. Click the Manage Existing tab.
   The systems lists the plugins installed in your application.
2. Click the name of the plugin that you wish to uninstall.
   The system displays the plugin details.
3. Click the Uninstall button.
   The information summary displays an Uninstalling message and uninstalls the plugin from your application.

Uninstalling a 'Version 1' plugin manually

1. Shut down JIRA.
2. Remove your plugin jar (e.g. 'EXAMPLE_PLUGIN.jar') from the appropriate plugins directory:
   • If you are removing a 'Version 1' plugin, remove the jar from your JIRA installation directory under atlassian-jira/WEB-INF/lib/.
   • If you are removing a 'Version 2' (OSGi) plugin, remove the jar from your JIRA home directory under plugins/installed-plugins/.
3. Start up JIRA.
4. Go to 'Administration > Plugins'. Your plugin (e.g. 'EXAMPLE_PLUGIN') will no longer be listed.

Configuring a JIRA Plugin

A number of plugins have advanced configuration options, e.g. a plugin may contain multiple 'modules' that you can enable/disable. If you have one of these plugins installed on your application instance, you can view and update these configuration options via the Universal Plugin Manager (UPM).

To configure a plugin:

1. Click the Manage Existing tab.
2. Locate the plugin that you want to configure and click its title.
   The plugin details section expands.

3. Click the Configure button for that plugin.
   The advanced configuration options appear.

   If the plugin is disabled, you cannot configure it and so the Configure button does not appear. If there are no advanced configuration options for the plugin, there is no Configure button.

4. Update the configuration settings as desired and save your changes.
   Note: The plugin itself provides advanced configuration options. If you encounter any problems after you click the Configure button, the plugin is responsible for the issue, not the UPM.