Tidying Up Jira

[#1]

So, back in 2019, Tidying Up With Marie Kondo on Netflix was a big deal.

While my wife and I enjoyed watching the show, it was really more out of relief, seeing the featured homes and families and be able to say, "Well, at least we're not that bad!" (But I really do need to get rid of some of these tech t-shirts I have. But what if they all spark joy?)

But I digress. Let's talk about tidying up a Jira cloud instance I was working on earlier this year:

The problem:

Jira cloud instance with ~400 users

• 451 projects
• 983 workflows
• 756 workflow schemes
• 215 issue types (!?)
• 721 issue type schemes
• 1213 screens
• 1170 screen schemes
• 372 issue type screen schemes
• 97 permission schemes
• 252 field configurations
• 250 field configuration schemes

First, let's talk about the elephant in the room: How in the world did it get like this?

Well, this Jira instance had some liberally permissive policies that let anyone create projects. But to be blunt, Atlassian didn't do anyone any favors by making projects with Shared Configurations into a second-class citizen in the Create project screens.

In my work below, I found plenty of instances where somebody created several projects with identically customized workflows and screens, even named similarly. But in Atlassian's efforts to offer pre-made templates of every shape and size, they've made it even harder to find the option to create projects that leverage existing work.

But also - this client let anybody create projects. So yes, that's going to be an issue. Your first step then, let's call it step 0.5:

0.5 Governance - create standards, and lock down admin permissions

You don't want to get into this state again. Take some time to find a project that you can call "Company Standard Software Workflow", and maybe a few alternates like, "Company Simple Task Workflow."

Document these workflows. Put them in your Confluence, and list them as the company standard workflows, and note that any customizations will have to be reviewed by the Jira Steering Committee. (This is a real thing that you can set up!) (Yes, this is easier said than done, you will likely have to get "buy-in" and cut through all kinds of bureaucratic corporate red tape. Make sure you get Program Managers and Engineering Managers and QA Managers and Documentation folks all on the same page. This is actually a whole other article.)

But yeah. Policies are good. Then you can remove broad administrator rights. And have standard workflows.

Oh shoot, I almost forgot one more step.

0.75 BACKUP!

Even though we're going to be super-careful, you're ultimately going to be deleting workflows/screens/issue types/schemes that somebody may miss. So then, MAKE A BACKUP, and know how to restore it somewhere so that you can at least visually see what you may need to re-create. Oh hello sandbox feature!

OK! Let's get to cleaning up.

1. Clean up unassociated objects and schemes 

It turns out that many of these objects and schemes for projects that have been deleted, which means they're not associated, and hence, show in the UI as deletable. Bob Swift's venerable CLI is a huge help, as it has actions that let you delete objects and schemes, and they have a "deleteEnabled" option to ensure it only runs on objects that can be deleted. Using those actions, I was able to cut some of these numbers in half.

This works for:

• Issue type screen schemes, screen schemes, and screens. (In that order.)
• Workflow schemes
• Field configuration schemes

With a little bit of extra work with Excel, you can also use CLI to clean up unassociated issue type schemes and inactive workflows.

All of the CLI commands I used (and more) are in this separate article: Jira Cleanup with CLI.

2. So Many Issue Types

Optimizer is your friend. It's clear somebody didn't actually understand what issue types are for, and there was also possible evidence of imports that went awry (issue types named: ABC-1, ABC-2, ABC-3?).

Luckily Optimizer lets you find unused Issue Types and quickly start deleting types with no issues.

WARNING: Before doing this, you want to make sure you can see every issue. The Permission schemes may be in a crazy state, especially with 97 of them. And don't forget about Next-Gen projects.

3. Broken Workflows (1-Step!)

When you export workflows using the CLI action getWorkflowList and add the option --outputFormat 999, the resulting CSV will include a column with the number of steps in that workflow.

In my case, I found several (like at least 50) workflows with only 1-step. These are not valid. (My suspicion is that these were the result of some kind of import that went wrong.)

Working backwards, you can determine which workflow schemes these workflows are part of, and if they are single-workflow workflow schemes, you can replace these schemes with one that includes a standard workflow that will actually allow issues to be closed.

4. Use "Archive" schemes

For any future archiving of projects, first switch them to use these schemes:

• Default Issue Type Scheme
• Archival Issue Type Screen Scheme with (1 screen with all fields listed)
• Shared Field Configuration Scheme (all fields optional)

After archiving Projects, rinse and repeat (clean out all of the unused schemes that you can.)

Final score:

• 451 projects -> 313
• 88,305 issues -> 
• 983 workflows -> 140 (54 of those are Next-Gen)
• 756 workflow schemes -> 65
• 215 issue types (!?) -> 25
• 721 issue type schemes -> 46
• 1213 screens -> 145
• 1170 screen schemes -> 86
• 372 issue type screen schemes -> 53
• 97 permission schemes -> 4
• 252 field configurations -> 11
• 250 field configuration schemes -> 15

• 131 statuses (Never got to this one - it's tricky. That is way too many.)

So... definitely an improvement. But it took a while. And I omitted a lot of very tedious work I did trying to manually find identical workflows.

Hopefully your cleanup effort won't be quite this onerous.

One last tip: Remember to document your work. It's good to open up the initial CLI listings of various schemes in Excel and use that as a record and history of everything you've cleaned up.

Oh, and while this work was done on Jira Cloud, the techniques (and tools!) will certainly apply to Server as well.

[Darryl Lee]

@Matt Doar asked how long the process took, and I'm *really* bad at keeping track of hours. I'd say in total this probably around 40 hours worth of work. I think the most time-consuming bit was trying to come up with clever ways to determine if schemes were duplicates. I was using CLI and the API to get field configurations, screen schemes, and then diffing them, doing hashes and comparing them. It was a lot of work, but if I were to go back, I'd probably skip a lot of that and focus on step #4:

If you can identify a lot of Projects that can be archived, then before doing that you can switch most of their schemes to Default/Show All Fields, which will preserve the data, but allow you to clean out the schemes.

[Dave Bosman [Realdolmen]]

Hi @Darryl Lee 

This seems very familiar to me as we have done this recently for one of our customers. 

The only problem we had was that for each and every change that we wanted to do we had to ask for approval before we could do it. 

This approval caused it to take months of work before we finally where able to finish it. But it is so worth it. 

We also did a check statusses and removed the ones that had the same meaning. So we also had to update multiple workflows.

And also on custom fields as we had multiple fields that had the same name and this leads to a lot of issues when trying to create a filter. Besides that we also had fields with names that where slightly different (synonyms) and where used for the same purpose. So we had to migrate the data from one field to another. 

Regards

Dave 

[Daniel Ebers]

I fully agree, @Darryl Lee - thank you so much for this nice article.
From my past experience all applies exactly like this and what you described it is the way out of those unpleasant situations.
One encounter I like to add, probably a puzzle piece which could have lead to situations like this.
On a rather "wild" Jira instance I found lately Screens, Screen Schemes, Field Configuration, Field Configuration Schemes and Workflow Schemes not being named according to a whatever negotiated pattern. Nearly every user had their own naming scheme making it for fellow admins harder to understand it and align with a concept.
Despite of consolidating, establishing rules, creating documentation also a huge renaming task was started lately where users had to negotiate on ONE naming scheme for all configuration elements. After that all configuration was renames (apart from workflows where this is a pain it was doable but tedious).

Only exception are a few "default" (company-default so to say) configurations, with a very specific and precise meaning like "Company default workflow - Approval and non-Approval issue types". Those were allowed to stay - but all others have now to follow a naming scheme.

[Carol Low]

Hey @Darryl Lee, great article and I'm sure it sparked joy for your client!

Super keen to hear about how you recommend going about setting up standards and governance as well.

[Kristján Mathiesen]

Well written, @Darryl Lee !

[Dave Liao]

How in the world did I miss this article?

I'm doing this now for a Jira instance and I can say that b33r makes it even more enjoyable. 🍻