Seeking feedback for Jira Cloud's new sidebar nav architecture

Hi Cloud app developers!

We are in the process of building a new sidebar architecture that will help with Jira’s performance, scalability and overall usability. As part of this new architecture, we’re working on restructuring how some of the URLs from the sidebar links look and behave in Jira Cloud. We have also found some locations that are being utilized by a small number of Cloud apps and we would like to deprecate some of these, but before we do we want to better understand how these are used.

Our proposed plan

Based on our investigation, we are proposing the following changes and would like to get your feedback on this before moving forward:

  1. Changes to URLs

  2. Deprecation of Global Settings - System (a)

a) Global Settings - System (<3% of apps use this location):

  • Location = advanced_menu_section/advanced_section
  • Module = adminPages
  • Documentation: Admin Page

b) Global Settings - Apps

If your Cloud app currently uses the above Global Settings System location (a), can you give us more detail on why you use this and not the Global Settings Apps location (b)? For the end-user, we believe that #2 provides the same utility as #1.

Feel free to comment below on these proposed changes or tell us more about how you’re using these various locations. We want to better understand the use cases so we can make a much more informed approach to how we tackle this. Thanks so much for your time!

Kind regards,

Matt Tse,
Product Manager


Hi @mtse,
please note that changing the URL of these locations will break some apps that have links to these locations (for example to open them in a new window). So you’ll need to either maintain both URLs, or else provide us with a way to open this URLs in a new window using AP.navigator.go.


In addition to what @david2 said - this will also break our documentation and cause a large volume of support tickets for us.

For this type of change we would need to be able to contact every customer where our app is installed and let them know what exactly is changing so they can retrain/be prepared (browser bookmarks has to be up dated and so forth).

This could have serious impact on both our costs (support and development) as well as sales (as we probably will lose installs) depending on how this is rolled out, implemented and communicated.


I can echo what David and Daniel said.

Our apps use some of the links and changing them will:

  1. break functionality and require changes in the apps
  2. require changes in documentation

Releasing the change in batches (Atlassian usually does it) means that part of our app, even updated, would not work for some of the customers.
Therefore, handling old and new URLs for some time is a must-have when it comes to the implementation that you plan.



Just noticed that the redirect servlet isn’t mentioned. What’s the impact on it?

Similar to others, this change to URL’s (change 1) will break many links in our Apps and require changes to the source and documentation :frowning:

Does anyone have any concrete reasons why this is being done?

It’s difficult for vendors to be happy with these changes when there isn’t a reasonable justification.

Aren’t there more important things that the Cloud teams can work on which add value to customers, instead of these small changes that have the exclusive effect of upsetting ecosystem vendors?


In Backbone Issue Sync we’re using admin_plugins_menu for global app configuration things. Also, we’re linking & redirecting to this location from a few points in our app. Changing the URL would be fine for us as long as you’re announcing this change early enough, so we can prepare for it. And then please have the two URLs available together for some time (e.g. two weeks), so we can monitor any problems and react on them.

Although we’re not as affected as the others here, I do understand their concerns.

I’m a little confused by how you have split the global settings to two configurations:

a) Global Settings - System

  • Location = advanced_menu_section / advanced_section
  • Module = adminPages

b) Global Settings - Apps

  • Location = admin_plugins_menu
  • Module = webSections | webItems

We use a different combination of those two in our app ProForma, let’s call that (c):

c) Global Settings - ProForma

  • Location = admin_plugins_menu
  • Module = adminPages

So we are already using admin_plugins_menu which I think is your preferred location?

However if you’re interested in why we use adminPages rather than webItems then there are some clear benefits of adminPages:

  • Jira automatically does the security checks in adminPages so we know anyone viewing must be an administrator; in webItems we would have to apply permission checks manually.
  • adminPages puts our app in an iframe with consistent navigation so it feels more like a part of Jira, whereas webItems is a redirect to our cloud servers so we would lose the Jira navigation bar.
  • The adminPages URL is pretty static (ignoring your planned change for a moment), whereas webItems URLs would change regularly because we change our app URL every few months — as moving URLs that’s the easiest way to handle the half-day Atlassian Marketplace transition window when some Jira instances have our old version and some Jira instances have our new version. So bookmarks would break much more often when using a webItems redirect.

