Clean up your Jira instance

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

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 organization. See Prepare for the cleanup for more about determining business rules and getting the right people involved.  

For easy access to tools and tips that can help you deal with unwanted data, go to  > System > Clean up.

Process overview

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

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.

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. 

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 and Is there an easy way to archive a lot of issues?

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.

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 and Is there an easy way to archive a lot of issues?

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.

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.

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

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

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%'

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. 

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.

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