Administration UI locations

Top navigation bar

The system.admin.top.navigation.bar location defines web sections that are shown in the navigation bar on Administration page and in cog wheel drop-down.

There are few predefined sections.

Section Name

key attribute

Applications

admin_applications_section

Projects

admin_project_menu

Issues

admin_issues_menu

Add-ons

admin_plugins_menu

User Management

admin_users_menu

System

admin_system_menu

Creating a new section in predefined tab

The admin_plugins_menu location defines web sections and items in the Add-ons tab of Jira administration area. We will use this location for example.

The following module definition steps show how to add one or more items in the Add-ons tab sidebar, each of which leads to a single page.

Web section won't appear on UI until you define at least one web-item in the section.

  1. Define one or more web-section modules for the Add-ons sidebar.

  2. 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 app's i18n.properties file) will be shown in bold text at the top of your section.

    For example:

    1
    2
    3
    4
    5
    <web-section key="my_new_section" ... location="admin_plugins_menu" ...>
        ...
        <label key="my_new_section_name"/> <!-- This element is optional -->
        ...
    </web-section>
  3. 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 section attribute whose value is admin_plugins_menu, followed immediately by a slash symbol /, and followed immediately by the key attribute's value specified in the relevant web section module.

    For example:

    1
    2
    3
    <web-item key="my_new_tabbed_item" ... section="admin_plugins_menu/my_new_section" ...>
    ...
    </web-item>
  4. Define a meta element in your HTML template file (such as a Velocity template file) with the attribute name="admin.active.section". * This meta tag should contain a content attribute whose value is the section attribute's value specified in the web-item module you defined.

    1
    2
    3
    4
    5
    For example:
    
    ``` xml
    <meta name="admin.active.section" content="admin_plugins_menu/my_new_section"/>
    ```
  5. Define another meta tag in the HTML template file with the attribute name="admin.active.tab".

    • This meta tag should contain a content attribute whose value is the key attribute's value specified in the web-item that links to that page.

    For example:

    1
    <meta name="admin.active.tab" content="my_new_tabbed_item"/>
  6. To render your page with Administration layout, define a meta with content="decorator".

    1
    <meta name="decorator" content="atl.admin"/>

Creating a new section in custom tab

If you want to create a new custom tab, you should create a web-section with the system.admin.top.navigation.bar location. Then follow steps in previous section and use your custom tab key instead of admin_plugins_menu.

Customizing the positions of your own items and sections

To customize 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.

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

Existing web sections of the administration location

Projects

Section Name

location

none

admin_project_menu/project_section

Issues

Section Name

location

ISSUE TYPES

admin_issues_menu/element_options_section/issue_types_section

WORKFLOWS

admin_issues_menu/element_options_section/workflows_section

SCREENS

admin_issues_menu/element_options_section/screens_section

FIELDS

admin_issues_menu/element_options_section/fields_section

PRIORITIES

admin_issues_menu/priorities_section

ISSUE FEATURES

admin_system_menu/top_system_section/issue_features

ISSUE ATTRIBUTES

admin_system_menu/top_system_section/issue_features

none

admin_issues_menu/misc_schemes_section

Add-ons

Section Name

location

Atlassian Marketplace

admin_plugins_menu/upm_section

User Management

Section Name

location

USER MANAGEMENT

admin_users_menu/users_groups_section

none

admin_users_menu/users_groups_configuration

USER DIRECTORIES

admin_users_menu/users_groups_configuration/embedded_crowd_section

System

Section Name

location

none

admin_system_menu/top_system_section

SYSTEM SUPPORT

admin_system_menu/top_system_section/troubleshooting_and_support

SECURITY

admin_system_menu/top_system_section/security_section

USER INTERFACE

admin_system_menu/top_system_section/user_interface

IMPORT AND EXPORT

admin_system_menu/top_system_section/import_export_section

MAIL

admin_system_menu/top_system_section/mail_section

ADMIN HELPER

admin_plugins_menu/admin-helper-admin-section

SHARED ITEMS

admin_users_menu/shared_section

ADVANCED

admin_system_menu/advanced_menu_section/advanced_section

Maintaining administration area location compatibility across Jira versions

To ensure that web-items defined for Jira's administration area will remain compatible for different Jira versions, specify the following in your app:

  1. Add a new IsPriorToJiraVersion Condition class to your app to identify if your Jira version is earlier than, for example, Jira 4.4. This class:

    1
    2
    *   Implements `com.atlassian.plugin.web.Condition`
    *   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 app's IsPriorToJiraVersion class to the web-item module defined for versions of Jira prior to 4.4. This condition:

    1
    2
    3
    4
    *   Passes the version number of 4.4 to your app's `IsPriorToJiraVersion` class via child `<parameter/>`
    elements.
    *   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.
  3. Add the IsPriorToJiraVersion Condition class to your app:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    @Scanned
    public class IsPriorToJiraVersion implements Condition {
    
        private int maxMajorVersion;
        private int maxMinorVersion;
        private int majorVersion;
        private int minorVersion;
    
        public IsPriorToJiraVersion(@ComponentImport 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);
        }
    }
  4. Add a condition that calls your app's IsPriorToJiraVersion class to your web-item module:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    ``` xml
    <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>
    ```

    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.