We’re in the same boat as @charlie

We have adminPages in a webSection of admin_plugins_menu, does that also count?

In our case (TM4J), changing the URLs would have a similar impact as described by others. Many users share URLs and bookmark them. Additionally, our documentation would be inconsistent and some automated tests would break as well.

I think redirecting from the old URLs to the new ones is the only reasonable way to go.

Now, sharing some feedback about the URLs, I think my only question is: why using “addon”? Aren’t we sticking to the new “apps” terminology (I honestly prefer “addons” to “apps”, but we need consistency)? In addition to that, since the URLs are being changed, would be nice to think of a way to make them look nicer. Adding the app key and item key to the URL makes them look quite long and unclear.


Hi everyone,

Thank you all for your thoughtful feedback and timely responses. Before I get into the specifics, I wanted to make sure that we share the “why we’re doing this” in a bit more detail.

So why the changes?

Jira Cloud’s sidebar navigation has gone through several iterations over the past couple of years, both from a UX and an architectural standpoint. We are now at the point where the architecture is slowing us down and limiting us from making performance improvements in the product. We know that performance of our Jira Cloud products is extremely important for our Cloud customers; it is often cited as one of the top pain points. Improving the sidebar is one of the many initiatives we’re doing to improve performance. Given that the sidebar is rendered everywhere in Jira, this new structure will benefit every single page in Jira.

Jira Cloud is moving towards a single-page application (SPA) and our current sidebar was designed in a way that is very hard to scale. As an example, our sidebar API returns way more data than is actually needed on the page just to account for all possible configurations, which prevents us from making optimizations like effective caching. A way to tackle these issues without introducing waterfall scenarios is by leveraging better URL patterns; by having unique URLs per location we can preemptively fetch and load only the data and the assets required. This approach helps us get closer to our target of having Jira pages rendered in <1s and interactive in ~2s in the next two years.

Another benefit for our Cloud customers is that these URLs will make it easier for Jira users to understand where they are in the product. We have seen from research and customer interviews that many of our users use the browser URL as a means to navigate and orient themselves in the product. We know how difficult it can be for users to find things in Jira and our hope is that moving to better-formatted URLs will improve usability over time.

Now to address some of the specifics:

  • Regarding the URL changes - we will not rush these changes as we understand that ecosystem developers will need time to update their respective documentation to mitigate any influx of support tickets. We want to assure you all that these changes are not going to happen tomorrow. We are however planning on tackling the URL changes within the next 2 months (see the detailed implementation plan below). When this does start, we will ensure that we still support the old/current URL pattern during this time and provide a solution to handle both URLs for 6 months. This date is flexible and we can accommodate a longer period if we’re still seeing lots of apps on using the old URLs.

  • Regarding the deprecation of advanced_menu_section/advanced_section - thank you for sharing your feedback with us about the permissions checks. As part of this, we can reassure you that these checks will be maintained in admin_plugins_menu. Some of you are asking why we would deprecate this section at all. Aside from reducing the calls we’re making to load the system admin menu, we believe that it is more intuitive and easier for users to find your respective Apps’ admin settings from admin_plugins_menu . Below is a snapshot of the engagement of the two different sections for one particular App that currently uses both locations. We see roughly ~5x more engagement in the last 90 days.

We understand there are some Apps out there that only use admin_menu_section/advanced_section, so our plan would be to programmatically carry forward these Apps’ admin pages into their corresponding section.

Of course, it’s also completely possible for you to define the section it belongs to. This can be done by using the existing webSections or webItems module.

Implementation plan (open for feedback)

  • Create a redirect that supports the old URLs, starting late July 2020.
  • Create the new URL structure, starting early August 2020, targeting to be rolled out by 100% by end of August 2020.
  • 6 month deprecation notice for admin_menu_section/advanced_section goes up in June 2020. Our proposed solution for handling this is implemented and rolled out to 100% by December 31, 2020.

Thanks again for your time! We really appreciate this level of engagement and care.


1 Like