In JIRA 4.4 we made some significant changes to the admin UI to improve navigation and general layout of the admin section in JIRA. All admin items have been re-grouped in a more logical manner and we’ve added quicknav to make it easy to navigate to an admin section from anywhere in JIRA.
JIRA 4.4 also introduces a new admin summary page that provides a good overview of all the admin sections that are available. Users used to searching through the old mess of 75 links using their browser’s CTRL + F search functionality will still be able to do so on this admin summary page.
JIRA 4.4 introduces admin quicknav which provides a much faster way of locating an admin page with additional keyword matching:
Getting your plugin ready for JIRA 4.4
If your plugin does not provide an admin section then this guide does not apply to you. You may want to read our full plugin upgrade notes available in our docs to make your plugin work correctly with JIRA 4.4 however.
If your plugin does provide an admin section then there are several steps you can take to make it ready for 4.4.
My favourite! If your plugin provides a web-item to insert itself in JIRA’s admin section it would have had to use the old ‘system.admin’ location. For example:
If you leave your plugin as is, this web-item will appear at the bottom of the new plugin’s dropdown (amongst other plugin links):
Update your plugin for JIRA 4.4
If you’d like your plugin’s admin links to appear in their own section there’s an easy way you can do this. You simply need to update the section attribute to point to one of the new predefined sections for plugins:
|Section Name||web-item’s section attribute||web-section’s location attribute|
For example to move your web-item into the ‘Builds’ section you’d have to modify your web-item to this:
This means the Bamboo Configuration link will show up under the ‘Builds’ section shown in the screenshot of the dropdown above.
What about backwards compatibility?
If you modify the web-item to point to one of the new admin web-sections then this link will no longer show up if your plugin is installed in JIRA versions prior to 4.4. In order to fix this problem you should keep the old web-item around but only display it if the plugin is installed in a version prior to JIRA 4.4. To make this easier we’ve introduced a new condition to check what version of JIRA you’re running.
The condition’s source is available in the plugin upgrade documentation. Once you’ve added this condition to your plugin this is what you should have in your atlassian-plugin.xml:
This will ensure that in older versions of JIRA you’ll still get the old system.admin link and versions newer than JIRA 4.4 will insert the link in a new admin section.
For more details see the full Plugin Developer Notes for JIRA 4.4!
How does keyword matching work?
Your plugin’s web-items will automatically show up in JIRA 4.4’s new admin quicknav search. If you want to add additional keyword matches to your plugin you’ll have to add the webfragments.keywords param to your web-item. For example:
This web-item renders the CVS modules admin section link. It specifies that keywords are available under the webfragments.keywords.admin.plugins.cvs_modules key. The actual keywords themselves have to be defined in your plugin’s i18n properties file under this key as a comma separated list:
Done! Now your plugin’s admin section can also be found via keywords in quicknav. The keywords can be translated so that they still make sense in various languages!