Administration Area Locations

Available:

JIRA 4.4 and later — the admin_plugins_menu location is available.
JIRA 3.7 and later — the system.admin location is available.

Administration Area Location

(info) JIRA 4.4 and later versions.

The admin_plugins_menu location defines web sections and items in the 'Plugins' drop-down menu, available from the top navigation bar of JIRA's administration area.

You can add new web items to pre-defined web sections in the 'Plugins' drop-down menu, or add new sections to this drop-down menu along with new items. This will create a menu item that leads to a single page.

You can also create a menu item that leads to a set of tabbed pages (as indicated in the following screenshot). To do this, the menu item is defined as a new web section within a web section of the 'Plugins' drop-down menu (i.e. a 'nested' web section). The procedure for creating this is explained below.

(tick) If your plugin defines a web item module that uses the system.admin location available in JIRA 4.3.x and earlier (see 'Former Administration Location' below) but you have not yet updated it to use the system.admin.top.navigation.bar location available in JIRA 4.4 and later, then your web item will appear in a separate section towards the end of the 'Plugins' drop-down menu in JIRA 4.4.

Adding 'Plugins' Drop-down Menu Items that Lead to Single Pages

The following module definition steps show how to add one or more items in the 'Plugins' drop-down menu, each of which lead to a single page.

