nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

Jira Instance Cleanup Guide

Kim Mooney

Great news! We've posted an updated version of the guide. Use this link to teleport over to it! 🚀

👋 Hey there! I’m Kim with Atlassian Customer Success. We’re here to help you succeed with Atlassian products like Jira. Our subject for today – instance hygiene. 🛀

If you and your team have been using Jira for over a year, we recommend running an instance clean up project. A cleanup is also great for instances recently migrated to Jira Cloud that weren’t cleaned up prior to the migration.

Running a Jira instance cleanup improves productivity, reduces the time to find what you’re looking for and enhances the user experience.

Ready to get started? Check out this guide to cleaning up your Jira instance and eliminate redundancies⤵

Prepare for the cleanup

Before you start the actual cleanup, there are a few things you should do to make sure everything runs smoothly.

✅ Decide who should be involved

Limit the number of admins involved in the project. We recommend more than 2 but fewer than 5. This isn’t a scenario where “the more the merrier” applies. 😉

✅ Audit your instance

Change starts with awareness. Before you can effectively clean up your instance, you’ll want to take inventory of what it looks like today. Below are areas we recommend you review and how to find them.

Audit item	Audit resource
Apps Are there unused apps, or apps that have been made redundant by native functionality? Check which projects use the app and speak to the team using it to weight your options.	How to view connected apps
Users Do you have any inactive users? Have any of the inactive users left the company or changed roles and no longer need access?	How to view inactive users* *Only available for verified domains
Projects Are there any projects that haven't been updated for at least 2 years?	How to view all projects Select Projects from the global navigation → Manage projects
User groups Are all your user groups necessary? Any duplicates?	How to view user groups
Issue types Are there unused issue types?	How to view issue types Select Settings ⚙️ from the global navigation → Issues → Issue types How to find unused Issue Types Use a REST API in Python
Workflows Are there any duplicate workflows or ones that are unused?	How to view all workflows Select Settings ⚙️ from the global navigation → Issues → Workflows to see a list of active and inactive workflows.
Automation rules Are there any unused rules you could delete or turn off?	How to view automation rules

✅ Understand processes and baselines

Once you know what areas of your instance need cleaning, create rules so your team has a common understanding of what to keep and what’s redundant.

Review these questions to decide on your rules:

What’s your organization’s retention period? → Establishing that will help you decide on the policy to archive issues and projects.
What constitutes a valid user group? → Establishing that will help you decide which user groups to keep.
What constitutes an inactive user? → Establishing this will help you decide when to delete a user. For example, a user may be inactive because they left the company or they aren’t using Jira at the moment but still need access for the future.
What's your criteria for granting permissions? → Establishing that will help you decide which groups to keep and help clean up permission schemes.
What's your baseline for keeping / deleting a custom field? → This will help you get rid of unused custom fields.
What constitutes a project? → This will help you clean up projects and project schemes.
Think of other criteria that are applicable for your instance. → This will help capture items that are particular to your instance.

💡 Pro Tip: Document your rules in a Confluence page for future reference.

✅ Prioritize what to clean up first

If you've never run any cleanup activities, the initial ones are likely to be a heavier lift. Start by identifying some quick wins for key problem areas and then reduce the noise over time.

Potential quick wins

Archive projects that haven't been updated for at least 2 years
Archive projects assigned to deactivated users
Delete duplicate custom fields that aren’t being used

✅ Keep your team in the loop

Administrators, team leads, and project admins can help you determine what needs cleaning and identify the entities that are redundant. Notify them about the planned cleanup and reach out to them to help. You’ll also want their input when developing a change management plan to make sure you’re effectively communicating changes to the rest of your organization.

Start your cleanup

💡 Pro Tip: We recommend backing up your instance and running any changes in a test environment first before applying them in production.

✅ Address your quick wins one at a time

Make sure you take notes as you go. This project is not only about cleaning the instance now, but maintaining order in the future. Try to think about what rules or changes to your process will help.

