Clean up your Jira instance

Still need help?

The Atlassian Community is here for you.

Ask the community

The purpose of this guide is to outline the ways you can declutter and reduce the overall size of your Jira application. 

There is no single approach, or magic button, that will work in all situations so on this page, we'll show a range of techniques you can use to clean up your site. This will no doubt be a team effort, and you'll need to enlist the help of people in your organisation. See Prepare for the cleanup for more about determining business rules and getting the right people involved.  

Your process here will be iterative and will look the following:


BASIC CLEANUP  → 
(quarterly)                                

ADVANCED CLEANUP  →  
(annual)                                        

AUTOMATION 
and
OPTIMIZATION 
(after completing each activity)

Looks heavy? If you've never run any cleanup activities, the initial ones are likely to be so. This guide is to give you direction as to where to look for things worth reviewing and help select tools and ways with which you can identify the entities that are redundant for your instance.

Looking for some inspiration to start?

Watch this video to get more insights into a real-life cleanup project.

tip/resting Created with Sketch.
  • Have you backed up your data? It's a good idea to do that before you start. See how to back up data.
  • Make changes in your test environment first before applying them in production.

Basic mandatory cleanup process

Recommended frequency: once per quarter

Skills required: basic Jira admin skills

Step 1: Archive old projects

If your Jira is several years old, you’re bound to have a couple dozen projects that are complete, retired or never-to-be finished. There might be projects that have been created but have no issues at all. These cause clutter for users who might see irrelevant projects, cause their JQL queries to return results they might not expect, and make your reindexing happen much slower than it needs to.

How do I identify what to clean up?

In your Admin panel, go to Projects, and filter for those whose last issue update happened, for example, 2 years ago. If issues in those projects haven't been touched for so long, they are likely to remain inactive in the future. 

Need app assistance?

Optimizer for Jira  help you find out projects that have a small number of issues that might be candidates for archiving/deletion.

How do I go about the cleanup?

There are a few methods to deal with old projects:


  • You can delete projects if your company policy allows this and the data from those projects aren't used in any kind of reporting. This will help performance. 
  • You can archive old projects. Jira 7.10 introduced an easy way of project archiving that does not require any prior project preparation and allows for an easy restore. This method will help reduct instance clutter but will have a smaller performance gain than deleting. 

To learn more about project archiving, see Archiving a project

How do I automate?

Discuss optimal retention for projects. Then, you can either create a script that automatically archives or deletes projects, and/or you can talk to project owners or project admins to run regular review of projects and nominate the ones to be archives/deleted. Our archiving REST API can also help you automate. See archiving API

Explore the possibilities of the ScriptRunner app as it can also help you automate your archiving tasks.

Step 2: Archive old issues

If you have issues that haven’t been updated for the last 2 years, it might be time to clean them up. Again, you can delete them, but if your company policy requires that you keep them longer, we have a good solution. 

How do I identify what to clean up?

Query for issues that haven't been updated for a while. We normally say two years is the timeframe after which issues should be archived, but feel free to make your own decision here. 

How do I go about the cleanup?

In Jira 8.1.0 and later you can easily archive individual or multiple issues, and restore them when needed. Naturally, issues get archived when you archive a project they belong to, but in this case, you can archive old issues that still belong to an active project. No reindexing is required when you archive or restore. To learn more about issue archiving, see Archiving an issue.

tip/resting Created with Sketch. Archiving old issues will also help slow loading agile boards that have too many issues load faster.

How do I automate?

Discuss optimal retention for issues. Then, you can either create a script that automatically archives or deletes issues, and/or you can talk to project owners or project admins to run regular review of issues and nominate the ones to be archives/deleted. Our archiving REST API can also help you automate. See archiving API

Step 3: Clean up custom fields

Did you know that having too many or poorly configured custom fields is one of the largest performance killers for most Jira instances? Some custom fields can take up a lot of the indexing time causing indexing time to peak. It’s a good idea to audit your custom fields and see what actions you can take. 

How do I identify what to clean up?

NEW Check the usage of custom fields

Check the usage data for your custom fields—how many issues are actually using your fields and when was the last value update. This data is displayed in new columns for every custom field, and should help you find custom fields that aren't used too often or haven't been updated for a long time. You can sort by these columns and use filters to quickly find good candidates for deletion. It might happen that some custom fields were created for testing purposes and now aren't used at all, so you'll be able to bulk delete them right away. For more info, see Analyzing the usage of custom fields.

