JIRA as a Platform

The San Francisco Atlassian User Group met last night in the coolest place so far, PariSoMa. ParisSoMa is a "innovation loft" - imagine a shared loft with lots of tables, chairs and people to talk with. About a dozen people chatted about Atlassian tools and tools in general. Thanks to Atlassian for the beer and food!



I gave a short talk about using JIRA as a platform, where different groups can use JIRA without their changes affecting each other. The original slides are above and also available from here. A reformatted version of the notes is below.

JIRA as a Platform

Summary

JIRA often starts in one department and then spreads. Of course, each department often has different needs for JIRA. The question is how best to configure JIRA for separate uses. This post contains a worked example of one way to add a new department to JIRA without affecting other existing departments.

Overview

Using the combination of (project, issue type) in JIRA we can change:

- the active custom fields, and most system fields
- position of fields on the screen (1 column only)

and also

- Components
- Versions
- Permissions
- Notifications

However, there's not much documentation on how to do this in an organized manner.

Also, maintaining hundreds of custom fields in JIRA can become tedious. For example, a set of 20 related fields need to be added to the issues in a new project, but they were originally restricted by project. Now each field in turn has to be updated by hand.

Worked Example: Setting up a New Department

1. Create a new Project Category for the department, e.g. "Accounts". Some scheme names will get this word as a prefix.

2. Create a new issue type for that department's issues, e.g. "Invoice". Other scheme names will have this word as a prefix.

3. Create a test project, e.g. ACCTEST

Summary so far: ACCTEST is a project in the Accounts category and contains Invoice issues.

Basic Project Setup

• Set the category for the test project to "Accounts"
• Create a notification scheme named "Accounts Notification scheme", e.g. copy the default
• Set the notification scheme for the project to "Accounts Notification scheme"
• Create a permission scheme named "Accounts Permission scheme", e.g. copy the default
• Set the permission scheme for the project to "Accounts Permission scheme"
• Create a workflow scheme named "Accounts Workflow scheme" and configure it to use a copy of the default JIRA workflow
• Set the workflow scheme for the project to "Accounts Workflow scheme"

Advanced Project Setup

We need to define the more complex schemes:

• Issue Type Scheme
• Field Configuration Scheme
• Issue Type Screen Scheme, which uses a Screen Scheme

and to configure the ACCTEST project to use them.

As an aside, an Issue Security Scheme is only needed if you have some departments that are more private than others, e.g. Legal

1. Issue Type Scheme

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

Under Admin, Issue Types (middle tab) create a new Issue Type Scheme named "Accounts Issue Type Scheme"

Add the main issue type, .e.g "Invoice" as the default

Add other issue types, e.g. "Task", "Improvement" if they will be used by the new department

2. Field Configuration Scheme

A field configuration controls which fields are part of an issue type, e.g. what data is in an Invoice. Fields can be marked as Required, and Hidden fields are not shown as searchable.

Create a new Field Configuration named "Invoice Field Configuration"

Don't hide any fields here yet, use screens for that

Create a new Field Configuration scheme named "Accounts Field Configuration Scheme"

Configure the scheme to use the Invoice Field Configuration for Invoice issues

3a. Screen Schemes

Screens control whether a field appears in an issue, 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 Edit Screen". This screen should have all the fields in the Accounting Issue issue type

Create a screen scheme named "Invoice Screen Scheme"

Configure the Create, Edit and View issue screens to be the same screen for now

Later on, copy the Edit screen to be a Create screen and remove fields not needed at creation time

3b. Issue Type Screen Scheme (ITSS)

An ITSS ensures that the right screens are used for each issue type.

Create an ITSS named "Accounts ITSS"

Configure the default screen scheme to be the "Invoice Screen Scheme" defined in the previous page

Adding a Custom Field

Adding a custom field is the real test of all this work. It's just as usual except:

1. Restrict the custom field to just the issue types that use it, e.g. Invoice
2. Don't restrict the custom field to a project
3. Add the custom field to the Invoice Edit screen (and Invoice View screen and Invoice Create screen if defined)
4. Don't add the field to any other screens at all
5. Hide the field in the Invoice Field Configuration to stop it being searchable

You will likely need to select a project and issue type to have the searchable custom fields appear properly

Existing Schemes

Having a standard approach to creating schemes and issue types is all very well, but what about an existing instance of JIRA? The following ideas may help with the clean-up.

Document the existing system, ideally by talking with the original designer. Sometimes there was a vision, sometimes they were still learning how to use JIRA.

Change one department at a time to whatever approach you have settled on.


Conclusion

Users hate being surprised by new fields that they don't care about!

The key to using JIRA for many groups is to have a standard way of using JIRA schemes and issue types. And since JIRA schemes can get complicated, document what you did and why.

Occam's Razor comes into play here. Too few schemes and every change will have unexpected consequences. Too many and you'll lose track of how they differ.