Audit item	How to archive/delete
Apps	How to delete connected apps
Users	How to delete inactive users
User groups	How to delete user groups
Projects	How to archive a project* *Only for Premium and Enterprise plans
Custom fields	How to delete custom fields* *Only for Company Managed Projects
Issue types	How to delete an issue type
Workflows	How to delete a workflow
Automation rules	How to disable an automation rule

✅ Set up automations or create process improvements

This is when you update procedures and processes. At this point, you might know what you can automate so cleanup activities are less time-consuming in the future. Here are a few ideas:

Process improvements	Automations
Create a request process for adding apps to review whether the outcome can be achieved using native features, such as automation Share the Confluence page you created to document your audit rules with your team so they’re aware	Auto-archive projects after 2 years of inactivity Auto-archive issues at the end of the year

💪 Stick with it!

Frequent cleanups tend to be less time-consuming than those performed at long intervals. Keep up the momentum and schedule time for regular cleanups.

Recommendations for cleanup scheduling

Quarterly	Annually
Custom Fields (pay attention to contexts) Identify projects for archive or deletion Remove inactive users Build into offboarding process Archive old issues Prepare for annual cleanup Audit third-party apps	Archive or delete projects Audit third-party apps

Done a cleanup before? Already have a process for keeping your instance clean?
Let us know what advice you have for others doing this for the first time.👇

Comments

Yatish Madhav

Thanks for this @Kim Mooney - I have not read this article yet ... But I will be going through this real soon! I have been doing this since I started using Jira as it is so powerful and at the same time can get so complex for administrators. Esp when the kitchen has tons of chefs ... which is also what we are planning to clean up. Thank you

Gary Spross_o1iwv6

I've been going through a constant clean up effort for a while now. This is an excellent reference guide to assist in that process. Thanks for this @Kim Mooney!

Kristján Geir Mathiesen

Instance hygiene - love it! Good post. Thanks @Kim Mooney

Joanna Thurmann

Fabulous post, @Kim Mooney. And even more great news is that Atlassian University has a FREE Jira Governance & Housekeeping skill-builder course that includes these wonderful tips and much more. Check it out!

Rebecca Hylek

Great article! We recently migrated to the cloud and have been working on cleaning up our instance of Jira. This an awesome reference and definitely helps keep the right things in mind!

@Joanna Thurmann thanks for the link to the course! That's one I'll definitely be taking soon!

Cheri Hansen

@Kim Mooney This is awesome!! Thank you so much for posting this and getting me on the right path as we look to clean up our jira instance.

Natasha Richardson

This is a great list and has come at a perfect time for us as we are starting our governance project for Jira. Thanks! @Kim Mooney

A A Ron Geister _Trundl_

@Kim Mooney Great article. This is something I do through the year and have an Epic that deals with some of these same points. I think I might follow your standard as my is a little different but I surely think this is awesome!

Kudos

Edgar Spence

Some other areas I have found useful to clean up:

Unused filters

Combine or reduce screens, field configurations, etc. along with associated schemes (Anything from a former project, or combine commonly used items to make the assigning and searching of these options easier)

Paula Hidalgo

@Kim Mooney - Great article! I have been monitoring the design elements on our cloud instance twice a month since July 2020. I initially tracked 18 different config items and now track 27 different stats. The most challenging to keep under control are filters, board admins, dashboard, and project leads with inactive users. Scripting using API calls is the only way to identify the elements tied to an inactive user, Once a user goes inactive, the View all dashboards (and System Manage dashboards) and the View all filters (and System Manage filters) no longer let you search by the inactive user name.

Eleanor Kerman_6ac91w

Appreciate this article

Great guide

would like additional ways or tools to monitor private and shared dashboards, filters. i also wouldlike to be able to diable the creation of team maanged projects by "Admins"

Sandra Robin

Thank you for sharing! Much appreciated.

Yatish Madhav

Hey @Kim Mooney ...

Some typos

Redundant what in the intro...

3rd row in the 1st table has wrong resource

Some feedback

This is a great start for a cleanup ... I think the trickiest is the schemes as @Edgar Spence eluded. Ie. If 2 schemes are identical, only way to see that is compare them manually?

