Overview

I once wrote an article with the provocative title Bug Trackers: Do They Really All Suck?. My conclusion was probably not, but that they are all annoying in some way. Why is this? My theory is that it’s because tools such as JIRA are used by multiple groups of people. This means that each group has different needs from the same tool, which in turn leads to no one being fully satisfied. However, the advantages of using a single tool can often outweigh the functionality of separate tools.

So what can be done? I think the first thing to remember is that every problem is at root a people problem (Jerry Weinberg). What that means for you and your JIRA is that decisions about using the tool need to be discussed and agreed upon by the people who use the tool. Tools can only help to reduce the barriers for people and groups working together; there is no magic tool to make people want to work together.

That said, this chapter describes some of the more common frustrations with JIRA and possible ways to avoid some of them. These include both things that annoy users if not configured properly by administrators, and aspects of JIRA that annoy JIRA administrators.

Add-Ons That Should Be Standard

There are some useful, well-supported, and even free (zero cost) add-ons that I install in almost every JIRA instance that I configure. This suggests to me that their functionality should be part of the core JIRA functionality. My four standard add-ons are currently:

JIRA Toolkit Plugin

This is the grandfather of all JIRA add-ons, and contains too many useful features to list.

JIRA Suite Utilities

Also known as JSU, this add-on has the custom fields, conditions, validators, and post functions that everyone uses.

JIRA Misc Workflow Extensions

JMWE has conditions, validators, and post-functions (the earlier name for post functions), all in a code base that has probably been used as the base for more customizations than any other add-on. JMWE become a commercial add-on in 2013 and is also available in JIRA Cloud.

ScriptRunner for JIRA

ScriptRunner for JIRA, formerly Script Runner, lets you run scripts written in Groovy inside JIRA. Groovy is very similar to Java if you haven’t used it before. The add-on also comes with customizable workflow conditions, validators and post functions, listeners, and services. No restarts are needed and there are no other add-ons to install. You get far greater flexibility for modifying JIRA and the ability to script many tedious administration tasks. It requires JIRA administrator permission to run such general scripts. Jamie Echlin, the author of this add-on, joined Adaptavist in 2015 and the plan is to make this a commercial add-on by the end of 2015.

Frustrations with Fields

One of the most common frustrations for users is having to enter data in fields that they don’t understand or care about. This can happen in a number of ways:

• A field may be required by one team, but not another.

  The solution for this is to define a field configuration and screens for use by just that team’s projects, along with the other schemes for their projects. Grouping projects into project categories can help with maintaining such schemes, as described in Chapter 4.

• The field’s description may be missing or misleading.

  Don’t accept a request for a new custom field unless it comes with a succinct and clear description of what the field is intended for. Then use that as the field’s description. The description of a field in a field configuration overrides the original custom field description.

• The field’s name is a duplicate.

  JIRA allows multiple custom fields with the same name, but it is almost always a mistake to do this because in some places you’ll have multiple choices with no distinguishing information. If you do decide to do this, then at least give each field a good description.

• The field is being used as a combination of other fields.

  This can happen if custom fields aren’t added when needed, so users overload an existing field (such as Summary) to record two or more pieces of information. For example, I’ve seen Summary fields that contain text such as Showstopper: customer can’t log in. The Showstopper part of that field should have been recorded in some other field, probably Priority, to allow better reporting lafter on. It’s also easy to forget the convention, or use it without really understanding it (perhaps using it just because some other issues did).

• Required fields are not on the default tab.

  Just don’t do this when you’re designing screens. Put all the required fields on the default tab, so you don’t forget that they’re required during issue creation. Put them higher up on the screen so users don’t have to scroll down to edit them.

Frustrations with Actions

Other frustrations for users center around issue actions and workflow transitions:

• Why can’t I change an issue to a certain status?

  If it’s just certain transitions, then it’s probably due to conditions and validations that have been defined as part of the workflow for the issue. These conditions may or may not make any use of the Resolve Issues and Close Issues permissions, depending on how the workflow is configured (see Chapter 5).

  Adding the introduction gadget to the system dashboard and including links to documents that describe such expected restrictions can help. The ability to display the status of an issue within the workflow diagram can also help with this frustration.

