By Matt Doar
ServiceRocket's Chief Toolsmith
Author of the O'Reilly book Practical JIRA Administration

I've worked with people setting up JIRA for nearly ten years now, so I've seen some mistakes that come up again and again. Like any list there are occasional exceptions, but these five guidelines should hold true more often than not.

1. Avoid Confusing Names for Custom Fields

Don't add custom fields with the same name as the standard JIRA fields. It makes writing searches harder. Also don't add multiple custom fields with the same name, even though JIRA will let you do this. Again, it's just too confusing. Check first if a custom field with the same name already exists.

2. Don't Add An Unresolved Resolution

JIRA has a standard field named Resolution that is empty when you create a new issue. When an issue is closed this field is set to a value such as "Fixed" or "Duplicate", and the issue key has a handy strike drawn through it like this: TEST-123. Don't create your own resolution value named Unresolved because then JIRA will draw a line through the issues that you're still working on. And even worse, most of the standard JIRA gadgets will not work as you expect them to.

3. Use Roles not Groups

JIRA groups are collections of JIRA users, but they can only be changed by the all-powerful JIRA administrators, and you don't want to have too many of those.

However you can also define project administrators who can only affect what happens to a single JIRA project. For groups of JIRA users it's often a better idea to use project roles instead of groups, since who is in a role can be changed by project administrators. Better scaling all around.

4. Don't Copy the Default Workflow

The default JIRA workflow, the one named "jira" or "classic", doesn't let you edit issues when they're closed. This makes updating many issues at once much harder than it should be. The default workflow also has some hidden restrictions on who can change the status of an issue. I recommend creating workflows from scratch using any one of the workflow editors.

5. Clear the Resolution When You Reopen Issues

If you create a workflow from scratch make sure that you set the resolution when an issue moves to a status where no more work is going to be done on it. But also make sure that you clear the resolution using a post-function. If you forget to do this then you'll end up with reopened issues that have a resolution such as "Fixed" but with a confusing line drawn through them.

Learn the skills of a JIRA Administration guru with our new eLearning for JIRA Administration course.