Practical JIRA Administration

Chapter 4. JIRA as a Platform

Overview

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. ¹ 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:

• Issue Type scheme

• Workflow scheme

• Field Configuration scheme

• 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:

Accounts

A project category

ACCTEST, ACCMAIN, ACCSUB

The keys of three JIRA projects in the Accounts project category

Accounting, Engineering

Groups of JIRA users

Users, Developers

The standard JIRA project roles

Invoice

A new issue type

Amount

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

Summary

The key to using JIRA for many groups is to have a standard way of using JIRA schemes and issue types. The details of the approach used in the example in this chapter are:

• The project category is used as the common theme for related projects.

• The naming of schemes uses the category or issue type names.

• Field constraints are implemented using issue types not projects.

• Use project roles in preference to groups.

• Document what you do!

Of course there is a balance to be struck with any approach. Too few schemes, and every change will have unwanted consequences. Too many schemes, and you risk losing track of how they differ.

Tip

In general, try to make the names of schemes, filters and dashboards unique in their first few letters. This helps when you are searching in a long list of names. That is, don’t use names such as Agile Simplified Workflow for ... even though JIRA Agile does.

¹ You can also allow numbers and underscores in the project key if that helps. This is configured at Administration→ Settings→Advanced Settings, by clicking on the jira.projectkey.pattern value.