Now Available: This content is available as a presentation on SlideShare!

Defining issue types, fields, and workflows

How does Jira Software present and store information? There are three main areas to explore: issue types, fields, and workflows.

  • Issue types: issue types are entities that mirror real world objects. Software teams will often use issue types like bugtask, and user story.
  • Fields: fields track attributes surrounding each issue type. Bugs usually have fields like summarydescriptionfix version, and component to describe the area of software where the bug surfaces.
  • Workflow: workflow is the lifecycle of the object represented by the issue type. Bugs are found, reviewed, fixed, verified, and closed by several members of the team.

Jira field greatness_defining issues

Mastering fields

Fields allow teams to track data individually so that it’s easy to search and track later. When organizations first adopt Jira Software, there’s a strong temptation to act like a kid in a candy store and add a whole bunch of fields. Like many things in life, too much of a good thing can be bad!

During a rollout of Jira several years ago, I interviewed many different stakeholders at the company regarding what data they wanted to track on one of our issue types. The stakeholders spanned several areas of the business and had key requirements for the new system. What did I find out? The business wanted to track over 60 different fields on this one particular issue type. To put that into perspective, the average tax return in the United States has between 20 and 80 different fields. We were asking each user to put the same amount of effort into putting an issue into Jira as it was required to file taxes!

We were victims of field-itis.

Jira field greatness_fielditis

Diagnosing field-itis

Field-itis is a common condition in many Jira Software instances when the team asks for too much information from its user base. When someone requests a field, they tend to not realize that their field has a cost. Every time a new field is added into Jira Software, it becomes harder for users to create issues. No one likes to see a giant form with lots of cryptic terms in it. How do you know if you’re struggling from field-itis? Let’s center around three important questions:

  • Are people neglecting to fill out all of the necessary information when creating issues?
  • Do people not submit issues because it’s too much work?
  • Are certain fields collecting bogus information because end users don’t understand them?

8 cures for common field-itis

1. Ensure the field meaningfully impacts the business

Administrators, when someone asks you to add a field into Jira Software, I’d encourage you to always ask the following questions:

  • What is the business value of this field? In other words, how does knowing this information meaningfully impact how you do your job?
  • What is required of the end user to submit this information? How long does it take a user to reliably collect and submit the information correctly? Is there any way to automate capturing that information?
  • When in the issue lifecycle do you need this information?

Every field has a cost. Users have to:

  • Understand what the field is
  • Enter data
  • Update it as its value changes over time

For fields to be useful, they need to be filled out accurately and contain current information. When the system becomes cumbersome, users no longer enter quality data. Field rot then sets in, as the data is no longer dependable. Ensure each and every field is legitimately needed.

2. Order fields on screens

By default, Jira Software adds new fields to the bottom of the screen. When an administrator initially builds a screen, all the fields are in a logical order for that application. As the team needs extra fields, take the time to add them to the right place on the right screen. Doing so will optimize the data entry experience for your end users. Each new field should bring a user closer to completion. Let’s look at two forms:

Jira field greatness_form flow

While the first one does capture all of the right data, the second screen has a much more intuitive flow. Ask a few people who use each screen on a regular basis if the flow is right. Fine tuning the flow will help users enter better data, making for a more optimized workflow for the entire team.

3. Fill out the field description

When a custom field is added to Jira Software, you have the option of adding a description of the new field. Make use of that description so users can learn what information is needed in the field. I’d keep the description short so that the overall screen remains compact. You can use HTML in field descriptions, too, so that it’s easy to link off to more extensive documentation. For example, let’s look at a sample description for a field called build number.

The build number is the current version of software. See the build docs for how to find the build number.

Educating your users goes a long way towards making everyone more efficient in the team.

4. Respect the required option

If you take one piece of advice from me in this post, make it this one: use the required attribute carefully. There’s a strong temptation to make fields required. You need the data, right? So why not ensure the users enter it? Well, if your users don’t know what to enter, they may give you bad data – and bad data is worse than no data. It’s hard to get rid of bad data in searches and that makes reporting a nightmare.