The instance I work on and manage had a number of admins previously and chrrently and so it's become a scenario where the primary corporate admins may not know the background of those setups like numerous projects and schemes they have set up. So we seem to be stuck between a rock and a hard place. Any ideas on how to quicker understand the full project, it's schemes, and create almost a Venn diagram of sorts? And move towards lowering admistrators ...

Another aspect is the numerous Statuses and Custom Fields we. I wonder if removing a custom field as easy as it is is fine. Or if removing it we need to consider and review more than the context like filters and automation too? Anything else?

Also I love the point 3 of creating business rules of administering Jira. We are trying to clearly figure that one out too

Lastly any tips for actioning those 3 quick wins? The last i did was find all projects that had 0 to 3 issues in total and cleaned those up ... allowing me to clean up lots of linked entities like schemes, fields and Statuses used only in those.

Thanks once again Kim

David Meredith_lho1hy

https://jira.atlassian.com/browse/JRACLOUD-67882

^^ Alternatively, you could engineer Jira products so that it doesn't leave unneccessary schemes and associated data everywhere?

If you didn't have to create new workflows to delete a transition, you wouldn't have so many inactive workflows.

For projects, if someone creates a new project, automatically you get a number of individual schemes and items created, especially if you create a project from a template. If you decide to use a shared scheme in future you need to manually review and delete unused schemes.

You can create a project using another project to share settings with. But that then shares EVERY scheme and doesn't allow you to pick and choose the relevant parts to share.

A workaround could be to create each new project to share settings with a DEFAULT project that has generic shared schemes. Then create individual schemes and items for the new project only when they are required.

Jay McCarogher_3vvyhj

I kinda feel like you read my mind this morning!
This process is going to be super useful, thank you!!

Roman Sirochinsky

I was looking to clean up my Atlassian SPACE!!!

I'm still not sure how much space is available fo my organization in JIRA or Confluence or how to manage it.

Derek Adkins_xfckrq

I was hoping for a less manual way to cleanup Jira Cloud. I'd expect an option or report that runs through the whole Jira instance and provides a report of when things were last used. (Workflows etc.)

At the very least, when a project is archived or deleted, it's boards, workflows, filters etc that are ONLY used in that project, should also be deleted as well.

I find it very frustrating that when a board is deleted, its filter stays behind.

Same with a project leaving behind its workflows, screen, issue types etc.

Kim Mooney

Loving all the feedback! Keep it coming.

@A A Ron Geister _Trundl_ - I’d still be interested to hear what you have in your cleanup Epic currently.

@Edgar Spence - Great idea! I’ll add that to my list to include in future versions.

@Paula Hidalgo - That’s a great call out too regarding inactive users. Thank you!

@Yatish Madhav - Thanks for the heads up. Made the fix you pointed out. Regarding your other feedback and questions, I’ll check in with my team and get back to you.

@Derek Adkins - Thanks for your feedback! I totally understand where you're coming from, which is why I created this guide to help with how it works now. As @David Meredith mentioned, we do have an open feature request which aims to improve this process ➡️ https://jira.atlassian.com/browse/JRACLOUD-67882. You can click on Start watching this issue to receive updates about that or leave a comment there to provide more feedback on the feature.

Yatish Madhav

Super! Thansk @Kim Mooney - appreciate this starter guide and the progress made additionally on Jira

Mauricio Heberle_x42e0d

Are there any queries where we can search for all these unused Jira object in our database? This way we can use SQL to search and clean up based on dates

A A Ron Geister _Trundl_

@Kim Mooney Here is a snapshot of my Epic for Atlassian Audit

Haddon Fisher

@Kim MooneyMany people have mentioned this above and it's been a source of friction for as long as I've used Jira, but at the risk of stating the obvious: Jira really doesn't do a lot to help with keeping itself not messy.

