JIRA Tutorial

JIRA Tutorial

This tutorial gives you an overview and talks about the fundamentals of Atlassian JIRA.

What is JIRA ?

At its very core JIRA is a software program that helps organizations manage their issues, tasks, processes, and projects. However, it is ‘smart software’ because much of the tedious stuff related to issues, or tasks, or processes, or project management, can be automated fairly easily. 

JIRA started life in Atlassian (the parent company) as a way to track issues related to software ‘bugs’. It wasn’t long before additional features were added and it grew into a project management program with the ability to ‘automate’ a lot of the work that is necessary but provides little value, such as emailing or phoning a work colleague when a task is done and ready to be handed off.

The JIRA architecture

Installing JIRA is simple and straightforward. However, it is important for you to understand the components that make up the overall architecture of JIRA and the installation options available. This will help you make an informed decision and be better prepared for future maintenance and troubleshooting.

Atlassian provides a comprehensive overview of the JIRA architecture at https://developer.atlassian.com/display/ JIRADEV/JIRA+Architectural+Overview. However, for day-to-day administration and usage of JIRA, we do not need to go into details; the information provided can be overwhelming at first glance. For this reason, we have summarized a high-level overview that highlights the most important components in the architecture, as shown in the following figure:

jira training

Web browsers

JIRA is a web application, so there is no need for users to install anything on their machines. All they need is a web browser that is compatible with JIRA. The following table summarizes the browser requirements for JIRA:

Browsers Compatibility
Internet Explorer 8.0 (not supported with JIRA 6.3)9.0, 10.0, 11.0
Mozilla Firefox Latest stable versions
Safari Latest stable versions on Mac OSX
Google Chrome Latest stable versions
Mobile Mobile SafariMobile Chrome

Application services

The application services layer contains all the functions and services provided by JIRA. These services include various business functions, such as workflow and notification, which will be discussed in depth in Jira trainingWorkflows and Business ProcessesE-mails and Notifications, respectively. Other services such as REST/Web Service provide integration points to other applications The OSGi service provides the base add-on framework to extend JIRA’s functionalities.

Data storage

The data storage layer stores persistent data in several places within JIRA. Most business data, such as projects and issues, are stored in a relational database. Content such as uploaded attachments and search indexes are stored in the filesystem in the JIRA_HOME directory, which we will talk about in the next section. The underlying relational database used is transparent to the users, and you can migrate from one database to another with ease as referenced athttps://confluence.atlassian.com/display/JIRA/Switching+Databases.

Installation of JIRA would be covered as part of  JIRA Training.

1. Groups Versus Roles


The difference between JIRA groups and JIRA project roles seems to confuse many JIRA administrators. This chapter explains the differences and what each one is good for.

JIRA originally just had users and groups of users, and no project roles. Groups were pretty powerful — wherever you could do something with a user, you could generally use a group instead.

For instance, if you wanted to allow a specific user john.smith to change the Reporter field in a project’s issues, you could:

1. Create a new permission scheme with a description something like john.smith can change Reporter.

2. Next, add the john.smith user to the appropriate Modify Reporter permission entry in the new permission scheme.

3. Change the appropriate JIRA project to use the new permission scheme.

You could also do the same thing with a group:

1. Define a new JIRA group named Can Modify Reporters.

2. Add the user john.smith to the new group.

3. Create a new permission scheme with a description something like Added an extra group of users that can change Reporter.

4. Add the group (instead of the user) to the appropriate Modify Reporter permission entry in the new permission scheme.

5. Just as before, change the appropriate JIRA project to use the new permission scheme.

Both of these approaches now allow john.smith to change the Reporter field. So far so good, but there are two main problems with using JIRA groups like this: scaling and updating.


If you want john.smith to be able to edit the Reporter field in some projects, and also allow a different user, jane.bloggs, to do the same thing in other projects, then you have to create two permission schemes, one for each user being granted this permission. If you then decide that they are both allowed to edit the Reporter in some shared projects, then you need a third permission scheme. With lots of users, this leads to an explosion in the number of permission schemes (and any other JIRA scheme that supports groups).

Keeping track of the difference between each of these permission schemes is tedious and error-prone, even with the scheme comparison tools (Administration→Scheme Tools), which are themselves deprecated in JIRA 6.4.


As time passes, users will likely need to be part of different JIRA groups. Only JIRA administrators can change the membership of JIRA groups. However project leads are allowed to make changes to project roles, and project leads usually know which project roles a user should currently be part of. Using project roles means fewer tasks for JIRA administrators.

Project Roles

What was needed to avoid these problems with JIRA groups was another level of indirection,1 and that’s exactly what JIRA project roles are. The below diagram shows the basic idea.


JIRA has three default project roles: Administrators, Developers, and Users. The current members of these roles for each project can be seen at Administration→Projects: click on the project name, then Roles.

The number and names of the roles can be changed at Administration→User management→Roles, but for now let’s stick with the three default roles. Every JIRA project has the same set of project roles all the time. The default members of each role for new projects are shown in below diagram. Note that the project lead is not a default member of the Administrators role and has to be explicitly added.


For each role in every project, a JIRA administrator or a project administrator can define who plays that role by adding or removing a user or a group for the role.

For example, you could add an individual contractor using JIRA to the Users role for only the projects they need to work with. For such JIRA instances, I usually create a new JIRA group named something like “my-company-name-staff” and then replace the “jira-users” group with the new group throughout JIRA. I then create a JIRA group for each set of contractors and add that group to the appropriate project roles for select JIRA projects (and also to the “JIRA Users” permission at Administration→System→Global permissions).

Once you’ve chosen who plays each role for each project, you can use the roles in your schemes. For instance, when you look at the default permission scheme you’ll see that all of the permissions are granted to project roles, not directly to users or groups. The significant thing about roles is that they can be changed for each project by people who are in the Administrators role but are not JIRA administrators. These people can now create versions and components for their project without needing to change the underlying configuration of JIRA or needing to be JIRA administrators.

To put all that another way:

Who can change a project’s versions and components?

The users who have the Administer Projects permission.

Which users have the Administer Projects permission?

Check the specific permission scheme, but it’s usually only people in the Administrators project role.

Which users have the Administrators project role?

Members of the jira-administrators group and anyone else that you add to that role for a project.

Who can change other parts of JIRA’s configuration?

Only members of the jira-administrators group, not the users who have the Administrators project. Project administrators can’t change workflows, for example.

Creating a New Project Role

Another way to understand what’s going on here is to create a new project role. Let’s say that for some reason, we want to allow the technical publications (Tech Pubs) users assigned to each project to modify the Reporter of an issue.

The default permission scheme already allows users with an Administrator role in a project to modify the Reporter of an issue. But we don’t want to allow the Tech Pubs user to administer the whole project: we just want to give them that one specific permission.

We can create a new role Documentation, at Administration→User management→Roles. We can also add our Tech Pubs lead bobby.jones as a default member in the Users column under Manage Default Users of the new project role so that he will be in the Documentation role for all new projects by default.

Now every JIRA project has this new role, since you can’t add a new project role just for one JIRA project. When a new JIRA project is created, it will have the bobby.jones user in the Documentation role for the project. For existing projects, we can manually add the appropriate Tech Pubs user (or group) to the Documentation role for each project. Once the users for this role have been added, we can edit the appropriate permission schemes and add the Documentation role to the Modify Reporter permission entry. The permission scheme now checks which users are in the role for each project, rather than looking at a fixed list of users or groups of users.

If the Tech Pubs person changes for the project, then the people in the project role Administrator can change the members of the Documentation role for just that project. There is no need to ask a JIRA administrator to make the changes.

Tip: An example of a good description for a newly created role is “This new project role is for identifying Facilities staff in non-Facilities projects.” Creating a wiki page that describes the intended purpose of each new role is another good idea.

For more information about using project roles to control which users can view which projects, see “Hiding Projects from Users”.

From the other direction, you can also see which roles an individual user has in all the JIRA projects: go to Administration→User management→Users, find the user, and click on Project Roles.

The easiest way to allow everyone to see the members of each role for a JIRA project is to install the Project Role Tab add-on. This add-on allows JIRA administrators to tell their users to contact the project administrators for certain changes.

Not Creating New Project Roles

Sometimes I see JIRA instances where roles have been treated like groups. This results in many roles being created, but many of these only make sense in a few projects. For instance, if you create a new role named Operations and then have a JIRA project for tracking job applications, there may be no obvious use for Operations and job applications. The best approach is to keep the number of roles as small and generic as possible. Some useful examples of names for extra roles are: Creators, Approvers, Managers, Workers, Testers and Schedulers. These names are generic and apply to more than just software development.

Another configuration problem I see is using user names in the default memberships of roles. What happens is that every new project has the user name set for the role, but when the user leaves, every project has to be modified to change the role. This is a good argument for using only groups as default role members.

One mistake I’ve seen have some serious consequences is using a project role in a notification scheme. This can happen when you want to allow project administrators to send specific users an email when an issue is created in their project. It’s easy to create a project role such as Notify on All Create Issue and add it to the notification scheme. The problem is that a unknowing project administrator can add a large group such as jira-users to the project role and then every single person in jira-users will receive email when a new issue is created. In a large organization this can be thousands of users being spammed each time. I recommend not using project roles in notification schemes if possible.

Tip: You should only create a new project role if you are going to use it in a scheme or workflow, and if it applies to all your JIRA projects.

2. Resolved, Resolution, and Resolution Date


One thing that sometimes confuses both JIRA users and administrators is the difference between the Resolved status and the Resolution field. This chapter clears up some of the confusion between these very similar-sounding terms.

Getting this right is important, because many of the standard JIRA reporting gadgets on dashboards expect the Resolution field to be set as expected — otherwise confusing results occur. For example, gadgets that refer to the date when issues were resolved use the Resolution Date field, which is in turn based on the Resolution field.


JIRA comes with a default workflow (Administration→Issues→Workflows) named jira, shown later in the default Jira workflow and summarized below in diagram. This workflow has the following statuses for an issue, shown in the order they commonly occur.


The idea is that an issue (such as a bug) is created with a status of Open, and is then moved to In Progress and then Resolved by the person who fixes it. The bug is then moved to either Closed or Reopened by someone who checks whether it really was fixed or not. So Resolved is just a name for an issue status. The status could just as well have been named Believed Fixed or Ready for Testing.

Caution: If you create a workflow from scratch (see 5. Creating a workflow from scratch), the Resolved status is not connected in any way with the Resolution field.


It’s generally a good idea to keep the number of statuses in your workflow as small as possible to make maintenance easier. It makes sense to avoid having lots of statuses with names like:

  • Closed and Fixed
  • Closed and Won’t Fix
  • Closed Because It’s A Duplicate
  • Closed Since…

The Resolution system field (Administration→Issues→Resolutions) can be used to avoid having lots of similar statuses. The default values for Resolution of Fixed, Won’t Fix, Duplicate, Incomplete, Cannot Reproduce, Done and Won’t Do cover many of the ways that an issue could be closed, and you can change this list if necessary. I find that a Complete resolution is often useful for generic tasks that are finished. Canceled is a gentler form of Won’t Fix, but has spelling variants. Once the Resolution field in an issue contains any value at all, then links to that issue will have a line through them to indicate that the issue is resolved.

The intended use of the Resolution field is that when a bug is created, the field is empty, with no value at all. This is displayed in an issue as a value of Unresolved. When an issue is moved to a status such as Resolved or Closed, the Resolve Issue Screen is usually shown during the transition. This screen includes the Resolution field, ready for the user to set a value. A bug can have its Resolution set to Fixed while it is moving to the Resolved status, for example.

Tip: JIRA expects the Resolution field to be set in any status you would consider an issue resolved, and that the Resolution field should be cleared in all other statuses. It’s up to you to make sure this happens, with a transition screen or post function when you create or modify workflows (see 5. Creating a workflow from scratch).

In the default JIRA workflow, the Resolve Issue Screen is the only screen where you can set the Resolution field for an issue, and this screen is only used for transitions to the Resolved and Closed statuses. In your own workflows you are responsible for making sure that the Resolution is set. Once the Resolution has been set, the issue is considered resolved by JIRA, even if the status of the issue is not the Resolved status but some other status defined by you (such as Deployed).

Caution: The only way to remove the resolution from an issue in a standard JIRA installation is to Reopen an issue. Adding the Resolution field to the Default Screen or any other non-transition screen to make it easier to change is a bad idea, because it is a required field and will get set for issues that aren’t yet resolved. You can see which screens the Resolution field is on by looking at any field configuration (Administration→Issues→Field configurations)

Another approach for cleaning up the results of an incorrect workflow and clearing the Resolution field in an issue is to create transitions back to the same status that have a post function to clear the Resolution. The ability to create transitions back to the same status is a non-obvious and useful ability for workflow designs.

One way to make sure you don’t have problems with the Resolution field and custom workflows is to create and save the JQL filter: status = Open and resolution is not empty order by created desc. This filter should always return zero issues. If there are Open issues with a resolution set being created, then you can look at a recent issue’s History tab and see where the resolution was not cleared. You can even set up a filter subscription to email any non-zero results to you.

A similarly useful query is status = Closed and resolution is empty order by created desc, which helps find workflows where the Close transition does not set the Resolution field. This filter should also return zero issues.

Resolution Date

The Resolution Date system field is the latest date that any value was set in the Resolution system field for that issue. The Resolution Date field will only be empty if there is no value at all in the Resolution field.

Caution: The Resolution Date is confusingly named Resolved in the list of Issue Navigator columns and some gadgets. This has nothing directly to do with the status named Resolved.

Other Appraoches

Some organizations using JIRA don’t use the Resolution field for a number of reasons:

  1. It’s hard to reset the value to empty for unresolved issues.
  2. The resolution field doesn’t appear on standard screens, only during transitions.
  3. If the Resolution field is used on any custom transition screens, it’s hard to make the field not be required.

Instead, they base their reporting only on the name of the statuses in the workflows. They may also create their own custom Select List field named something like Our Resolution or Sub-status, with its own values such as Unresolved, Fixed, Won’t Fix, Duplicate, Incomplete, and Cannot Reproduce.

Tip: The drawback of not using the system Resolution field as JIRA intended is that many of the standard JIRA gadgets are no longer useful. Making sure that the Resolution is set correctly in your workflow is a better approach in the long run (see the section “Implementing a Workflow”).

The options for the Resolution field are defined for all JIRA projects and workflows. Sometimes you may want to restrict the resolutions used in a workflow. One way to do this is to use Workflow Properties. Another way to do this per issue type is to have a custom field with the Resolution options you want for each issue type, and then use a workflow post function to set the Resolution system field based on the value of the custom field (thanks to Joanna Thurmann for that idea).

A helpful approach to consider in custom workflows is creating a transition for each desired resolution, with a post function in each transition to set the resolution without using a screen. For example, there could be a transition from the current status to Closed named “Duplicate,” which automatically sets the resolution to Duplicate.

Caution: Adding a resolution named Unresolved to the system Resolution field is a bad idea, because since the Resolution field now has a value, the issue will still be treated as resolved by the standard JIRA gadgets.

3. Understanding Schemes


Schemes are a major part of configuring JIRA, but they are also one of the most confusing parts of JIRA. This chapter is intended to clear up some of that confusion. 4. Jira as a Platform has a worked example of how schemes can be used to configure JIRA.

A JIRA scheme is a collection of configured values that can be used by one or more JIRA projects. For example, a Notification scheme describes who receives email when issues are changed. The same Notification scheme can be used by more than one JIRA project. In fact, the Default Notification scheme is used by all JIRA projects unless you configure a project differently.

The seven schemes that are active for a particular JIRA project can be viewed and edited by editing the project (go to Administration→Projects and click on the project name, not Edit).

We’ll cover the four schemes that are similar to the Notification scheme first and look at the remaining three (more complex) schemes later. The top-level page in the Atlassian documentation for all of this information is http://confluence.atlassian.com/display/JIRA/Defining+a+Project.

Project-Wide Schemes

The four schemes like the Notification scheme that apply either to the whole JIRA project, or to all issue types within a project are:

Issue Type Scheme

What issue types (Bug, New Feature etc) can be used in a particular JIRA project

Notification Scheme

Who receives what email when an issue changes

Permission Scheme

Who can do what to an issue

Issue Security Scheme

Who can even view an issue   First we’ll take a quick detour to see how JIRA refers to users in such schemes.

Adding Users to Schemes

There are a dozen different ways (shown in Referring to users in a scheme diagram) that JIRA lets you specify a set of users, but happily the same ways can be used in both Notification and Permission Schemes. Issue Security schemes use a subset of these choices.


The simplest of these are:

Current Assignee

The user that the issue is currently assigned to.


The reporter of the issue; usually the JIRA user who originally created the issue.

Current User

For permission schemes, the user who is logged in.

Project Lead

Component Lead

The project lead is specified in each project’s settings. Component leads are optionally configured for each component in a project.

Single Email Address

A specific email address. This only works for issues that can be browsed anonymously. Before JIRA 5 the email is formatted as text, not HTML.

All Watchers

All users listed in the system field Watchers for an issue.     

The not-so-obvious ways are:

Single User

A username such as john.smith, not their full name such as John Q. Smith.Group

Project Role

A JIRA group of users or a JIRA project role. In general, use a Project Role instead of a Group, as discussed in 1.Groups Versus Roles

User Custom Field Value

Use the contents of a custom field of type User Picker or Multi User Picker. Such a field might be populated during a transition or by editing an issue.

Group Custom Field Value

Use the contents of a custom field of type Group Picker or Multi Group Picker. In a notification scheme, all the members of these groups will receive email, so be careful about how many users are involved.

Issue Type Schemes

A JIRA project’s issue type scheme controls which issue types are available for use in that project, as shown in Issue Type Scheme diagram. For instance, most JIRA projects that are not used by developers should not have the Bug issue type shown as a choice anywhere.

You can define an issue type scheme by going to Administration→Issues→Issue types and clicking on Issue type schemes. You can also set the default issue type that will be used when someone is creating an issue, and even change the order of issue types that the user will see.

Caution: Don’t use the Default Issue Type Scheme in your JIRA projects. Every new issue type that is created gets added to that scheme. So over time people using a project will see a wider and confusing choice of issue types to use. You should define an issue type scheme with a specific set of issue types and use that instead.

Changing any scheme for lots of projects is generally a long and repetitive task (see “Managing Projects”), but not for issue type schemes. The Associate link in the list of issue type schemes allows you to select multiple projects to change at once.

For more information, see the documentation at https://confluence.atlassian.com/display/JIRA/Associating+Field+Behavior+with+Issue+Types.


Notification Schemes

A notification scheme controls who receives what email about changes to JIRA issues. The default notification scheme sends emails to the reporter, assignee and watchers of an issue. Email messages are sent out from JIRA at most once per minute, and have to be sent to each individual user in turn to make sure that the permission scheme and issue security scheme are respected. So if a user doesn’t have permission to view an issue, they won’t receive email when the issue is changed.

Tip: It’s much easier to add changes to a notification scheme than to undo them. So always keep an unchanged copy of the default notification scheme as an easy way to undo any changes you make later on. The first copy of a default scheme is often named something like “My Company Default Notification Scheme.” I sometimes add a prefix DO NOT USE to the name of the default notification and permission schemes to make it obvious when the default schemes are still being used by a project.

JIRA uses an event-driven model for its notifications. When something such as a comment or a status change happens to a JIRA issue, a specific kind of Event is sent within JIRA. Another part of JIRA listens for events and acts on them when they are received. For example, when the JIRA system Mail Listener (Administration→System→Listeners) receives an event from an issue, it uses the notification scheme for the issue’s project to decide who should receive the email. This process is summarized in below Notification Scheme diagram. The actual set of users who are sent email for each different event can be defined in the various ways listed in “Adding Users to Schemes”.


You can define your own custom events at Administration→System→Advanced→ Events, and then change the post function in a workflow transition to make it send (fire) the new event. The new event will appear as a new row in all the notification schemes, and you can then define who should receive email when that transition takes place.

Note that you cannot configure the type of event sent for non-workflow issue operations such as Assign or Comment.

Tip: It’s important to avoid spamming your users with too much email, or they’ll just filter it and miss useful information. Be careful how many users you add to a notification scheme. You can also share an issue or list of issues via email directly using the Share button or by typing @userid to send email to the user userid.

For more information, see the documentation at http://confluence.atlassian.com/display/JIRA/Creating+a+Notification+Scheme.

Permission Schemes

A permission scheme is how you configure who is allowed to do what to a JIRA issue. There are a number of fine-grained permissions, such as Create Issues and Edit Issues. Each of these permissions has a set of users that are granted that permission, as shown in below Permission Scheme diagram. Just like notification schemes, this set of users can be configured in the various ways described in “Adding Users to Schemes”.


Just like other schemes, it’s much easier to make changes to a permission scheme than to undo them. Keep an unchanged copy of the default permission scheme as an easy way to undo any changes you make later on, or rename the default permission scheme with a prefix of DO NOT USE.

Once defined, such permissions are used by JIRA in various ways. The most obvious permissions do what they say (e.g., Link Issues controls whether a user can link one issue to another). Other permissions such as Transition Issue, Edit Issue, Resolve Issue and Close Issue can be used in workflow conditions to control who can change an issue’s status.

However, some of the permissions have effects that are not as obvious at first glance. For instance, when editing an issue, the Resolve Issue permission is needed to see the Fix Versions field, and the Schedule Issues permission is needed to see the Due Date field. If the user does not have those permissions, then these fields are hidden — not just grayed out — in an issue’s edit screen.

As a guideline when creating a new permission scheme, use project roles rather than groups for each permission. This makes the permission scheme useful in more projects. Administrators can usually be given all of the available permissions. To stop users viewing the project and all its issues, use the Browse Projects permission.

Caution: When you give a User Custom Field Value or Group Custom Field Value a permission, if the field is empty it behaves exactly like the Anyone permission. For example if you grant Edit permission to members of a Multi User Picker field, then when the field is empty that means anyone. I would expect that an empty field would mean no-one could edit the issue, but that is not the case (see JRA-26659).

For more information, see the documentation at http://confluence.atlassian.com/display/JIRA/Managing+Project+Permissions.

Issue Security Schemes

An issue security scheme controls who can view or edit a specific issue. In practice, most JIRA projects don’t need to have an Issue Security scheme defined, which is why this scheme is set to None by default when you create a new project.

Within an issue security scheme, you can define one or more security levels as shown in below Issue Security Scheme diagram. There is actually no hierarchy involved in these levels; they’re really just sets of users. Each security level can have users assigned to it in the same way that was described in “Adding Users to Schemes”. You can also choose one level to be a default security level for the scheme. Users can belong to more than one security level and will see issues that are in any of their levels as you would expect.


There is a system field in all issues named Security Level, which contains a list of all the different levels configured in the issue security scheme that are active for that issue’s project. Once a security level has been set in this field in an issue, then only users in that level can view or edit the issue. For other users, the issue is invisible and doesn’t appear in searches, or recent issue lists either. If you have permission to change the security level of an issue you won’t be allowed to change to a level you’re not in, so that you don’t create issues and then accidentally make them invisible to yourself.

Tip: To be able to set the Issue Security field in an issue to anything but the default value, you need to have the Set Issue Security permission (“Permission Schemes”). The default permission scheme does not give any user this permission. The project role Administrators is generally a good choice.

As an example of using an issue security scheme, if you are using JIRA as a help desk for external customers you can use an issue security scheme that only allows the Reporter and your staff to see each issue. That way, confidential information in a support request from one customer was not seen by another customer. JIRA Service Desk is a JIRA add-on from Atlassian that helps you configure JIRA for this use case, along with lots of other features.

For more information on issue security schemes, please see the documentation at https://confluence.atlassian.com/display/JIRA/Configuring+Issue-level+Security.

Schemes That Use Issue Types

Every JIRA project has three other schemes whose behavior depends upon the issue type of an issue. For example, the fields for a Bug may be quite different from the fields for a Task — this is defined in a field configuration scheme.

Tip: These schemes are more complex than schemes that don’t depend on the issue type, so they’re the schemes that usually confuse JIRA administrators. One way to keep the two kinds of schemes separate is to remember that only workflows, fields, and screens can depend on issue types.

The three schemes that use an issue’s issue type are:

Workflow Scheme

Which workflow is used for each issue type

Field Configuration Scheme

Which fields are part of each issue type

Issue Type Screen Scheme

Where the fields are displayed in an issue’s screen   

All of these schemes have the concept of a default. This is what is used if an issue type is not specifically mentioned in the scheme.

Tip: Different JIRA projects can all have totally different schemes, but to make maintenance easier you should always try to define schemes that can be reused by more than one project. This is discussed in “Working with Schemes”, where defining schemes for a project category is suggested.

Workflow Schemes

JIRA is designed to support different workflows. A workflow is a set of statuses and the transitions between them. A workflow scheme defines which workflow is used for each issue type, as shown in below Workflow Scheme diagram. A default workflow can also be chosen in a workflow scheme, and this workflow will be used for all issue types that aren’t specifically mentioned in the scheme.


Tip: The workflow scheme is an example of a common naming pattern for these three JIRA schemes: the Workflow Scheme is the mapping from an issue type to a Workflow. Similarly, the Field Configuration Scheme is the mapping from an issue type to a Field Configuration. However, the Issue Type Screen Scheme is a mapping from an issue type to a Screen Scheme.

One common practice is to start with a single workflow for the default and to then add workflows for specific issue types as necessary. For example, begin with a custom My Company Default Workflow, then add a Bug Workflow, a Task Workflow, and so on. This is covered in more detail in 5. Creating a workflow from scratch

For more information about Workflow Schemes, please see the documentation at http://confluence.atlassian.com/display/JIRA/Activating+Workflow.

Field Configuration Schemes

A field configuration scheme defines which Field Configuration is used for each issue type, as shown in below Field configuration scheme diagram. A default field configuration can also be set.


A Field Configuration (which is not a scheme) is a list of all the possible fields in any issue, with further configuration so that each field is valid and therefore shown, or invalid and hidden. For instance, the Fix Versions field is useful for a Bug but maybe not for a Task, so it could be configured as hidden in the Task Field Configuration.

When you edit a field configuration, you’ll notice that every possible field is listed, whether or not the field is restricted by issue type or project. This is the expected behavior.

Each field can also be marked as Required, which means that it can’t be left empty. JIRA will try to not allow you to make a field both required and hidden. If you make a field required, also check that it appears on the screens used for creating and editing an issue. The next time the issue with a new required field is edited, the field will be required before the changes can be saved.

You can change a field’s description in a field configuration, and also change the way that the contents of the field are displayed using various renderers. The renderers can show the contents of a field as raw text or can treat the text as wiki markup. If your users complain about JIRA mangling characters in the description or that they can’t use wiki markup such as {noformat}, check which renderer is being used. The wiki renderer is the default renderer for the system fields Description, Environment, and Comments.

A field’s description is also a convenient place to add JavaScript to tweak the behavior of a field. One example of this is shown in this jiradev blog post, though maintaining such JavaScript after JIRA upgrades can become a lot of work and is not recommended. A better approach is to use the Behaviours part of the ScriptRunner add-on.

For more information about Field Configuration Schemes, see the documentation at https://confluence.atlassian.com/display/JIRA/Associating+Field+Behavior+with+Issue+Types.

Issue Type Screen Schemes (ITSS)

A screen in JIRA is just a column of fields. The fields may be system fields such as Summary and Description or custom fields. JIRA does not allow you to use a grid of fields on a screen.

I’ve saved the most complex and confusing scheme for last. All the other JIRA schemes either control the behavior of an entire JIRA project (issue type, permission, notification, issue security schemes) or control the behavior per issue type. An Issue Type Screen Scheme (ITSS) controls how the fields are displayed for an issue, that is, which order the fields should appear on the screen.

An ITSS uses two levels of indirection instead of just one. This is shown in Screen scheme and Issue Type Screen Scheme.

Tip: Other things to note about this scheme are that an Issue Type Screen Scheme is entirely different from a Issue Type Scheme, and also that the phrase Screen Scheme is a great tongue-twister. Try it!

Recall that a field configuration scheme and its field configurations define the fields that are valid for a particular project and issue type. A field can be shown in a field configuration, but if it doesn’t appear on any screens, the only place you’ll see the field is when it is listed as a column to display in the Issue Navigator. Basically, screens control how these fields are viewed by a user.

On the first level of indirection we have Screen Schemes, which are not used directly by a JIRA project. Each Screen Scheme refers to up to three screens — one for creating an issue, one for viewing an issue, and one for editing an issue. This is so that you can have the same set of fields displayed in a different order on each screen, or not show certain fields during issue creation if they don’t make sense there.

I often define a screen scheme for a single issue type. For example, you might have a Bug Screen Scheme that defines how to display the fields for a Bug during creation, viewing, and editing an issue, as shown in Screen scheme diagram.

At the second level of indirection, an ITSS defines which screen scheme should be used for each issue type. A default screen scheme can also be chosen in an ITSS.

To summarize, an ITSS tells JIRA which screen scheme should be used for a particular issue type in a project. Then a screen scheme tells JIRA which screen should be used for creating, viewing, or editing an issue.

For more information, see the online documentation at https://confluence.atlassian.com/display/JIRA/Associating +Field+Behavior+with+Issue+Types.



Working with Schemes

Even once you understand what the seven different schemes do in JIRA, they will still need to be maintained. Every time that someone asks you to add a new field just for them, you will want to consider the effects of that change on everyone else’s issues. Chapter 4 looks at how to make sure this happens in a controlled way, and the rest of this chapter covers some of the details of making this possible.

There is a necessary balance between the number of schemes and what they all do. I try to have only as many schemes as are needed by the different communities using a particular JIRA instance. You can configure JIRA so that every project has a complete set of schemes, but that could make for a lot of maintenance work later on. Also, if every group in an organization has a different process then working together is going to be that much harder.

Tip: The most important thing to do before changing schemes is to create a backup of your JIRA data. If possible, test all scheme changes on a development or staging JIRA server. Even better, do both. All JIRA licenses can be used in one production and one development instance. You can also download a Developer license for this purpose from https://my.atlassian.com under your main license.

Choosing Schemes

Rather than allowing users to request many small changes to the schemes for their JIRA project, a better approach is define a set of predefined schemes and ask them to choose one from each. This supermarket approach also makes it easier for users to describe what they need as a change from something more commonly used.

For instance, some common workflows that users can choose from might be defined as:

Standard Simple Workflow

Open, In Progress, Closed

Standard Testing Workflow

Open, In Progress, Ready for Testing, Closed

Standard Approval Workflow

Open, Approved, In Progress, Closed

Standard Approval and Testing Workflow

Open, Approved, In Progress, Ready for Testing, Closed

Documenting Schemes

Each scheme has a name and an optional description. What are good names for schemes? Obviously it’s a personal preference, but I usually name my schemes using a Project Category or Issue Type name, and then the scheme type.

For example, I might have a project category named Customer Support for all of the Customer Support department’s JIRA projects. For an ITSS used by all those projects, I would use a name such as Customer Support ITSS — and then this scheme would refer to screen schemes with names like Support Request Screen scheme and Training Screen scheme, using the issue type name as part of each screen scheme name.

I occasionally use the scheme’s description field to record the latest change at the beginning, just after the summary of what a screen is for. The maximum length of the description varies according to the underlying database, but you can assume at least 4000 characters.

Sometimes I also add version numbers to a scheme’s description or name, and update these when I change the scheme. This is useful, but I recommend adding the date as well, since you may end up with branched schemes. Workflows record the date and user who last changed them in their XML definition, and changes to other schemes appear in the Audit Log at Administration→System→Audit Log.

If the JIRA configuration is particularly complicated, then I may create a document describing the intended purpose of each scheme and the changes that have been made to it over time. This helps me when I’m trying to work out the effects of a proposed change to a particular scheme. I also add JIRA issue keys to scheme descriptions, where the issue contains the request for the change to the scheme.

Debugging Schemes

Sometimes you have to try to understand how a JIRA instance has been configured by another person whose documentation and naming of schemes was perhaps minimal. This usually happens when someone asks you something like why can’t I edit this field anymore?

This type of task has become easier since JIRA 5.2, thanks to three new features for administrators in the bundled JIRA Admin Helper add-on. When creating or editing an issue, there is a link under the Configure Fields menu to Where is my field?. This lets you specify a field by name, and then the various schemes are checked to see what is affecting that field. The other two features are the Permission Helper and Notification Helper, which help debug why a user does not have a certain permission or is not receiving notifications. These helpers are both available from the Admin button when viewing an issue. These helpers are the best place to start when debugging problems.

If you’re not using the helpers, then the first thing to do is to see if the names of the various schemes bear any resemblance to what they are actually used for. Just because a scheme is called Bug Workflow scheme doesn’t mean that it’s only (or even) being used for bugs. The fastest way to get this information is to go to each scheme administration page and look at the projects that each scheme is assigned to. With luck, you’ll spot an obvious pattern. If the scheme names don’t end in scheme, consider adding that to make it clear that it’s a workflow scheme, not a workflow (for example).

You may also want to compare two schemes to see how they differ. Up until JIRA 6.3 there is a tool for comparing permission and notification schemes available at Administration→System→Scheme Tools. For other scheme types, I find that opening each scheme in a separate tab in my browser allows me to compare them reasonably well side-by-side.

If you decide to do a wholesale renaming of the schemes in your JIRA instance, then I recommend making a backup (of course) and then renaming just one collection of similar projects at a time (such as those with the same project category). Renaming old scheme names with an obvious prefix such as OLD can also help you spot the cases that you’ve missed. Since you’ve got a backup, you can also consider deleting inactive schemes.

Once you have a better understanding of which schemes exist and what they’re used for, you can debug the original problem. My process for debugging most scheme problems is as follows:

1. Obtain a specific issue key where the problem can be reproduced.

2. If you can, get a sense of when the problem began, since it may be related to some other scheme change you’ve just made.

3. Note the project, issue type, and status of the issue, and also whether the problem occurs during creating, viewing, or editing the issue.

4. Go to Administration→Projects and click on the project name.

5. Note the names of the seven schemes that are currently being used by this project.

6. For each scheme in turn, view the details of the individual scheme and see what applies for the specific issue type. Note this information down as well.

7. If the problem is about a field, then view the appropriate field configuration and the create, edit, or view screen. The field may be hidden, required, not present on the screen, or present but in another screen tab.
A custom field may also be restricted in the custom field context (Administration→Issues→Custom fields) to only certain issue types or projects.

Some fields are only visible if the user has the correct permission, so an administrator may not have the same problem as a user. Try creating a user account with the same groups and project roles as the user reporting the problem. Alternatively, log in as the user who reported the problem using either the SU for JIRA or the ScriptRunner add-ons.

8. If the problem is about a workflow action, check the specific transition’s conditions and validators first.

9. If the problem seems related to some other scheme, then drill down into that scheme’s definition, bearing in mind the issue type and where the problem was seen.

10. Once you have identified the root cause and fixed it, revert the fix and confirm that the same problem reappears, then fix it again. This confirms that your analysis and changes are correct. You should also check other schemes where the same problem may also exist.

Tip: Don’t make any change to schemes before making a backup. Ideally, you should debug and fix the problem in a development instance of JIRA before touching the production JIRA.

The Future of Schemes

Schemes have always been a powerful and potentially confusing part of JIRA. JIRA versions since 4.4 contain much improved project administration screens that show more information in one place about how each JIRA project is configured. The underlying way that schemes work hasn’t changed since before JIRA 4.0, however.

With the release of JIRA 6.4, there is an increased emphasis on using project templates. A project template allows you to choose a project type for a JIRA project on creation such as SCRUM Agile, and JIRA creates copies of some standard template schemes for the new project. This leads to each JIRA project having its own seven schemes which makes it easier to change one project and not accidentally affect any other projects. However it does mean that there will be many more schemes for administrators to manage: possibly seven for each project. For large JIRA instances I recommend choosing the Classic JIRA project which allows you to set the specific schemes.

As an aside, he new Where is my field? features are also typical of how Atlassian makes medium-to-large feature changes to JIRA. First an add-on is developed that offers the functionality in parallel to the existing functionality, but in a harmless way. Feedback and fixes occur rapidly and then the add-on (jira-admin-helper-plugin) is bundled with the shipped JIRA package (5.2 in this case). Many of the core features of JIRA are in fact add-ons when you look at their source code. Such add-ons can be disabled at Administration→Add-ons, System, but you should test carefully before doing this in production.

4. JIRA as a Platform


A common request that JIRA administrators receive is to use JIRA for more than its current purpose. The typical case is that someone in one group tells a different group that you can do that with JIRA, and it’s already installed. After all, a JIRA project is like a spreadsheet with a line for each JIRA issue and a column for each field. It’s true that JIRA can be used to track many different kinds of issues, and Chapter 3 described how to configure JIRA schemes to do just that.

This idea is, in effect, using JIRA as a platform for different web applications or vertical solutions for each group of users. There might be one such web application for Engineering JIRA projects, one for Customer Support JIRA projects, and so on. Using JIRA as a platform in this way is part of how it is designed to be used, but it does need a consistent configuration approach to be successful. This is particularly true if different groups don’t want to see any part of other groups in the same JIRA instance.

However there isn’t much documentation on how to do this in a consistent manner. This chapter describes one way to do this using a worked example, and then summarizes this in the section “Summary”.

What Can Be Configured

For each pair of a JIRA project and issue type, we can change the following:

  • Which system and custom fields an issue can use, and whether they are required or not
  • The order in which custom fields appear on an issue screen
  • The workflow for an issue, including the statuses available in an issue

On a per-project basis, we can also configure:

  • The issue types used in the project
  • The components and versions available for an issue
  • The permissions for what a user can do with an issue, including even knowing the issue exists
  • Who can access the whole project
  • Who receives email about changes to issues

What Is Configured System-Wide

Some configurations for JIRA are system-wide and affect all the users of a JIRA instance. Such configurations are not part of using JIRA as a platform, but they may have a bearing in discussions between groups because changing them affects everyone. Some of the more common ones that I encounter when discussing this topic are:

  • The logo and colors used by JIRA, though each JIRA project can have its own avatar or logo
  • Names of system fields; any translation of a field name or status applies everywhere (Administration→Issue types, Translate)
  • Whether unassigned issues are allowed or not (though if set to allowed globally this can then be set per project)
  • The maximum attachment size, which is set to 10MB by default.
  • Priorities; all issues use the same list of priorities in the system Priority field.
  • Resolutions; all issues use the same list of resolutions in the Resolution field (this is most commonly seen during a workflow transition where they can be restricted using Workflow Properties).

For the last two, there is the top-voted Suggestion for JIRA (JRA-3821) to make priorities and resolutions fully configurable per project and issue type.

All the other system-wide configurations, such as enabling or disabling voting, can be found at Administration→System, Settings.

Worked Example: Configuring JIRA for a New Department

In this example, we’re going to configure JIRA for use by an imaginary accounting department. The people in Accounting may have decided to store invoices in JIRA rather than using some other dedicated and perhaps much more expensive system.

The information stored for Accounting is totally different from what appears in a Bug issue type, and includes a custom field named Amount. Only certain people can see the accounting information in JIRA, and some of this information is still further restricted. The accounting department also requested that they should see nothing about Engineering projects, since that was just unnecessary clutter on their screens.

The first thing to do is to take a backup of your JIRA data, do this work on a development JIRA instance, or both. The next things to do are:

  1. Create a new Project Category for the accounting department, e.g., Accounts. Some scheme names will use this word as a prefix, so make sure that the category name is something obviously unique, meaningful and brief.
  2. Create a new issue type for that department’s issues, for example, Invoice. This is because we know we will have a different set of fields for accounts issues, and possibly a different workflow. Add a description of what kind of information it contains. Other scheme names will also use this word as a prefix, so make it meaningful.
  3. Create a test project with a project key such as ACCTEST. JIRA project keys should generally be as brief as possible since everyone types them frequently. 1 The project name can be more descriptive than the project key. The project key and project name can be changed later on, with some restrictions such as not being able to reuse the old project key. Once this project’s configuration is complete, you can create more JIRA projects and configure all of them in the same way.

Basic JIRA Project Setup

The next stage is to do the simplest part of the job first. Edit the project configuration with Administration→Projects, then click on the project name ACCTEST (not on Edit).

Project Lead

Set the Project Lead for the project. The project lead is the person who is usually contacted to confirm future requests for changes to the project. This user will be also be the default assignee for issues in the project. With the default notification scheme, email about new issues is sent to the assignee, reporter, and watchers, so the project lead should expect to receive email about issues that were not assigned to anyone else.

Project Category

Set the Project Category for the project to the new Accounts category that we just created. Any other future accounting projects, such as ACCMAIN or ACCSUB, will also use this category.

Project Avatar

It’s also a nice touch to set an avatar (a small logo) for the project to make it easy for people to quickly distinguish it from other projects. You can upload your own images. One possible idea is to use the same image for all projects in the same category for branding.

Notification Scheme

Open a new browser tab and create a new notification scheme named Accounts Notification scheme. Copying the Default Notification Scheme and modifying the copy is the most common way to do this. The name of this new scheme indicates what the scheme is (a notification scheme) and which category of JIRA projects it is intended for (Accounts).

In your original browser tab, set the notification scheme for the project to Accounts Notification scheme, using Actions→Use a different scheme.

Permission Scheme

Create a new permission scheme named Accounts Permission scheme. Again, copying the Default Permission Scheme and modifying the copy is the standard way to do this.

In this case, there should be no need to change any of the permissions except for one. The Set Issue Security permission controls who can change an issue’s security level (see “Issue Security Schemes”). Add the Administrators role to this permission. As discussed in Chapter 1, we want to use a project role rather than a group here.

Set the permission scheme for the project to the new permission scheme, Accounts Permission scheme.

Groups and Roles

Define a new JIRA group named Accounting that contains all the users who should be able to see issues in the Accounts projects. If you’re lucky, the group may already exist in your local LDAP user directory and have already been imported into JIRA.

In the project configuration page, click on View Project Roles and then:

  • Delete the jira-users group from the Users role and add the Accounting group. Now only accounting can see the new project.
  • Delete the jira-developers group from the Developers role and add the Accounting group.
  • Add the project lead as a user to the Administrators role.

Hiding Projects from Users

At this point only Accounting users can see the Accounting projects, which is as intended, but they can still see Engineering projects. This is because all of those projects are likely using the jira-users group in their Users role.

To change this, we need to step back and look at how we are defining the Users role for all of the JIRA projects. The Users role is what usually controls who can access a project. There is no way to explicitly block access to a project for a specific group in JIRA. So one approach I sometimes take is that all users should be members of the default jira-users group, but also members of a group that controls which projects they can see.

So you might have a mycompany-staff group and a contractors group and add everyone to jira-users so they can log in, but change the groups in the Users role according to whether contractors have access to a particular project.

In this case I would define a group Engineering, add all the engineers to it, and then change all the Engineering projects’ Users and Developers roles to use this group instead of jira-users.

Now the users in the Accounting group won’t have access to the Engineering projects, and those projects won’t clutter up JIRA for the Accounting users.

Issue Security Scheme

Create a new issue security scheme named Accounts Issue Security scheme:

  • Add a security level named All Accounting and add the Accounts group to it. Make this level the default one.
  • Add another security level named Confidential Accounting and add only a few of the accounting users who are permitted to see the more confidential accounting information.

Set the issue security scheme for the project to the new issue security scheme, Accounts Issue Security scheme. Now when an issue has a security level of Confidential Accounting only certain accounting users will be aware the issue exists.

Advanced Project Setup

Now we need to define the more complex schemes and configure the ACCTEST project to use them. These schemes are:

1) Issue Type scheme

2) Workflow scheme

3) Field Configuration scheme

4) Issue Type Screen scheme, which uses at least one Screen scheme

For most of this work, the easiest direction to work is bottom up. So create the issue type Invoice before creating an issue type scheme that uses it. And create a workflow or screen before creating the schemes that use them.

Issue Type Scheme

An Issue Type Scheme controls which issue types can be used in a project.

Under Administration→Issues, click on Issue type schemes and add a new issue type scheme named Accounts Issue Type scheme. Then:

  • Add the main accounting issue type Invoice as the default issue type.
  • Add other issue types, such as Task and Improvement, only if they will be used by the new department. You can reorder them to change the order in which they appear when a user is creating an issue. The default issue type will be shown as selected at that time.

Now set the issue type scheme for the ACCTEST project to the new issue type scheme, Accounts Issue Type scheme.

Workflow Scheme

Create a new workflow for the Invoice issue type named Invoice Workflow and add the desired statuses and transitions to the new workflow. See Chapter 5 for more details on how to create a new workflow.

Create a workflow scheme named Accounts Workflow scheme and configure it to use the new workflow for the Invoice issue type. For any other issue types that are allowed in the project, add their workflow mappings in Accounts Workflow scheme. Before JIRA 5.2 if a workflow is not specified for Unassigned Types, then the default read-only JIRA workflow will be used even though the field is shown as blank. More recent versions of JIRA show the default workflow more clearly.

Set the workflow scheme for the ACCTEST project to be the new workflow scheme, Accounts Workflow scheme.

Field Configuration Scheme

A field configuration controls which fields are part of an issue type, e.g., what data is part of an Invoice.

Create a new field configuration named Invoice Field Configuration. This is not a scheme. Don’t hide any fields here yet since we’ll use screens to effectively do that later on. If a particular field is required in an Invoice issue, mark it as such here. I recommend making fields required only at the final stages of creating new schemes since it make testing harder.

Create a new field configuration scheme named Accounts Field Configuration scheme, and configure this new field configuration scheme to use the Invoice Field Configuration for the Invoice issue type.

Now set the field configuration scheme for the ACCTEST project to the new field configuration scheme, Accounts Field Configuration scheme.

Screen Scheme

Screens control whether a field appears in an issue to a user, and also the order in which the fields appear. Screen Schemes choose which screen is used to create, edit, or view an issue.

Create a screen named Invoice Screen. This screen should have all the fields that are wanted in the Invoice issue type, including the custom field Amount (after it is defined in “Adding a Custom Field”). In some versions of JIRA you can add more than one field at once, and then reorder them in one go using Move to Position.

Tip: I recommend starting with just one screen and using it for all three of the screens (Create, View, and Edit). Later on, you can copy and edit the screen and change the screen scheme without having to change the project settings. A good reason to have different screens is that some fields may not be known when an issue is created, or there might be fields that are not directly editable by users so should not appear on the edit screen. Another good reason is that the simpler a Create screen is, the easier it is for people to create new issues.

Create a new screen scheme named Invoice Screen scheme and configure the Create, Edit, and View issue screens to all be the same screen for now. This can also be done by changing the default to use just one screen.

Issue Type Screen Scheme (ITSS)

An Issue Type Screen Scheme (ITSS) ensures that the right sets of screens are used for each issue type.

Create a new ITSS named Accounts ITSS and configure the default screen scheme to be the Invoice Screen scheme defined in “Screen Scheme”. If there are other issue types, then add mappings for each one to an appropriate screen scheme. For more information about what an ITSS does, see the section “Issue Type Screen Schemes (ITSS)”.

Now set the issue type screen scheme for the ACCTEST project to the new issue type screen scheme, Accounts ITSS.

Adding a Custom Field

Adding a custom field is the real test of all this work, since you’ll probably do it more than once for all the JIRA projects in a project category. The custom field for this example is named Amount.

Define the new custom field with Administration→Issues→Custom fields and then the Add Custom Field link or button. This custom field is likely a Number Field. Give the field a name (Amount) and a description. Custom field names should only use ASCII characters and should be unique to avoid confusion. Since the description appears just below the field in the issue screens, make it useful for people by describing what they are expected to enter, perhaps along with an example value. For example, The dollar amount owed, with no dollar sign, e.g., “15.95.”

Since the accounting department will want to be able to search on this field, make sure that the Search Template value is set to something other than None.

Now restrict the custom field to just the applicable issue types that uses it. For this example, that’s just the Invoice issue type.

Tip: Don’t restrict the custom field to a project if you can avoid it, because then you’ll have to come back and do that for every JIRA project that you add to the Accounts category. If you have lots of custom fields or projects, that will take you a long time to do manually.

Go to Administration→Issues→Screens and add the new custom field to the Invoice Screen (or to the Invoice Create, Invoice View, and Invoice Edit screens if they were defined in “Screen Scheme”). To ensure that this new field doesn’t interfere with other projects and their issues, don’t add the new field to any other screens, particularly not the Default screen.

This is the end of the worked example. Note that when you’re looking for the Amount field to use in a simple search in the Issue Navigator, you will have to choose a project and an issue type in order for that the custom field to appear as a choice.

Tip: Do I really have to reindex after modifying a custom field? The answer is only if the field has existing data. New fields will have their data added to the index used for searching in JIRA when issues are edited. If a custom field is only used in one project then you can reindex just that project.

Prior to JIRA 5.2 reindexing used to lock all users out of JIRA until it was finished, so administrators of large JIRA instances had to wait until a convenient time occurred. Now with background indexing users can continue to use JIRA during reindexing. I still recommend reindexing at a time of low load since the process can take a long time in large JIRA instances. Until you do reindex, all JIRA administrators see a reminder about a reindex being needed in the Administration screens. Don’t just reindex without thinking carefully!

Names Used in the Example

This section lists all the different names used in the example above in one convenient place:


A project category


The keys of three JIRA projects in the Accounts project category

Accounting, Engineering

Groups of JIRA users

Users, Developers

The standard JIRA project roles


A new issue type


A custom field in Invoice issues

The seven schemes and the things they control are:

Accounts Notification scheme

The notification scheme for Accounts JIRA projects

Accounts Permission scheme

The permission scheme for Accounts JIRA projects

Accounts Issue Type scheme

The issue type scheme for Accounts JIRA projects

  • Invoice — a new issue type used in the ACCTEST JIRA project
  • Task, Improvement — existing issue types

Accounts Issue Security scheme

The issue security scheme for Accounts JIRA projects

  • All Accounting — a security level in the issue security scheme
  • Confidential Accounting — another security level in the issue security scheme

Accounts Workflow scheme

The workflow scheme for Accounts JIRA projects

  • Invoice Workflow — a custom workflow for the Invoice issue type

Accounts Field Configuration scheme

The field configuration scheme for Accounts JIRA projects

  • Invoice Field Configuration — the field configuration for the Invoice issue type

Accounts ITSS

The issue type screen scheme for Accounts JIRA projects

  • Invoice Screen scheme — the screen scheme for the Invoice issue type
  • Invoice Screen — the screen used for the Invoice issue type by the Invoice Screen scheme

5. Creating a Workflow from Scratch


Workflows are the different statuses that an issue can have, together with the transitions between the statuses. For instance, there could be a status named Open, with transitions leading to the Resolved and Closed statuses.

Tip: The word status is preferred over using state in the JIRA documentation (and also in this book), but in practice they seem to both be used interchangeably. One useful notion is that a status is a summary of states. For example, someone’s medical status could be summarized as normal based on the state of their heart, the state of their liver, and so on. In a similar way, a JIRA status is a summary of what is going on in an issue

Transitions in JIRA workflows usually go from one status to another status. However you can also define shared transitions (also known as common transitions) which go from many statuses to one status. There are also global transitions which go from every status to one status. Finally, self transitions are transitions that return to the same status they started from.

JIRA workflow transitions can also optionally have extra triggers, conditions, validators, and extra post functions:

  • Triggers make the transition occur when an external event is received. This can be used for integrating JIRA with other systems.
  • Conditions restrict who can see that a transition exists.
  • Validators check the values that were entered during a transition. JIRA has almost no useful validators installed, but many more can be found in the recommended JIRA Suite Utilities (JSU) add-on.
  • Post functions make changes after a transition has taken place and send events to say what just happened. JIRA automatically adds certain post functions to every transition.

The statuses and transitions of the default JIRA workflow are shown in Figure 5-1, which is taken from http://confluence.atlassian.com/display/JIRA/What+is+Workflow and is what is seen in the Workflow Designer. The expected sequence over time goes from Open to In Progress to Resolved and Closed. Custom workflow diagrams can be customized in the workflow designer to make the expected flow more obvious.


  Figure 5-1. The default JIRA workflow

One of the major attractions of JIRA is the ability to customize workflows, including adding new statuses, new transitions, and making other things happen as part of transitions. This chapter describes how to create such a JIRA workflow from scratch.

Why would you want to do that? JIRA comes with one default workflow. You could create your custom workflow by simply copying and modifying the default workflow (the original is not editable). However, I’ve found that doing this often leads to various maintenance problems including:

  • The names of your statuses may not be the same as the ones in the default JIRA workflow, and renaming them doesn’t completely hide the old names everywhere in JIRA.
  • The JIRA Closed status, by default, has a property that does not allow issues in that status to be edited (jira.issue.editable). It’s easy to forget that the property is there until you want to bulk change many issues, some of which may be in the Closed status.
  • The Start Progress transition auto-assigns the issue to the current user if permitted. This is often not what is expected.
  • The Resolved status has a value for the system field Resolution set, even though it is not a final status. The resulting strikethrough on an issue key can be confusing for users who expect that only for Closed issues
  • Some of the default JIRA transitions are common or shared transitions, meaning that changing them in one place also changes them everywhere else they are used in a workflow. This may or may not be what is wanted.

In general I recommend creating your own workflows from scratch rather than copying and modifying the default JIRA workflow.

Designing a Workflow

The hardest part about designing workflows is getting everyone to agree on them in the first place. After all the smoke and noise is over, all that is really needed is:

  • The issue types that are expected to use this workflow.
  • A list of the status names and their descriptions.
  • A list of the transitions start and end statuses, along with transition names and descriptions.
  • What, if any, information needs to be entered during each transition. Such information may be needed for restrictions of who can see or execute a transition. This information is used by the optional conditions and validators.
  • Any changes to an issue other than status as part each transition. These changes are typically made using post functions.
  • Any integration of the workflow with other Atlassian products using triggers.

Both statuses and transition names should be as brief, meaningful, and reusable as possible.

Some general guidelines for designing workflows that I find helpful are:

More than a dozen statuses is a large workflow

Only use statuses that will be useful in your key reports. More statuses means more work maintaining the transitions between them all.

Use the past tense of verbs for statuses

For example Closed, instead of Closing or To Be Closed. The name of the status should describe what has already happened to an issue that has that status.

Use the imperative tense for transitions into a status

For example Close, instead of Closing or To Be Closed. The name of the transition should describe you want to do to the issue. You can also be explicit and name each transition To XYZ, where XYZ is the name of the destination status. If there is only one transition between each status, you can even use the destination status name alone, though adding a good description for each transition is then more important.

Don’t use transition names that are existing action names

 There is a standard issue action called Assign that assigns an issue to a different user. If you give a transition that same name, then your users will see two tabs on an issue, both named Assign, that do very different things. Avoid confusing your users and don’t use Assign as a transition name.

Fewer statuses is better

Use the smallest number of statuses possible. More than about ten suggests you may have overcomplicated the workflow, which in turn means that other people will have a hard time using it. You may need to have more than one issue type and a workflow for each issue type.One way to decide whether you need a status is to consider whether any report that actually matters would use it, and whether that same information can perhaps be provided by JIRA in a different way.

Clear descriptions

Make sure that you have a brief description of the purpose of every status and transition, and enter it the JIRA workflow. This will appear as a floating tooltip on transitions to guide confused users.

Put statuses and transitions in their expected order

Whenever you list the statuses during design or are adding them to a JIRA workflow, do so in the order that you expect them to appear most of the time, in a vertical stack. The use of a vertical stack makes the expected path through a workflow clearer. This is particularly true for earlier versions of JIRA or when using the text-based workflow editor. Similarly, add the most common transition first in any list of transitions from a status. An alternative way to change the order that transitions appear using transition properties such as opsbar-sequence is described at https://confluence.atlassian.com/display/JIRA/Workflow+Properties. If you’re not using JIRA Cloud you can even export the workflow XML, change the order of the transitions and reimport the modified XML (in a test JIRA first).

Workflow screens

A transition can either happen immediately, or a transition screen with various fields on it can be shown during the transition. Transition screens also have a place to leave a comment about why the transition was made. JIRA provides two standard screens for this (Resolve Issue screen and Workflow screen), but if there are fields that you want to allow to be edited during a transition, then you can define your own screens. Just don’t use the Default screen as a transition screen, because when users change statuses they’ll feel rather overwhelmed by seeing all of the fields in the issue. A good transition screen presents the user with the fields that are most commonly changed during a particular transition.

Which statuses are resolved?

Decide which statuses should always have a value set in the system Resolution field (Chapter 2). Make sure that all transitions from a non-resolved status to a resolved status set the Resolution, and that all transitions from resolved to non-resolved statuses clear the resolution. Otherwise you’ll see reopened issues with a strikethrough in their issue keys.

Allow for mistakes: no status is final

Every status should have a transition to another status: otherwise, it becomes a final status. Final statuses are fine until someone accidentally moves an issue into one and then can’t undo their mistake. You can always allow only administrators to execute a transition if you want to make it more difficult to change a status.

The workflow shown in Figure 5-2 is an improved version of Figure 5-1. It was drawn with the Gliffy drawing tool, which is available as a add-on for both JIRA and Confluence. The points to notice are that the most common path through the workflow is a vertical stack of statuses. Other less common statuses such as Reopened are off to the side. Statuses that expect to have a resolution set are shown with a heavier border (Resolved, Closed). If I were further refining this workflow, I would remove the Reopened status since the same information about whether an issue has been reopened can be gathered with the JQL was operator, e.g., status = Open and status was Closed.

For many workflows, I find that thinking about the intended assignee and their team for each status is helpful when designing the workflow. For instance, a bug might have been assigned to a default user for a project, then to a developer, then to QA for testing, and finally assigned to someone in Operations for deployment as part of a release. I try to consider what each person will want to do most frequently with the issue.


  Figure 5-2. An Improved Default JIRA workflow

JIRA Agile and Workflows

JIRA Agile, formerly known as GreenHopper, is a popular JIRA add-on by Atlassian that allows you to manage issues in a more agile way. This means Kanban, Scrum, sprints, burndown charts, and a whiteboard-like active sprints board where you can drag issues from status to status. You don’t even have to be working in an agile way to appreciate it. So it’s very popular indeed.

JIRA Agile cards are simply JIRA issues displayed differently, so of course each card uses a JIRA workflow. The difference is that JIRA Agile lets you assign multiple statuses to columns on the Active Sprints (Work) board. For example, the column named To Do could have issues in the Open and Reopened statuses. When designing a workflow for use in a JIRA Agile board, there are a few points to remember.


Define the names for your JIRA Agile columns and decide which JIRA statuses should be mapped to each column. You can have statuses that don’t map to any of your columns, and in fact this is sometimes a useful way to keep issues from appearing on a board.


If you want to be able to drag an issue from any column to any other column, you will need to have a transition from every status to every other status. A regular JIRA workflow is often shaped like a ladder or diagonal, but a workflow for use in JIRA Agile is more like a fully connected circle. You’ll at least need a transition to one of the statuses in every column to allow cards to be dragged. This is an O(N2) number of transitions. A better approach is to define a common transition for entering each status. That way you only have to define as many as the number of statuses in the workflow. The Agile Simplified workflows that JIRA Agile can create are just the statuses with a global transition to every status. This means that you’ll see transitions back to the same status in every issue which can confuse some users. You also need to check that the system Resolution field is set properly in these generated workflows. You can add multiple conditions to a transition and even have levels of combinations of them. However I recommend avoiding complicated conditions that restrict who can change an issue’s status, or you’ll have users who are frustrated that they can drag issues to some columns but not other columns.

Transition Screens

Many people like to avoid transition screens with JIRA Agile. When they’re dragging issues from one screen to another, they don’t want to have pop-ups interrupting them. This is fine except for transitions that need to set a resolution. The resolution can be set in a post function, but which resolution to choose? I recommend choosing the most frequent resolution, then add another transition between the same two statuses with a transition screen that lets you choose a resolution. When the issue is dragged to a column where the resolution should be set, two small areas will appear named after each transition. One could be Completed since it sets the resolution with no pop-up screen, and the other could be named something such as Close – Other.


People drag issues around on the work board without realizing that they are sending out email about status changes. You may want to use a custom event for some transitions and prevent the notification scheme from sending out email for that event.

Implementing a Workflow

Once you have the names and descriptions of the statuses and transitions, you can create the new workflow at Administration→Issues→Workflows. For ideas on naming the workflow, see the sections “Workflow Schemes” and “Workflow Scheme”.

JIRA has included some kind of graphical workflow designer since version 4.4. To use the text-based editor in JIRA 5 you have to click on the column that shows the number of steps in a workflow or the Text link. Since JIRA 6, there is a more obvious Text button to allow users to work with the text editor.

The graphical editor is an improvement on the original workflow editor, which had also some limitations about what it could do with draft workflows (see “Further Reading”). I confess I still create and edit workflows using the original text editor though, perhaps from long familiarity. However there’s no other way than the Workflow Designer to produce workflow diagrams.

First, create new statuses as necessary at Administration→Issues→Statuses, or in the graphical designer Statuses area.

If you are not using the graphical workflow designer, then add the statuses to the workflow in the expected order of their most frequent use.

Caution: A workflow is actually made up of steps, and each step has just one status associated with it. For simplicity make the step names the same as the status names — otherwise, your users will see discontinuities in a few places in JIRA.

JIRA will have added a first step named Open. After you add other steps you will be able to make any one of them your initial status, and can then delete the original step that JIRA added for you. To change the initial status, click on the Open step name, then the Create Issue transition, then Edit, and finally change the Destination Step to the new initial status.

Next, add the transitions away from the first status, also in their expected order of use.

For each transition, after you’ve entered the name and description, check which triggers, conditions, validators, and post functions are wanted, and add them. If you see a number after a transition name, that’s a unique ID for that transition. This can help to see which transitions are shared (common) or global

I recommend changing the event fired in the post function from Generic Event to something more informative, even if it’s only Issue Updated. This can also be used reduce the amount of email sent when an issue is updated as described in “Workflows and Events”.

Check that there is a Transition permission condition. This controls who can change the status of an issue. Earlier versions of JIRA didn’t restrict this except by adding a condition to each transition. In that case I recommend adding a Permission Condition to check for Edit permission and make this behave as expected. Adding such a condition also makes it easier to make a JIRA project properly read-only.

Tip: You are allowed to have self transitions back to the same status if you want to. This is one way to narrowly restrict what is changed in an issue, and is used in the section “Resolution”.

The default JIRA workflow has some triggers, conditions, validators, and post functions that are worth knowing about:

  • The initial Create Issue transition into Open has a validator to check that the user has the Create Issues permission.
  • Transitions have a condition that checks for the Transition Issues permission.
  • The Start Progress transition has a condition to check that the current user is the issue’s assignee. Other users won’t see this transition as a choice. Other variants of the default workflow assign the issue to the current user during this transition.
  • The Closed status has the jira.issue.editable property set to false which means that issues with this status can’t be edited.
  • Many statuses and transitions have a property jira.i18n.title which is used to get the actual name. If you’re having problems renaming something, look for this property, and either delete it or translate the status’ name at Administration→Issues→Statuses.

There are five post functions that are added by default to new transitions, but only one of these is editable: Fire Generic Event. Events are discussed later in “Workflows and Events”.

Deploying and Testing a Workflow

When a workflow is created from scratch, there is of course no project or issue type that is using it, so it’s inactive. Recent versions of JIRA display workflows in active and inactive sections, and the inactive section is not expanded. If you can’t find the workflow you just created, expand the inactive section before searching for it on your browser page.

The first step towards making a workflow active is to create a workflow scheme to define which issue types use each workflow. For instance, tasks (issues with issue type Task) could have a different workflow from bugs, which have an issue type of Bug. See “Workflow Scheme” for details on a recommended way to do this.

Once you have a workflow scheme that refers to the new workflow, you can edit a JIRA project to use the workflow scheme (go to Administration→Projects and click on the project name). Then go to Workflows and click Switch Scheme.

Now when you create a new issue of the specified type in that project, you should see that the status of the issue is the one that you chose as the initial status. The available workflow choices for the issue should be the transitions that you defined as possible from that status. The permission View Read-only Workflow allows people to see an image of each issue’s workflow. This is so helpful that it’s worth adjusting the workflow diagram in the graphical editor to make it clearer.

To test the workflow, execute the transitions between all the statuses, checking for usability errors as well as any actual failures or error messages in the JIRA log files. Check that any custom triggers, conditions, validators, or post functions behave as expected. Manually testing all the different combinations of transitions and user permissions is only really possible for small to medium-sized workflows.

To make a change to a workflow once it is in use and active, you have to create a draft of the workflow (the graphical designer will do this automatically), edit the draft, and finally publish the draft. The option of saving a copy of the original workflow is offered when the workflow is published, and can be useful if version numbers are added to the workflow name. However, I generally find it leads to too many copies of old workflows, so I don’t use it very often.

Some changes to a workflow can’t be done by creating a draft. For the following changes you have to create a copy of the workflow, edit the inactive copy and then change the workflow scheme to use the copy.

  • A workflow’s name cannot be changed, though the description can.
  • Statuses cannot be removed.
  • A status can only have new transitions added from it if it already has at least one outgoing transition. So dead-end statuses cannot have an outgoing transition added.
  • Changing the name of a step used for a status. Generally the step name should be the same as the status name.

One thing that’s currently missing in JIRA is a way to compare two versions of the same workflow. When I really want to be sure of what has changed, I export the workflow’s XML before and after the change and then compare the two files using a diff tool, preferably one that understands XML.

Workflows and Events

JIRA sends software events internally when issues are changed. Some of these events are hardcoded, such as the one sent when an issue’s assignee changes. However, events sent during a transition are designed to be configurable. Many of the events listed at Administration→System→Events are really intended for use in workflows. For example, the Work Started on Issue event is intended to be sent (fired) by a post function on all transitions into the In Progress status.

The standard post function Fire Generic Event can be edited to send a more appropriate event when a transition executes. The main reason that a JIRA administrator cares about what type of events are sent is because they are used by a project’s Notification Scheme (see “Notification Schemes”), which controls who receives email when the status of an issue changes.

You can also add new types of events to JIRA at Administration→System→Events, as described in detail at http://confluence.atlassian.com/display/JIRA/Adding+a+Custom+Event.

The ability to create new events and have your workflow fire them off instead of the Generic event or some other standard event can be useful for trimming JIRA spam. For example, if you really want to fine-tune who receives email when an issue changes status, you can define a new event type for each transition, perhaps giving them highly descriptive names such as Task Workflow: Open to Resolved Event. (The event names don’t appear in email templates.) Then you can edit the transition from Open to Resolved, and change its post function to fire the appropriate new event. In a custom notification scheme, you can then specify which users will receive email for precisely that one transition and no other transitions.

Transitions, Sub-Tasks, and Links

When designing a workflow, there is often some confusion over which parts of JIRA are best for different purposes. Should a task be tracked as a sub-task of the main task? What are the differences between sub-tasks and links for reporting? This section clarifies the advantages and disadvantages of different ways of designing workflows.

A transition is part of a linear flow in a JIRA workflow. It doesn’t have support for parallel actions. Transitions are intended to be relatively simple, perhaps with some post functions that set values in an issue.

Standard JIRA supports two levels of hierarchy in issues, and just one level of hierarchy for projects. An issue of type Bug or any other issue type can have many sub-issues. The Sub-task is just one of many possible sub-issue types. The only difference between an issue and a sub-issue is that the sub-issue has a value in its Parent field. The advantage of a sub-task is that work can be recorded independently of the parent issue. So if two pieces of work proceed in parallel, they may be a good fit for using sub-issues. Sub-issues and their progress are displayed clearly inside the parent issue. Sub-tasks can be searched for with JQL such as: parent in (“TEST-2”). Sub-issues have to be in the same project as their parent issue.

Issue links are a more general form of sub-tasks because they allow a many-to-many relationship. You can also choose different types of links such as Related To or Duplicate. You can further customize issue links by defining your own link types. Issue links are visible from inside issues, and can now be searched in JQL with: key in linkedIssues(“TEST-2”). JIRA does not have a general purpose tool to display the relationship between a set of linked issues, but there at least two add-ons that provide this: Links Explorer and Links Hierarchy Structure.

Neither sub-issues nor links can be easily ordered in JIRA. That is, the related issues are a set, not a queue. Also, sub-tasks inherit the issue security setting of their parent issue.

JIRA Agile adds an Epic issue type which provides a way to collect issues together. This is the most common way to add another hierarchy level to JIRA.

If you need more levels of hierarchy than JIRA and JIRA Agile provide then you may be interested in the Structure add-on from ALM Works, which provides multiple levels for JIRA issues with a well-integrated UI.

6. Custom Fields


One of the primary purposes of an issue tracker is to collect organized data, and custom fields let you personalize that data. If you need to track how many angels can dance on the head of a pin, JIRA allows you to create a custom field for that. (It would be a number field, presumably, though number field values in JIRA have an upper limit of 100 trillion.) The appeal of creating custom fields is understandable, and it makes sense that as an organization grows and adopts JIRA for varied purposes, the number of custom fields grows along with it.

The problem is that custom fields are like glazed doughnuts — they always seem like a good idea at the time, but if you continue thinking that way in perpetuity then you’re sure to witness a reduction in speed. The number of custom fields in JIRA is one of the most significant factors in the performance of a JIRA instance. You can see the details of Atlassian’s performance testing of JIRA 6.4 in their enterprise documentation at https://confluence.atlassian.com/display/ENTERPRISE/Scaling+JIRA.

There are certainly other factors that can affect performance, such as the number of issues, number of concurrent users, and behavior (or lack thereof) of add-ons. But for most administrators, many of these factors are difficult to directly control. Managing the number of custom fields in your instance is the most straightforward way to control the performance of JIRA.

In addition to improving performance, custom field management can help reduce the administrative overhead involved in updating and maintaining custom fields in JIRA. Restricting the overall number of fields is only part of this process. Care and thought should be put into the selection of custom field types and how those fields are configured. This will pay dividends for your users in terms of reporting and user experience.

What’s the Big Deal with Custom Fields?

When users think of the fields associated with an issue, they think of the fields that are actually displayed on the screen for that issue. JIRA thinks differently. When a new custom field is created in JIRA, by default it is added to every JIRA project and issue type, even if it never actually appears on a screen. This means that JIRA has to make a decision about that custom field for most issue operations such as create, edit, and search, even when the field has no value. The part of JIRA most impacted by all this additional work is the Lucene issue index.

The Lucene index is your database’s butler. It maintains its own copy of all of JIRA’s issue information in a format that is optimized for search operations. When you submit a JQL search it is the Lucene index, not the database, that handles the request. This significantly reduces the load on the database and is the reason the database is rarely a performance bottleneck for JIRA, and that most JIRA searches are surprisingly fast. You can delete the Lucene index and rebuild it from the information in the database (though it may take a while in larger JIRA instances, so be careful).

To understand the impact of custom fields on the Lucene index it helps to visualize the Lucene index as a spreadsheet where issues are along the y axis and custom fields are along the x axis, as shown in Figure 6-1. Scaling along either direction (by adding an issue or a custom field) increases the complexity of searching for issues. Keep in mind that the Lucene index has to be kept synchronized with the data. This means that whenever the data is updated, the index needs to be updated as well. This is why creating, editing, and searching issues all impact the index. As more custom fields are added to JIRA, the time it takes to complete any of these operations increases.


  Figure 6-1. Visualizing information in the Lucene issues index

If you are administering a large JIRA instance, it is important to understand this relationship between custom fields, the Lucene index, and performance. This can prove helpful in troubleshooting, especially if you notice a lot of activity reading from and writing to the disk where the index lives. Note that Atlassian recommends using a fast, local disk for the Lucene index files. More commonly, you should be exercising this knowledge to guide your decisions about how you set up and configure custom fields.

If you are administering a small JIRA instance, then you are unlikely to notice any performance benefits from reducing the number of custom fields below a few hundred. Small JIRA instances often experience no real performance issues at all. However, as I mentioned in the introduction, there’s more to managing custom fields than just performance benefits.

Choosing Custom Field Types

JIRA ships with 22 custom field types.1 The following list includes the other 20 types along with discussion about when to use each one. Add-ons can provide you with many other custom field types, see their documentation for more information about those.

Standard Text Fields

Standard text fields contain text. No surprises, no strings attached! (Okay, technically they have nothing but strings attached.) The standard text fields all use the Free Text Searcher. This means that a general JQL text search such as text ~ “foo” will search in all the custom text fields as well as the system text fields (Summary, Description, Environment, and Comments).

Text Field (single line)

This field has a practical limit of 254 characters. This is your best choice if the information you are trying to capture is short. Compared to multiline text fields, single line text fields have a smaller screen footprint, which is good for the interface.

Text Field (multiline)

JIRA does not limit the size of multiline text fields. Because of this, the theoretical limit is derived from the kind of database that JIRA is using. In practice you will break the interface before you exceed the limit. The Description system field is a multiline text field, and if you can search for any information within that field. You could keep all your unstructured text about an issue just in the Description and Comments fields. However, it is sometimes useful to have other multiline text fields to help people know what information to add where.

Text Field (read only)

 The read only text field has a limit of 255 characters. It can be configured to appear on view screens but not on create, edit, or transition screens. This means it cannot be used to display messages to your users on these screens, which limits its value somewhat. You also cannot assign the field a default value. The value can be set using a post function, so the field can be used to set a value in a workflow when you don’t want the any one to edit that field. This field is most often used to hold read-only information about issues imported into JIRA from other systems.

Validated Free Input Fields

These fields have a text input box where you can enter whatever you please; however, JIRA will only accept certain values.

Number Field

Not surprisingly, JIRA will only accept a value in this field if it is a number and formatted in the appropriate way for your JIRA locale. Decimals are fine, but are rounded to three decimal places. Negative values are also allowed. The upper limit, as mentioned in the introduction to this chapter, is 100 trillion. The lower limit is peculiar to say the least. Suffice to say that I’ve gotten JIRA to output a value of negative infinity. Also, searching on a range of negative numbers returns confusing results.


 This is a single line text field that will only accept a URL. What this means is that the value is checked to ensure that a valid protocol has been entered (e.g., http://) followed by other characters. The URL searcher is an exact text searcher, which is rather unfortunate. This means you cannot do a text search to find all addresses with oreilly in the URL. You have to search for the full URL text such as http://shop.oreilly.com/category/new.do. The URL field also suffers from a field limit of 255 characters, which can be frustrating when dealing with longer URLs.

Option Fields

Option fields allow the user to select from a predefined discrete list of choices. This makes them the best choice for getting consistent, reportable field values without having to worry about the case sensitivity and spelling variations of the Labels field (see “The Labels Field”).

Select List (single choice)

Single choice select lists allow the user to choose just one value from a list of options. If this is the desired behavior, then this is your field. Be careful, though, there is no easy way to convert custom field types. You cannot simply convert this field into a multiselect list later.

Select List (multiple choices)

Unlike its single-select relative, a multiple choice select list (multiselect list) allows you to choose as many options as are available. If you are torn between whether to use a single or multiselect list, then in general you should go with the multiselect list because it is more flexible.

Select List (cascading)

A cascading select list actually consists of two single select lists where the options in the second list depend on what is chosen in the first list. This mechanism is an excellent way to break down long lists of choices that can be logically categorized with the first list. The timezone options in your JIRA user profile are an excellent example of a cascading select list. There are no options to add additional cascades, nor are there cascading multiselect lists. Note that if you make a cascading select list required with a field configuration, as in “Field Configuration Schemes”, only the first list requires a value. The None option will still be available for the second list.

Radio Buttons

A radio button field is functionally identical to a single select list. Choosing one over the other simply boils down to cosmetic preference. I personally have a strong preference for the single select list because it is more compact on the screen, but only if you have a small number of options like Yes and No.


Here we have another repeat because checkboxes are functionally identical to a multiselect list. This time, however, I have no favorite. I find that the interface for checkboxes is cleaner and more intuitive, while multiselect lists should always be used when you have many options. If I know that the list of options will always be small (say six or fewer), then I consider using checkboxes.

The Labels Field

The labels field is special enough to get its own section. Labels are the same idea as tags in many other applications. This field type combines the reportable nature of option fields with the freedom of text fields. Labels are best used for short-term work by a small set of users. This allows users to quickly gather data on a collection of issues without requiring the creation of a new custom field or options.

Caution: Because anyone can create a new label, it’s very easy to create multiple labels for the same thing. For example, were all those issues labeled with HP or Hewlett_Packard? Even with JIRA prompting them with existing values, people tend to mistype the same word over time. To make matters more confusing, labels are case-sensitive when they are added but case-insensitive when searching for issues by label.

JIRA labels cannot contains spaces, and cannot easily be renamed in bulk or deleted. As of JIRA 6.4, bulk updates to issues can now append to Labels field values instead of overwriting the existing values.


 If you want another field that functions exactly like the system Labels field, you can create a custom labels field. While the system Labels field very effectively fills a niche purpose, adding a second labels field provides little additional value, and I have rarely found use for one. One benefit of a custom labels field is that its values (and hence the values that appear in its drop-down list) are independent of the system Labels field.


Date Picker Fields

Date fields are critical to how users sort and plan their work in JIRA. Adding custom date fields can make a crucial difference for teams with sensitive time-based requirements.


Date Picker

The date picker allows you to choose a specific day but not a specific time on that day. This works well if the time is irrelevant. The date picker field does not seem to have any clear value limits. If you plan on sticking to dates within 1970 to 2030, you should be fine, but I wouldn’t use JIRA to date ancient artifacts or plan a timeline for interstellar travel.


Date Time Picker

 As the name implies, this field allows you to choose both a date and a time. This field is most often used to capture the time when a certain event, such as a workflow transition, occurred. Date time fields are stored as Unix timestamps and will not behave properly for dates before January 1st, 1970 or after January 19th, 2038 (UTC).

Tip: When you use JQL to search for dates, remember that if you just specify a date then JIRA assumes that you mean midnight at the start of that day. For example, if you want to find issues with a due date of 9th July 2015 and earlier, you have to search for duedate <= ‘2015/07/09 23:59’ or just duedate < ‘2015/07/10’.

User & Group Picker Fields

User Picker and Group Picker fields can also be incredibly useful. You can use them to create new issue-specific roles2 such as Tester or Approver. These custom user fields can be referenced in permission schemes, notification schemes and workflows, giving administrators tremendous flexibility to shape the way that users interact with issues.


User Picker (single user)

The single user picker is a great choice for an issue role that would only ever have a single user in it (e.g., QA Lead).

User Picker (multiple users)

Multiuser pickers allow us to choose multiple users for an issue role without needing them to be in the same group. This custom field type really shines for listing a set of reviewers, testers, or approvers of an issue. The multiuser picker is also your answer to allowing multiple assignees on an issue. I typically keep the Assignee field as the primary responsible user, and list other assignees in an Additional Assignees multiuser picker field.

Group Picker (single group)

 The single group picker allows you to select a JIRA group instead of a JIRA user. This provides one possible solution to the problem of how to assign a team to an issue, assuming that your teams can be maintained as directory groups. (The other solution is to use an option field, but a group field is the more powerful of the two.)

Caution: Be incredibly wary of adding a group field to your notification schemes. Without validation, there is nothing to stop a user from adding the jira-users group to the custom group field and notifying all of your JIRA users. This particular faux pas is a likely way to earn an unhappy conversation with your boss. Using a group picker in a permission scheme has no such risk, however.

Group Picker (multiple groups)

 Like all multipicker fields, the multigroup picker is more versatile than the single-select version. See the entry for the single group picker for the warning about referencing this field in a notification scheme.


Other Picker Fields

These fields types allow you to choose from other objects in JIRA, specifically versions and projects.


Version Picker (single version)

A version picker lets you selects from all available versions for an issue’s project, just as the Affects Versions and Fix Versions system fields do. The single version picker differs from the system fields in that it only allows the selection of a single version. Because JIRA has a great deal of built-in functionality surrounding the system version fields (especially the Fix Versions field), I don’t recommend trying to replace them. Only use custom version fields to supplement the existing system fields, for example a version field named Target Fix Version is sometimes used.

Version Picker (multiple versions)

This field type behaves the same as the system version fields except that there is no built-in functionality for it. It does not appear in release notes (https://confluence.atlassian.com/display/JIRA/Creating+Release+Notes) nor does it contribute to version progress in JIRA’s roadmap feature.

Project Picker (single project)

 The project picker allows a user to choose from any project that is visible to them. While this field is rarely useful in most projects, it is very useful in a JIRA administration project, e.g., What project is related to your issue?
Caution: There is a long-standing bug where the merge function for version pickers custom fields does not work as expected. When a merge is performed on a particular version, that value is deleted from a custom version field instead of updated. This is even more reason to stick with the system version fields.

What is a Custom Field Context?

A custom field context controls the scope, default value, and certain type-specific features for a custom field in JIRA. Before addressing the details of contexts, though, I’ll address the matter of what this feature is called.

The custom field context is known by several names in different places in JIRA. The two most common names are custom field context and custom field configuration scheme. Other names are a combination of the first, e.g., configuration scheme context. I have a strong preference for the term custom field context. Custom field configuration scheme is too easily confused with field configuration scheme, which is one of the seven schemes of JIRA discussed in “Field Configuration Schemes”. For this reason, I’ll use the term custom field context, or simply context, throughout this chapter.

To access custom field contexts, go to Administration → Issues → Custom fields, click on the custom field name, and then click on Configure under the cog item on the right. You should see a screen similar to the one shown in Figure 6-2. (Edit is for changing a field name, description or searcher, but not for contexts.)

  Figure 6-2. An example custom field context

The context is where you can usually set the default value for any custom field. This is useful for setting list options to the most common value or for adding a template or help text to a text field.

For option fields, the context allows you to edit the option list, whether this is for renaming options, disabling or deleting options, or adding new options to the list of options. Deleting an option that has been used in JIRA constitutes data loss, so make such a change with care and read “Deleting Contexts” carefully beforehand.

Single user picker fields can optionally have user filtering applied at their context. This allows you to restrict the set of valid users for such a field by groups and project roles. For example you could restrict the options for a QA Lead single user picker custom field to only accept members of a Quality Assurance project role.

Limiting Contexts

The default context created for all new custom fields is a global context. This means that upon creation, the field is potentially applicable to all projects and issue types in JIRA. By editing the configuration of the context, you can limit which projects and issue types it will actually appear in. An issue whose project and issue type are outside the scope of a field’s context will not display that field, even if it is on the correct screen and remains shown by the field configuration.

The ability to control context is useful when you need to add a field to a commonly used screen for only a few projects or issue types.

For example, let’s say that you would like to categorize bug fixes with a custom field named Bug Category that has options like Unhandled Exception, UI Error, Logic Error, and so on. The logical time to set this field would be during the resolution of the issue, but the field is only meaningful for issues of type Bug.

In this scenario, let’s assume that the project you want to modify has several issue types that are using the same screens and workflow. Without using contexts, you would have to take the following steps to implement the requirements for the new field:

  • Copy the transition screen being used to set the resolution in the workflow.
  • Add the Bug Category field to the new transition screen.
  • Copy the workflow to a new workflow for Bug issues.
  • Edit the new workflow to use the new transition screen.
  • Update the workflow scheme for the project to use the new workflow for Bug issues.

The need to fork the workflow means that you now have another workflow to maintain for this JIRA project. If your users need to be able to view or edit this field, you would need to add new screens and screen schemes, further complicating the configuration.

The solution using contexts is much more elegant. You simply limit the context to the Bug issue type only, then add the field to all screens where it is wanted. The field will then show only for the Bug issue type.

Another advantage of using custom field contexts is that they can actually improve JIRA’s performance. Part of this benefit comes from eliminating the schemes that you would have otherwise needed. But the actual narrowing of the context has a direct impact on the Lucene index. When a field’s context is limited, the Lucene index marks that field as unsearchable for everything outside of its context. This can improve search times because JIRA is able to skip the processing of irrelevant fields.

Adding Contexts

The most glorious aspect of custom field contexts is that you can have multiple contexts for a single custom field. For a given custom field you could create a different context for each project and set each one to have a different default value. By far though, this feature is most useful for allowing option fields to list different options for each context (project and issue type). Because of this flexibility, it is recommended to give custom fields as generic a name as possible. This will allow you to more easily reuse custom fields across JIRA, while minimizing the number of total custom fields.

  Figure 6-3. The TRAIN project is using the default global context that lists Horse options as breeds
  Figure 6-4. The DEMO project is using the same custom field but with a different context that lists Horse options by their names

There are limits to how contexts can be used. Each JIRA project can only have a single context, and each field can only have a single global context. A project-specific context will override a global context. This effectively means that you can never have different option values for different issue types within the same project.

Dangers of Custom Field Contexts

Making changes to JIRA’s seven schemes is like being guided across a crosswalk by a giant fuzzy teddy bear. Sure, there is some inherent danger, but the path is clear and you have a friend looking out for you. By contrast, making changes to custom field contexts is like being guided across a tightrope by a grizzly bear. As long as you are careful, everything will be fine, but things sure can go sour quickly.

Deleting Contexts

Caution: Read this section and the next before you delete or change a context for an Options custom field!

Deleting a context in JIRA is frighteningly easy. It takes only a single click on the trash can icon next to a context, and there is no confirmation screen or warning. This is not a problem for text fields, but for Options fields it effectively removes all of the data from issues that were using the deleted context. The data will be visible in affected issues until you try to edit the issue — then the options from the new context will be shown, and the old value is gone. The old value is shown in the issue’s History tab.

Changing Contexts

Unlike deleting contexts, editing contexts is a regularly occurring operation for JIRA administrators that use them. In the course of editing a context you may accidentally remove projects or issue types that were previously using that context. If the change results in a project or issue type having no context, there is little danger. The data will still be present and the context simply needs to be edited to include that project or issue type again. However if the context has actually changed (perhaps by defaulting to the global context, and is for an Options field), then you are up against the clock: now, editing an issue will force the user to choose a value from the new context. Even if the user doesn’t choose a new value, the old value will be cleared. Hence, the longer this change goes unrepaired, the more data you could lose.

Adding a New Context

Options in different contexts with the same option name are still unique because they have different numeric identifiers. That is, an option named Dog in one context is not the same as an option also named Dog in another context, even though their names are the same.

So adding a new context with the same option names as the previous context still means you are changing contexts. This will not be immediately obvious because searching will find both the new and the old option name and they will be lumped together in your search results, but they are still inherently different values. Editing any issue with an old context will drop the value unless the new value is selected.

 Screens and Field Configurations and Custom Field Contexts, Oh My!


So far in this book we’ve seen three different ways to control fields in JIRA. Table 6-1 contains a review of what screens (“Issue Type Screen Schemes (ITSS)”), field configurations (“Field Configuration Schemes”), and custom field contexts do.

Note: The Assignee, Comment, and Attachment fields can’t be made required. Issue Type and Summary fields are always required. The Resolution field is required in transition screens.

Table 6-1 shows what is unique about each feature. If you need a field to be displayed in an issue, it must be on a screen. To make a field required, set its renderer, or change its description from the default, then you must use a field configuration. And custom field contexts are the only way to set and change default fields values or option field values.

In fact, the only overlapping functionality between the three features is that they can all be used to hide fields. On this matter, there is no clear winner among them. Each has its own advantages and disadvantages for hiding fields. Deciding between them is largely a matter of figuring out which one would require the fewest number of configurations to enforce the required behavior.

For instance, screens have the best granularity of the three options, as you can use a different screen for create, edit, view, and transition operations all within the same issue. So if you need a field to show on an issue only at certain times, you should use screens to control the field’s presence. I also recommend using separate screens when they serve separate purposes. While you can use elaborate field configurations and contexts to enable you to reuse a screen in highly disparate issue types, at some point it becomes easier to maintain two separate screens than a multitude of strange field configurations.

Tip: Note that excluding a field from a screen does not make it invalid for the issue type, and any valid field can be edited through the bulk change operation.

Field configurations are the only way to hide system fields. If you need to hide one of the system fields that stubbornly refuses to disappear from the view screen (e.g., the Labels field) then you must use a field configuration. Field configurations are also the only feature where hiding a field is the active option. That is, hiding a field using screens or contexts is passive — they hide fields by exclusion. This means that ideally, field configurations should be used only to hide a field that rarely needs to be hidden, as that will minimize the number of overall configurations needed (as well as the effort to maintain those configurations).

Using custom field contexts to hide fields does have performance benefits, but those benefits are slight. More emphasis should be put on using contexts appropriately than trying to eke every last performance benefit out of JIRA. The question then becomes a matter of how often the field will be used. If the field is unique to only a few projects or issue types, then contexts are a good choice for hiding the field. In this scenario, you will only rarely need to modify the context when new projects and issue types are added, as the field will generally be inapplicable to most of them.

In summary, you should create a unique set of screens for each broad type of work that your organization is tracking in JIRA. This is also discussed in Chapter 4.

If there are unique situations that need a field to be hidden for a minority of projects, use a field configuration to hide it and avoid creating a duplicate set of screens.

If a field is only valid for a few projects or issue types, then limit its scope with a custom field context.

Where Is My Field?

With all of the different ways to hide fields in JIRA, JIRA administrators are commonly asked Where is my field?. This may seem like an opportunity to show off your prowess at differentiating between screens, field configurations, and contexts, but resist the urge to invoke your inner Sherlock Holmes. JIRA has a feature exactly for this question and you’ll save yourself a tremendous amount of time by using it. This feature is appropriately named Where is my field? and is documented at https://confluence.atlassian.com/display/JIRA/JIRA+Admin+Helper#JIRAAdminHelper-PermissionHelper.

The Where is my field? feature (Figure 6-5) is available to administrators on any issue’s create, edit, or view screen, and also via the Configure Fields button. It is excellent for quickly assessing the reason that a field is absent in that particular scenario. In addition to determining if a field has been left off a screen, is hidden by a field configuration, or is excluded from a context, it can also detect whether a field is missing from the view screen simply because its value has not been set.

Tip: Custom fields with empty values do not appear on the view screen. This is a common cause of user confusion, but does save space on the screen.

One scenario that the Where is my field? feature will not detect is when a field has been hidden by the create or edit screen’s Configure Fields option. This option allows the user to select which optional fields are displayed on a screen and is intended to allow people to streamline their create screens. It’s not uncommon for users and administrators alike to forget they have hidden fields this way.

If you have gone through all of the above checks and the field is still missing, then you have my permission to get out your tweed and your pipe, call up Watson, and set about investigating. You have a case to crack! At this point you should probably check what add-ons are installed and whether any custom JavaScript code has been embedded in the field description in your field configuration.

  Figure 6-5. In this case the Horse field does not appear on the View Issue screen because it has no value. Note that Project and issue type scope refers to the field’s context.

Minimizing the Number of Custom Fields

This chapter started off by stressing the importance of minimizing the number of custom fields use in JIRA. This section presents several strategies that can be used to do that. The section after this one describes how to correct the problem of already having too many custom fields.


Use generic field names

Making your custom field names generic enough to be reused for different purposes is critical for minimizing the number of custom fields. Several other strategies discussed here assume that you have used a generic name to begin with. The primary idea here is that you are more likely to be able to reuse an existing field rather than create a new one if you have used generic names for your fields. For example, a field named Document Link can be applied more widely than one named Link to Insurance Form.

Use a new context instead of a new custom field

For any new custom field request, you should check to see if an existing field will fit the need. All that is required is that the field have an appropriate name and be of the correct field type. Remember that option field values can be made completely different for each JIRA project using custom field contexts.

Add field details using a description in a field configuration

Your users may be disappointed with generic field names. In this case, the best strategy to appease them is to add detailed information about the field using a field configuration. Field descriptions in field configurations override the original custom field’s description and give you the opportunity to impress the details of the field that are lost through the use of a generic name. To use the Document Link field example from earlier, if the intention of this field is to hold a link to a specific type of document then it is good practice to add a helpful description (such as Provide a link to your Insurance Form) to the field description in the relevant field configuration.

Rely heavily upon the Description system field

Multiline text fields are exceptional for catching a lot of information in a single field. However, the Description system field that comes with JIRA is typically sufficient. If the purpose of a proposed multiline text field is to simply contain more information about the issue, the prudent thing to do is to simply roll that functionality into the Description field.

Use the default value for multiline text fields to create templates

One argument in favor of using custom multiline text fields is that they can be given default values, whereas system text fields like Description cannot. This allows you to create a template by embedding the template as the default value for the field. For example, a good bug report will contain the steps to reproduce the bug, the actual result, and the expected result. Rather than create three separate fields, you can create one multiline text field with three headers (Steps to Reproduce, Actual Result, and Expected Result) in the default value.

Don’t try to recreate long surveys in JIRA

Surveys and questionnaires often have long lists of what may appear to be custom fields. Creating a custom field for each question for a short, generic survey is fine, but naming a field something like Describe your biggest concern about the new coffee machine is not very reusable. Adding thirty custom fields for a single survey has too great of an impact on the instance as a whole to justify using custom fields for survey questions. Use JIRA links instead of URL fields

Unless your URL link is intended to be a required field, use the link operation to add web links to an issue, rather than capturing that information in a URL field.

Challenge all requests for new fields

When I administer a JIRA instance, I require a meeting with every user who requests a new custom field. This allows me to interpret their requirements for the field and explain why I am such a stickler about adding new fields. Cooperative requesters will then work with you to figure out if an existing field can be repurposed or if the field is needed at all. Do not be overly stingy though. If a user has a valid request for a new field, give it to them, because that’s what custom fields were made for.

Verify that each field has a purpose

Ensure that the information captured by each field serves a justifiable purpose. If the data is not used to work on the issue, or for reporting, then it is not needed. It’s worth checking with a JQL query how custom fields are actually being used on a quarterly basis.

Establish and share a governance policy

Create a clear and definitive set of regulations that establish how new objects such as custom fields and configurations are added to JIRA. A governance policy conveys that you have a well–thought-out plan with regard to how JIRA is managed. It is also much more difficult to argue with a document than with a person.

Get executive backing

 You can exercise every bit of advice listed above but it will all be for naught if you can’t enforce it. Share your governance policy with relevant managers and executives at your organization and impress upon them your need for their support in keeping JIRA running smoothly. Be ready to substantiate your policy with facts.


Reducing the Number of Custom Fields

Controlling the number of custom fields proactively is one thing, but what if you already have more than a few hundred custom fields in your instance? The truth is that there is no easy path to reducing the number of custom fields once they are already in place and in use. It is a time-consuming process and requires that a great deal of care be taken to ensure that no critical data is lost. But if you are already experiencing significant performance issues due to more than around 600 custom fields, this is still an efficient way to improve performance.

To start with, you should be looking for fields that are used so rarely that they need not exist, or fields that could potentially be merged with another field. To determine how widely a field is used, the Issue Statistics gadget on a JIRA dashboard can prove very useful. Edit the gadget and group by the custom field in question. Then little-used fields will either have very few non-empty values or very few non-default values. Your saved filter can also order by the Updated system field to see when an issue with a value in the field was last updated. If it was more than a year ago, then maybe that field is no longer being used?

Caution: Be careful if your instance has projects that have restricted the browse permission. If you are unable to view a project’s issues as a JIRA administrator, then their data won’t contribute to your searches or gadgets, and you will get inaccurate results. To further complicate matters, your instance may also be using issue security schemes that restrict the visibility of specific issues. Resolving these obstacles will depend on the specifics of your instance. Just ensure you do not accidentally expose any data to the wrong users in the process.

One way to find candidates for merging fields is to create a list of fields for each custom field type in a spreadsheet outside of JIRA. This process will initially be tedious (the REST resource rest/api/latest/field.json may help) but will pay dividends as you can limit your scope for matches to only the relevant field type. This will also give you a place to make notes about which fields to merge after you contact the relevant JIRA project leads.

Merging fields can be dangerous. Make sure you document your process well and are cautious to not lose data. You also need to announce these changes to your users so that they can update any filters, dashboards, and agile boards as needed after the merge.

The most important step of all is to implement policies to control custom field growth after you have completed your field reduction.

0 Responses on JIRA Tutorial"

Leave a Message

Your email address will not be published. Required fields are marked *

Copy Rights Reserved © Mindmajix.com All rights reserved. Disclaimer.