If you must require a field:

  • Have a way to say “I don’t know”
  • Give a field description (see step 3 again)

People, in general, want to do the right thing. If team members are artificially blocked, they’ll often go around the gates to be heard. Teach people how to be complete rather than making issue submission difficult.

5. Remove unnecessary fields

Teams often change, and what was important a year ago may not be so important now. I’ve found many times, users will say, “I absolutely need this field!” then a couple of months go by, and the team doesn’t use the field in the way the requester originally intended. In Jira Software, you can easily search to see how many issues use a particular field. Let’s say we added a field called build number to the issue type bug. We can then run two queries to see the percent utilization of that field.

Bugs that don’t have a build number

[cce]type = bug and “Build Number” is empty and created > “2013-02-01″[/cce]

Bugs that have a build number

[cce]type = bug and “Build Number” is not empty and created > “2013-02-01″[/cce]

I added the clause created > “2013-02-01” so that I exclude issues created before I added that field. What do I do If I don’t have that data? Run the this query:
[cce]type = bug and “Build Number” is not empty and created > “2013-02-01”
ORDER BY created ASC[/cce]

You can then use the first issue’s created date.

We can then compare the number of bugs that have a build number with the ones that don’t. If the team isn’t effectively utilizing the build number field, they have a decision to make: do they require the field?

If they do require the field, running this type of query becomes much harder to do (see step 4).

6. Spread out data entry

In many organizations, a collection of data around the particular issue type happens throughout the workflow. For example, a bug requires things like summary and description up front. It’s not until the bug gets fixed that it needs a field for resolutionfix version, and optionally, be assigned to a code reviewer.

Jira field greatness_data entry

With Jira Software, administrators can customize screens to make data entry a more natural experience. Users reporting issues only see the fields relevant to them. When an engineer reviews an issue, only the fields that are relevant for that operation appear. That way, no one is overwhelmed with all the fields at once.

In Jira Software, the issue detail view has all the fields listed. The product team has taken great strides in organizing how that information is presented to you, the user. With clear headings for issue details involving people, dates, and descriptions, it’s easy to find the details you’re looking for.

7. Scope each field

When administrators create custom fields, they have the option to limit them to certain projects or make them available to all projects. Using project contexts to limit where custom fields show up makes it easier for everyone. Forms that only have what’s necessary makes everyone more efficient.

Customers that have large instances of Jira Software can learn more from our guide about scaling Jira Software. We’ve included a section about custom fields that will help you learn how to optimize performance of your instance.

8. Automate all the things

I’ve saved the best tip for last! Automation allows you to collect data efficiently and correctly.

Jira Software has a flexible REST API that makes it easy for external applications to create issues and populate custom fields. Developers have easy access to a wealth of information that can be difficult or tedious for users to manually enter. Empower your engineers to help them get better issues by connecting Jira Software to your application.

With the REST API, engineers can then get high-fidelity detail about reported issues without burdening users with large amounts of manual work.

Maximizing fields

Fields are an integral part of Jira Software and they’re what makes the platform work in so many organizations. As administrators, one of our key contributions is helping people understand best practices for using Jira Software. Using fields for what they’re great for, and minimizing the downsides helps everyone be more successful with Jira Software.

It’s easy to add fields right from the issue detail screen.

Jira field greatness_add field

There’s also a field gallery so administrators can see a visual representation of the field before they add it.

Jira field greatness_field gallery

Jira Software makes it easy to build field configurations to share across many projects, making maintenance easy. Jira Software notifies the administrator if a new field will impact other projects. The administrator can then decide how he or she wants to proceed.

In addition, many custom field types are available on the Atlassian Marketplace for download into your Jira Software installation.

Ready for more Jira tips and tricks? Sign up for our monthly Jira Insiders newsletter, and click below for more tips and best practices blogs.

Bring on the Jira tips!


Did you find this post useful? Share it on your social network of choice so fellow Jira users can learn tips and tricks for mastering Jira fields, too!

8 steps to Jira field greatness