Already mentioned specifically, but the cruft created when you spin up a new project is a problem. I get why this choice was made, but this needs an auto-delete or something.
Without add-ons (I am thinking Project Configurator or Config Manager) it's mostly impossible to see usage of anything. The analysis needs to be done by hand, which is incredibly time-consuming in and of itself, but also only leads to more work because....
There are no tools to help you clean any of this besides "delete". Being able to merge custom fields of the same type ALONE would be a huge win for people who inherit instances that have 6 "Due Date" fields, but there's so much more Jira could be doing to help with this.
The UI really gets in the way of doing any of this in a non-painful way. There's almost no bulk anything, some things require ludicrous amounts of manual clicks (like re-ordering statuses), and just in general is a force-reductor instead of multiplier.

I'd also add that a lot of things being rolled out do not seem to have maintenance or administrators' sanity in mind. A little bit of forethought up-front would go a long way to helping out with this.

A A Ron Geister _Trundl_

@Haddon Fisher

This statement is so true

"There are no tools to help you clean any of this besides "delete". Being able to merge custom fields of the same type ALONE would be a huge win for people who inherit instances that have 6 "Due Date" fields, but there's so much more Jira could be doing to help with this."

I inherit instance with 7 start dates and it has been a mess to clean up. In fact so many server and DC migration have been done and so much garbage as been take to the cloud to clean up later. It would be nice have a merge field or some tools for clean up other than using the api.

Haddon Fisher

@Aaron Geister inherited instances are the worst. 😂

David Meredith_lho1hy

@Kim Mooney

I appreciate that this is a handy guide to perform a neccessary manual cleanup in the absence of anything automated.

However, please can you apply any pressure you can internally to get things like https://jira.atlassian.com/browse/JRACLOUD-67882 assigned to someone and prioritized?

Manually tidying up is a sticking plaster over a larger gap in functionality to either:

Automatically clean up after products
Engineer products in a way where it doesn't create so many junk schemes / data.

Kate Wall

@Kim Mooney

Loving this topic and the information provided; very helpful. One of the things my team struggled with is the ability to extract information from the back-end of Jira in order to complete tidy-up Analysis and Work.

If you don't mind me adding my wish list; the ability to pull the following data (as opposed to screen-scrapping) would be awesome:
- Project Lists
- Board lists
- Dashboards
- Scheme lists etc

For example, we found that we had over a thousand dashboards (which was a nightmare to copy/board over 40 pages of lists)....

We were able to request this information be pulled directly from the backend by Atlassian support, but it would be nice to be able to do this ourselves. My dream information for these would also include information like 'last updated' or 'last visited' but I know that's a big ask.

Paula Hidalgo

Pulling information means learning a scripting language (such as python), using the REST APIs, and understanding JSON. For Jira Platform, the API documentation is here The Jira Cloud platform REST API (atlassian.com). This will get you all the design element information except for Board list. For board list, you need to omit the {boardId} in this API The Jira Software Cloud REST API - Get Board

For your script, you need to get an API token: Manage API tokens for your Atlassian account | Atlassian Support

Use Excel to format the JSON file into a format you can use (here is a video that can help How to Import json File into Excel - YouTube)

Darrel Jackson

A few comments:

Calrification: For project audit, you need to go to Settings > Projects > Manage Projects in order to view when issues were last updated. Going Projects > View all projects doesn' tgive you the last updated date.
Is there a way to determine if a user group is in use (i.e. is assigned to project permissions, filter permissions, board permisssions etc). I don't think there is.

Kim Mooney

@Yatish Madhav - As promised, here’s what I found out for you:

Unfortunately, the only way to see what’s different in two schemes at the moment is to manually compare them.
Yes, before you remove a custom field, you should check to see where it’s been used and confirm it’s no longer needed. However, if you do remove a custom field that’s in use, it can be restored, here’s a page on this: https://support.atlassian.com/jira-cloud-administration/docs/edit-or-delete-a-custom-field/

Hope that helps!

Kim Mooney

@David Meredith - I certainly appreciate the analogy and I’m definitely passing the feedback I’m receiving on this post along.

@Kate - Glad it's helpful! To make sure your wish list gets seen, I’d recommend making a feature request which you can do here.

@Darrel Jackson - Thanks for the clarification! I’ll make that change to the guide. As for your question, I’ll double check with my team and get back to you.

Welcome!

It looks like you're new here. Sign in or register to get started.

Quick Links

Find more posts tagged with

jira-software

customer-success