• What permission do I need for a certain issue operation?

  The Permission Helper feature described in “Debugging Schemes” can help administrators to debug these problems. Permissions are controlled with the permission scheme that an issue’s project is using. To edit an issue, a user needs to have the Edit permission, which may be granted by project role or any of the other ways listed in the section “Adding Users to Schemes”.

  Some of the less obvious permissions are noted in the section “Permission Schemes”. Changing a permission usually involves adding a user to a specific project role, rather than modifying the permission scheme.

• Why can’t I bulk change some issues?

  The default JIRA workflow doesn’t let you edit issues in the Closed status. So if you want to change a field in a hundred issues using Bulk Change but just one of those issues is closed, then JIRA won’t let you change any of them. Sometimes there’s an explanation given, but more often it’s a puzzle to users and their administrators. Start with a smaller set of issues and see if you can bulk change those issues.

  Not all of an issue’s fields can always be altered using a Bulk Change. For example, the Resolution field can only be changed if the field configuration hasn’t hidden that field.

More Information Needed!

Sometimes users need more guidance about where to create or not create issues, and what should go into each field. What is needed is a way to add this information to JIRA’s issue screens.

For just this reason, the Message custom field types are part of the standard JIRA Toolkit add-on available from Atlassian. These field types allow you to display text on an issue’s screens. For example, the Message Custom Field (for edit) field type allows you to insert text between other fields on an edit screen. Other custom field types from the same add-on allow you to insert HTML to create the message. As shown in Figure 11-1, Atlassian uses these fields to provide additional guidance to users who are filing bugs with them.

Figure 11-1. Adding helpful text to an issue screen

These message fields are defined just like any other custom field except that the text is set as a default value, and the fields are added to screens as usual. They don’t have any values and do not appear in an issue otherwise. Sometimes they can appear unexpectedly on bulk change screens though. Since the message custom field names are not seen on the issue screens you can give them abstract names such as Message 1 and Message 2 and reuse them in multiple custom field contexts.

Frustrations with Email

How can you make sure that another user is notified of changes to a particular issue? That is what the Watchers system field is for. But even after another user has been added to the Watchers field, they won’t receive email about the issue until the next change after that. It’s like having a Cc on an email that only works for the next email.

Sometimes a user wants to just poke someone about an issue, but isn’t sure who else will receive the email if they add a comment. This is like Reply to All, but without being able to see the To field. What is really needed is the current list of email recipients for each action, just for when it is wanted. The JIRA Email This Issue Plugin can help older versions of JIRA with this.

The Notification Helper feature described in “Debugging Schemes” can help administrators debug why a particular user is not receiving email about changes to a certain issue.

Learning JIRA Safely

The first thing that any new administrator usually does with JIRA is to create a test project and a few test issues. The next thing they might do is change the default priorities and then start in on some workflow changes. A few minutes later, they wish they had made a backup and hadn’t been playing around with the production JIRA instance.

Now, playing about is a powerful way¹ to learn any tool as a new user or administrator, but do it somewhere that won’t matter when you make mistakes. Having a development or staging instance of JIRA is a great idea for this.

If you’re concerned about sending email to other people as a result of your changes, then you can define an empty notification scheme for the JIRA project where you are playing with issues. You could also do the same thing by just removing the notification scheme from a project, but using an empty scheme makes it clearer in Administration→Issues→Notification schemes as to which projects don’t send email.

I also like to have a project named SCRATCH in production JIRA instances that is configured with the same schemes as one of my more heavily-used JIRA projects. I use that project to create test issues when checking my changes and avoid cluttering up any real projects.

Another thing I do is to maintain a separate JIRA project or component to track issues related to the local JIRA instance. This is using JIRA as a meta-tracker and it helps for all the same reasons you installed JIRA in the first place.

Too Many Administrators

Having too many JIRA administrators invariably leads to a JIRA instance with a confusing configuration. The temptation to experiment and hack until JIRA appears to do what you want seems to be irresistible. A main administrator, a couple of backup administrators, and maybe an IT-related administrator are usually all that should be needed. I recommend trimming the jira-administrators group regularly.