To add one or more items in the 'Plugins' drop-down menu each of which lead to a single page:

  1. (Optional) Define one or more <web-section> modules for the 'Plugins' drop-down menu.
    (info) This step is optional because JIRA includes several pre-defined 'Plugin' drop-down menu sections (see below). In default JIRA installations, the 'Source Control' and 'Builds' sections are visible.
    • Each of these <web-section>modules must include:
      • A key attribute with a unique value.
      • A location attribute with the value "admin_plugins_menu".
      • (Optional) If you wish to create a 'section label' that appears in bold text at the top of the section, define a <label> element with a key attribute whose value defines a unique property. The string value of this unique property (defined in your plugin's i18n.properties file) will be shown in bold text at the top of your section.
    • For example:

      <web-section key="my_new_section" ... location="admin_plugins_menu" ...>
          ...
          <label key="my_new_section_name"/> <!-- This element is optional -->
          ...
      </web-section>
      
  2. Define a <web-item> module for each item that appears in one of the web sections in the 'Plugins' drop-down menu.
    • Each of these web item modules must include a sectionattribute whose value is:
      • The value admin_plugins_menu, followed immediately by
      • A slash symbol /, followed immediately by
      • The key attribute's value specified in the relevant web section module (see 1 above). Alternatively, use one of JIRA's pre-defined sections (see below).
    • For example:

      <web-item ... section="admin_plugins_menu/my_new_section" ...>
      ...
      </web-item>
      

Adding 'Plugins' Drop-down Menu Items that Lead to Tabbed Pages

The following module definition steps show how to add one or more items in the 'Plugins' drop-down menu, each of which lead to a set of tabbed pages.

To add one or more items in the 'Plugins' drop-down menu each of which lead to a set of tabbed pages:

  1. (Optional) Define one or more <web-section> modules for the 'Plugins' drop-down menu.
    (info) This step is optional because JIRA includes several pre-defined 'Plugin' drop-down menu sections (see below). In default JIRA installations, the 'Source Control' and 'Builds' sections are visible.
    • Each of these <web-section>modules must include:
      • A key attribute with a unique value.
      • A location attribute with the value "admin_plugins_menu".
      • (Optional) If you wish to create a 'section label' that appears in bold text at the top of the section, define a <label> element with a key attribute whose value defines a unique property. The string value of this unique property (defined in your plugin's i18n.properties file) will be shown in bold text at the top of your section.
    • For example:

      <web-section key="my_new_section" ... location="admin_plugins_menu" ...>
          ...
          <label key="my_new_section_name"/> <!-- This element is optional -->
          ...
      </web-section>
      

  2. Define a <web-section> module for each item that appears in one of the web sections in the 'Plugins' drop-down menu.
    • Each of these <web-section>modules must include:
      • A key attribute with a unique value.
      • A location attribute whose value is that of the key attribute's value specified in the relevant web section module (see 1 above). Alternatively, use the key attribute value one of JIRA's pre-defined sections (see below).
    • For example:

      <web-section key="my_new_menu_item" ... location="my_new_section" ...>
          ...
      </web-section>
      

  3. Define a <web-item> module for each tab associated with the menu item (defined as a web section in the previous step) in the 'Plugins' drop-down menu.
    • Each of these <web-item>modules must include:
      • A key attribute with a unique value.
      • A sectionattribute whose value is:
        • The location attribute's value specified in the relevant web section module (see 2 above), followed immediately by
        • A slash symbol /, followed immediately by
        • The key attributes's value specified in the relevant web section module (see 2 above).
    • For example:

      <web-item key="my_new_tabbed_item" ... section="my_new_section/my_new_menu_item" ...>
          ...
      </web-item>
      

To ensure that a particular tabbed page is displayed after a JIRA administrator selects the page's associated menu item:

  1. Define a <meta> element in your HTML template file (such as a Velocity template file) with the attribute name="admin.active.section".
    (info) This element links your HTML template to the menu item you defined in step 3 of the procedure above.
    • This <meta> tag should also contain a content attribute whose value is the section attribute's value specified in the <web-item> module you defined in step 3 of the procedure above.
    • For example:

      <meta name="admin.active.section" content="my_new_section/my_new_menu_item"/>
      
  2. Define another <meta> tag in the HTML template file with the attribute name="admin.active.tab".
    (info) This element specifies the tabbed page which is displayed by default after a JIRA administrator selects the page's associated menu item that you created in step 3 of the procedure above.
    • This <meta> tag should also contain a content attribute whose value is the key attribute's value specified in the <web-item> module you created in step 3 of the procedure above.
    • For example:

      <meta name="admin.active.tab" content="my_new_tabbed_item"/>
      

Pre-defined Sections of the 'Plugins' Drop-down Menu

For each of the pre-defined sections below, the section name appears in bold at the top of the section in the 'Plugins' drop-down menu.

Section Name

key attribute

Source Control

source_control

Builds

builds_section

Agile

agile_section

Testing

testing_section

Requirements

requirements_section

Timetracking

timetracking_section

Integrations

integrations_section

Workflow

workflow_section

Drawing

drawing_section

(tick) If you would like an item to appear in the very top section of the 'Plugins' drop-down menu (which only contains the 'Plugins' and 'Application Links' items in default JIRA installations), then your <web-item>'s section attribute (and if required, the corresponding <web-section>'s location attribute) which defines this item must reference the key attribute value 'top_plugins_section'.

Customising the Positions of Your Own Items and Sections

To customise the position of your own web items or sections in this location, add a weight attribute to your <web-item> or <web-section> and adjust its value with respect to JIRA's existing web items or sections. Lower weight values result in these items/sections appearing higher up the 'Plugins' drop-down menu.

Source File

To find the values of JIRA's existing web items and sections for the system.admin location, view the following file in JIRA's source archive:
<source-installation-directory>/jira-project/jira-components/jira-core/src/main/resources/webfragment/system-admin-sections.xml

Former Administration Location

(info) Versions of JIRA prior to 4.4.

The system.admin location defines web sections and items in the left-hand navigation column of JIRA's administration area.

You can add new web items to existing web sections in the left-hand navigation column of JIRA's administration area (see below), or add new sections to this column along with new items.

Adding New Items to Existing Web Sections

To add your own web item to an existing web section of JIRA's administration location, your web item must include a section attribute with the value "system.admin/section_name", where section_name is the section of the left-hand navigation column to which the web item will be added.

For example, to add a web item module that defines a new item in the Global Settings section, your web item module would contain:

<web-item ... section="system.admin/globalsettings" ...>
    ...
</web-item>

Existing Web Sections of the Administration Location

project

schemes

exportimport

usersgroups

issuefields

options

globalsettings

issuesettings

system

Adding Custom Sections and Items

To add your own section to the left-hand navigation column, define a web section that includes a location attribute with the value "system.admin".

For example, your web section module would contain:

<web-section key="my-custom-admin-section" ... location="system.admin" ...>
    ...
</web-section>

Adding new web items to your own sections is similar to the method above for adding new web items to existing web sections. However, specify the value of your web section's key attribute in the value of your web item's section attribute (preceded by the location). Hence, following on from the previous example, your web item would contain:

<web-item... section="system.admin/my-custom-admin-section" ...>
    ...
</web-item>

Customising the Positions of Your Own Items and Sections

To customise the position of your own web items or sections in this location, add a weight attribute to your <web-item> or <web-section> and adjust its value with respect to JIRA's existing web items or sections. Lower weight values result in these items/sections appearing higher up in the left-hand navigation column.

Source File

To find the values of JIRA's existing web items and sections for the system.admin location, view the following file in JIRA's source archive:
<source-installation-directory>/jira-project/jira-components/jira-core/src/main/resources/webfragment/system-admin-sections.xml

Maintaining Administration Area Location Compatibility Across JIRA Versions

To ensure that web items defined for JIRA's administration area will remain compatible for JIRA versions spanning 4.3.4 and earlier to 4.4 and later, the following must be specified in your plugin:

  1. Add a new IsPriorToJiraVersion 'condition' class to your plugin to identify if your JIRA version is earlier than JIRA 4.4 (see below for details). This class:
    • Implements com.atlassian.plugin.web.Condition of the Atlassian Plugin Development Platform and
    • Returns a true value if your JIRA version is found to be earlier than JIRA 4.4.
  2. Add a <condition/> element that calls your plugin's IsPriorToJiraVersion class to the <web-item> module defined for versions of JIRA prior to 4.4 (see below for details). This condition:
    • Passes the version number of 4.4 to your plugin's IsPriorToJiraVersion class via child <parameter/> elements and
    • If a false value is returned by this class (because your version of JIRA is later than 4.4), the web item will be disabled and hence, will not be visible in any drop-down menu of the JIRA Administration area.

Add the IsPriorToJiraVersion 'Condition' Class to Your Plugin

public class IsPriorToJiraVersion implements Condition {
 
    private int maxMajorVersion;
    private int maxMinorVersion;
    private int majorVersion;
    private int minorVersion;
 
    public IsPriorToJiraVersion(ApplicationProperties applicationProperties) {
        String versionString = applicationProperties.getVersion();
        String versionRegex = "^(\\d+)\\.(\\d+)";
        Pattern versionPattern = Pattern.compile(versionRegex);
        Matcher versionMatcher = versionPattern.matcher(versionString);
        versionMatcher.find();
        majorVersion = Integer.decode(versionMatcher.group(1));
        minorVersion = Integer.decode(versionMatcher.group(2));
    }
 
    public void init(final Map<String, String> paramMap) throws PluginParseException {
        maxMajorVersion = Integer.decode(paramMap.get("majorVersion"));
        maxMinorVersion = Integer.decode(paramMap.get("minorVersion"));
    }
 
    public boolean shouldDisplay(final Map<String, Object> context) {
        return (majorVersion < maxMajorVersion) || (majorVersion == maxMajorVersion) && (minorVersion < maxMinorVersion);
    }
}

Add a Condition that Calls Your Plugin's IsPriorToJiraVersion Class to Your Web Item Module

<web-item ... section="system.admin/globalsettings" ... >
    ...
    <condition class="package.qualified.name.to.your.plugins.class.IsPriorToJiraVersion">
        <param name="majorVersion">4</param>
        <param name="minorVersion">4</param>
    </condition>
    ...
</web-item>

(info) The section attribute of this web item module (for versions of JIRA prior to 4.4) defines which section of the Administration area the web item will appear in. For more information, see 'Former Administration Location' (above).

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport