Adding Users to Schemes

There are a dozen different ways (shown in Figure 3-1) 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.

Figure 3-1. Referring to users in a scheme

The simplest of these are:

Current Assignee

The user that the issue is currently assigned to.

Reporter

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 Chapter 1.

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 Figure 3-2. 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.

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.

Figure 3-2. Issue Type Scheme

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.

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 Figure 3-3. 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”.

Figure 3-3. Notification Scheme

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.

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 Figure 3-4. Just like notification schemes, this set of users can be configured in the various ways described in “Adding Users to Schemes”.

Figure 3-4. Permission Scheme

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.

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 Figure 3-5. 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.

Figure 3-5. Issue Security Scheme

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.

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.

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 Figure 3-6. 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.

Figure 3-6. Workflow 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 Chapter 5.

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 Figure 3-7. A default field configuration can also be set.

Figure 3-7. Field configuration scheme

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 Figure 3-8 and Figure 3-9.

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 Figure 3-8.

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.

Figure 3-8. Screen scheme

Figure 3-9. Issue Type Screen Scheme

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.