One oft-overlooked aspect of JIRA is that you can have both jira-administrators and jira-system-administrators groups. The differences between these two groups are described at http://bit.ly/ZFou2b. By default, the two groups are effectively the same, but one way to reduce what the existing JIRA administrators can do is to go to Administration→System→Global permissions, and set the group used for JIRA System Administrators to a new jira-system-administrators group.

You may wonder Why have I got so many administrators in my JIRA? The most likely explanation is that earlier versions of JIRA allowed only JIRA administrators to add components and versions to a project. This implied that project leads had to also be JIRA administrators, which often led to many users in the jira-administrators group. The better approach nowadays is to use JIRA project roles (see the section “Project Roles”), which let you grant project leads the permissions they need for their projects without destabilizing the rest of your JIRA instance. Adding new options to custom fields still needs JIRA administrative rights, but that kind of request can be better handled by filing a JIRA for the work with an administrator.

Automating Your Configuration

A common task for a JIRA administrator is doing something that the UI makes easy for one and tedious for ten. For example, adding a user is easy, but adding ten users requires a lot of clicking. There are at least two ways to automate JIRA administration.

The first approach is to use the same ScriptRunner add-on by Jamie Echlin (Adaptavist) described in “Add-Ons That Should Be Standard”. This add-on has many canned scripts to do such things as copy the configuration from one project to another or modify resolutions in bulk. This add-on is also the most general way to access the underlying JIRA Java API for administration operations.

The second approach is to use a CLI as described in “CLI (Command Line Interface)”. The problem with this is that not all of the APIs you might want for administration are exposed by JIRA. This approach is relatively easy to use if you are only modifying issue or project data, but most administrative actions are harder (if even possible).

JIRA used to support a deprecated scripting language named Jelly, but this was removed in JIRA 6.4.

For automating workflow actions (such as periodic escalation of issues or changing status when a comment is added), the JIRA Automation Plugin add-on by Atlassian (unsupported) is worth investigating.

Debugging Your Configuration

Working out why a user can’t see or do something they expect can take a few frustrating minutes, even when you have a good procedure.

My approach, described in more detail in “Debugging Schemes”, is to note the issue’s project and issue type, then go to the project’s administration screen. Note the names of all of the schemes that the project is using and then view the appropriate one. For example, for permissions, view the named permission scheme and see which project roles are needed for the permission in question. Then return to the project’s administration screen and go to the project’s roles to see which users have that role in the project.

For more complex schemes (such as the issue type screen scheme), view the scheme and use the issue type to work out which screen scheme is being applied. Then look at that screen scheme to work out which of the screens is involved. Finally, view that screen to see whether the field is shown or not, and where.

Managing Custom Fields

Managing large numbers of custom fields (more than a few hundred) can be difficult because you have to scroll up and down to find the field you want. The find feature in your browser can help here. JIRA permits multiple custom fields with the same name and field type, so check carefully which issue types and projects each custom field is applied to. Even a single custom field can have multiple contexts, one per project, so you may have to click Configure for a field before you can see all the ways that a field is configured.

Managing Projects

JIRA 6.0 added the ability to edit a workflow scheme in place, which also updates the scheme for all other projects that are using it. Before this you had to manually update each project’s workflow scheme if you added a new mapping from an issue type to a workflow, which could be very tedious if you had many projects, as noted at The Hundred Tab Problem (JRA-25961).

JIRA 6.0 also introduced the idea of project templates. When creating a new project you can choose from a number of predefined templates, which in turn use predefined schemes.

Once a JIRA project has been configured as intended, a common request is to create another project configured in exactly the same way. The new project will likely be part of a number of projects with the same category. JIRA has no built-in way to use a single project as a template for another, but the Project Creator for JIRA add-on from Wittified can help with this.

Further Reading

There is an excellent presentation, “Seven Sins of Jira Administration” by Matthew Cobby that contains a series of pithy patterns to avoid, plus characters familiar to all.

The JIRA Email This Issue Plugin can be found in the Atlassian marketplace.