Delete duplicate custom field and re-use custom fields across projects

Search through the custom fields looking for duplicates. For example, you might have "Start Date", "Started date",or "Date of Start" in your projects. Duplicates can definitely be deleted here, and you can re-use one across projects.

Review the custom field configuration and context

Some custom fields take much more time to index than others. If it’s not a system field, you might try to improve its configuration to make it index faster. To help you monitor custom fields' indexing times, Jira displays the 20 most time-consuming custom fields (10 in the Total and 10 in the Snapshot time period). Review this data to see if any of the custom fields your team has created takes long to index . For more information, see Jira cluster monitoring DATA CENTER

Look into context

Context is a part of custom field configuration. If a custom field has Global context assigned, it’s used in all projects in Jira. This has a significant impact on the index. It might happen that a certain custom field is used only by several projects and global context is not necessary. Instead, you can easily select projects and issue types to which this custom fields applies.

Run the custom fields optimizer available in Jira to see how many projects actually use the custom fields with the global context and how many of those can be optimized. See Optimizing custom fields.

Need app assistance?

The easiest way to find unused custom fields is to use one of the apps below:


However, if you are fine using SQL queries, you can use those provided below to look for the unused custom fields and then manually delete them from the custom field list.

SQL to find unused fields...

Replace the 12340 in the examples below with your field ID.


Dashboard gadgets


SELECT *
FROM
    gadgetuserpreference
INNER JOIN portletconfiguration ON portletconfiguration.id = gadgetuserpreference.portletconfiguration
INNER JOIN portalpage ON portalpage.id = portletconfiguration.portalpage
WHERE
    userprefvalue LIKE '%12340'


Filters


select * from searchrequest s where s.reqcontent like '%MyCFName%' or s.reqcontent like '%cf[12340]%'


Screens


SELECT cf.id, fsli.fieldidentifier, cf.cfname, fs.name, fst.name FROM fieldscreenlayoutitem fsli
INNER JOIN fieldscreentab fst 
ON fsli.fieldscreentab = fst.id
INNER JOIN fieldscreen fs
ON fst.fieldscreen = fs.id
INNER JOIN customfield cf
ON fsli.fieldidentifier = 'customfield_' || cf.id::text
WHERE fsli.fieldidentifier LIKE '%customfield_12340%'


Workflows

select * from jiraworkflows wf where wf.descriptor like '%customfield_12340%';

How do I go about the cleanup?

Delete duplicate custom fields and re-use fields where possible. Consider getting rid of the fields that take longest to reindex if they aren't crucial for your organization and provided these are not system fields. Adjust context. 

tip/resting Created with Sketch. Usually it’s not enough to find an empty custom field and delete it because even though the field may be empty if you have a workflow that sets the value, then you can break the workflow when it tries to set the custom field you just deleted.


How do I automate?

Start by running regular reviews of the custom fields and monitoring who's got permissions to create them. You might also use the Jira audit log to monitor when a new field is being created to make sure the field will serve a purpose. 

In Jira 8.14 we made it possible to set the context when users create a new custom field. Make sure they select the recommended option of applying the custom field only to selected projects. 

Step 4: Remove inactive users

Whenever someone leaves your organization, it’s good practice to disable their user account. This keeps your instance safe, keeps people from accidentally assigning tickets to an account where nobody is watching, and of course returns an all-important user license to you.

How do I identify what to clean up?

To get a list of users showing their last login timestamp from the database in order to audit application usage, see Last login date. If you use Atlassian Crowd, this app can also help you monitor licence usage. For details, see Monitoring license usage.

When you’re on it, review your groups and permission schemes. See if the schemes don’t overlap, if all the groups you have are unique and necessary. Decide which groups need global permissions and which should be granted only project permissions. Understand what function each group has and review them individually.


Need app assistance?

If you require an app to help, you can employ one of the above to give you a helping hand identifying and, some of them, getting rid of inactive users

How do I go about the cleanup?

Delete inactive users manually or using an app. 

How do I automate?

Run regular queries for inactive users and monitor group creation.

  All good? Now you can complete the advanced tasks

Last modified on Apr 22, 2021

Was this helpful?

Yes
No
Provide feedback about this article

In this section

Powered by Confluence and Scroll Viewport.