Atlassian JIRA Configuration Tutorial: JIRA Schemes (Part 1)

Part I - JIRA Schemes (Part 1)

Part II - Overview of JIRA Security

Part III - JIRA Schemes (Part 2)

Part IV - JIRA Schemes (Part 3)

Atlassian JIRA is an extremely flexible piece of software that can be easily customised by a casual administrator. Nonetheless, to take full advantage of all of its power, it's necessary to understand how it works and how are organised the concepts that it manages.

This series of blog posts is an overview of JIRA and a quick tutorial about configuring a JIRA project by taking advantage of JIRA configuration schemes.

If you're a Solaris user you may be interested to other posts I wrote about setting up and managing JIRA on a Solaris installation (some of them might be useful to users of other UNIX and UNIX-like operating as well):

• Installing JIRA on Solaris
• Registering JIRA as a Solaris SMF-Managed Service
• Backing Up JIRA and Confluence Taking Advantage of ZFS Snapshots
• JIRA: Creating Issues from TLS-Encrypted Email
• Adding Google Analytics Code To JIRA

Basic Concepts

Whenever you use JIRA, you're creating and updating issues in a project. Issues may be of specific types, may have custom fields and a security level. A user with appropriate permissions may act on an issue by applying a workflow transition.

Although it might seem otherwise, a project is not "just" an issue container with project roles and a set of security policies:

A project is a logical partition inside JIRA where a set of configuration rules are applied.

What a JIRA Scheme Is

This is when the JIRA scheme concept comes in. Inside JIRA almost everything can be configured:

• Workflows.
• Issue types.
• Custom fields.
• Field configurations.
• Screens.
• Notification.
• Permissions.

For each one of the above-mentioned concepts, user configurations and customisations are defined at the JIRA (global) level. The relation between a set of specific configuration rules for such concepts and one (or more) project is established by a set of schemes. In some conditions, a scheme might establish a relation between a scheme and another scheme.

This model is pretty flexible: the same issue type, for example, might be reused in different projects with different workflows, different field configurations and even different management screens. Conceptually, then, these concepts are organised as in the following picture:

The semantics and the behaviour of a concept can then be configured, customised and fine tuned at the project level by means of schemes.

The Importance of Schemes

Schemes probably are the biggest source of confusion for a novice JIRA administrator. At the beginning things may seem to work without the need of bothering with them. When the number of projects starts to grow, the possibility of configuration clashes grows too and that's when an administrator realises that the lack of a proper scheme partitioning is the source of all evil. Redesigning a JIRA configuration for a great number of projects is not easy and having projects polluted by configurations specific to other projects will make your users complain.

Schemes insulate projects from one another: a proper JIRA schemes' configuration guarantees that every manager can have its project configured with its own requirements without affecting other projects, even in the case in which they might be sharing some common concepts (such as an issue type defined at a corporate level.)

If in doubt, always create a scheme. If in the future apparently similar project configurations starts to diverge, schemes will enable you to independently manage different project.

JIRA Makes It Easy

Abstraction, decoupling and flexibility all come with a price: the administrator has to define configurations, schemes and associate them with a project. Fortunately, JIRA makes it easy since configuration and scheme can usually be copied: instead of starting from scratch, you can copy a scheme or a configuration and using it as a starting point for your new setups.

Types of Schemes

A JIRA scheme exists to map a project to almost any kind of concepts managed by JIRA:

• Workflow schemes.
• Issue type scheme.
• Issue type screen scheme.
• Issue security scheme.
• Field configuration scheme.
• Screen scheme.
• Notification scheme.
• Permission scheme.

In this series of posts we'll explore every kind of scheme, their relation between the project and the concepts they configure, and how they can be used.

In this part we'll explore the following types of JIRA schemes:

• Issue type scheme.
• Issue type screen scheme.
• Field configuration scheme.
• Screen scheme.

Issue Type Scheme

The first scheme you'll probably start with during the configuration of your JIRA project is the Issue type scheme. The issue type scheme establishes the relation between a project and the available issue types.

An Use Case

An issue type scheme is necessary when the default JIRA issue types are not sufficient for your project. Let's suppose your project will need additional issue types such as:

• Risk.
• Deliverable.
• Payment.

To safely add these new issue types with your project, you have to create the required issue types and associate them to the issue type scheme used by your project.

How to Setup Issues for Your Project

To setup the issue types you'd like to use in your project, you must perform the following operations:

• Define the issue types you need (if they do not exist yet).
• Create an issue type scheme for your project.
• Configure the issue type scheme to contain all the issue types to use in your project.
• Associate the issue type scheme with your project.

At this level, the selected issue types for your project are just names. During the configuration of the next schemes we'll give these names some meaningful behaviour.

What If I Use The Default Issue Type Scheme?

Since all issue types are implicitly associated to the default issue type scheme, if you modify it every project that is not associated with a custom scheme will see such modifications. If you're asked to setup a new JIRA project that will need a new issue type, that issue type will show up in every other project that is using the default scheme: that will probably make no sense to your users.

Field Configuration Scheme

The field configuration scheme establishes a relation between issue types and field configurations:

A field configuration scheme has a special default entry to map a field configuration to any unmapped issue type.

Field Configurations

A field configuration defines a field's behavior and is commonly used to tell JIRA:

• Whether a field is required.
• Whether a field is visible or hidden.
• How a field is rendered.

An Use Case

Field configurations and field configuration schemes are necessary whenever your issue fields behavior have to be customized. By default, every new field is visible and optional. If you need a field to be required or to be hidden for a given issue type, a field configuration scheme is required to map the affected issue types to the desired field configurations. A new Amount field, for example, might be required and visible only for the Payment issue type. Any screen for every other issue types should not require nor show the amount field.

How to Setup a Field Configuration Scheme for Your Project

With a field configuration scheme you can setup the behavior of every field, for every issue types it applies to:

• If applicable, define a field configuration that will apply to any unmapped issue types. A good starting point might be a copy of the default JIRA field configuration.
• Define a field configuration for every issue type that needs one. Many issue types can share the same field configuration.
• Create a field configuration scheme and associate the field configurations you created to the target issue types.
• Optionally, define the default field configuration for all of the unmapped issue types.
• Associate the field configuration scheme to your project.

What If I Use The Default Field Configuration Scheme?

Using the default JIRA field configuration scheme and the default field configuration may lead to configuration clashes such as the following:

• If a project requests a field to be hidden, every other project that might still require it will see the field disappear from its screens.
• If a project requests a field to be marked as required, every other project will be forced to set a value for such a field in its screens.

Screen Scheme

JIRA lets the user easily define new windows, called screens, that may be used during a workflow transaction or during an issue type operation such as create, edit and view.

A screen scheme establishes a relation between an issue operation and a screen. A screen scheme has a special default entry to map a screen to any unmapped issue operation.

Screens

A screen is just an ordered list of fields easily configurable with the JIRA administration console. The field rendering and behavior, such as its format or whether it's required or visible, is configured by a field configuration.

An Use Case

A custom screen it's necessary, for example, when you want to control which fields are visible or editable during an issue operation and when you need a brand new screen for a transition in a workflow of yours.

For a Payment issue type, for example, it might be desirable that some fields (such as Amount) should not be visible or editable during the edit operation. In this case, it's necessary to define a new screen that contains the editable fields and associate it with the edit operation in a new screen scheme. This screen scheme will then be associated with the target issue types by means of an issue type screen scheme that will be examined in the next section.

A Payment issue type might then be associated with a user-defined workflow. During a specific workflow transaction, such as Pay, it might be necessary to update another custom field: Payer. In this case, it's necessary to define a new screen that contains the Payer field and any other required field and associate it with the desired workflow transaction.

How to Setup a Screen Scheme for Your Project

To configure a screen scheme to use in your project you have to follow these steps:

• Define a screen for every customised issue operation screen that your project needs.
• Create a screen scheme.
• If applicable, define a screen for every unmapped issue operation.
• Associate the screens you created with the corresponding issue operation.
• Repeat this operation and create screens and screen schemes for every issue type whose operations need screen customisations in your project.

What If I Use the Default Screen Scheme?

Since the default JIRA screens are associated to all issue operations for every issue types, a modification in either the default screens or the default screen scheme will be visible in all the projects that don't use custom screen schemes. This situation may lead to complaints for missing or new and unknown fields in screens used by other projects.

Issue Type Screen Scheme

An issue type screen scheme establishes a relation between a screen scheme and an issue type. An issue type screen scheme has a special default entry to map a screen scheme to any unmapped issue types.

An Use Case

The issue type screen scheme is mostly a "technical" scheme to tell JIRA to use a screen scheme for a specific issue type in a project. Common use cases have been explored in the previous section.

How to

To setup an issue type screen scheme for your project you have to follow these steps:

• Create a new issue type screen scheme.
• If applicable, associate a default screen scheme for every unmapped issue types.
• Associate a screen scheme to every issue type whose screens you need to customise.
• Associate the issue type screen scheme to your project.

What If I Use The Default Issue Type Screen Scheme?

Since the default issue type screen scheme just maps the default screen scheme to any issue type, using this scheme in every project will have the same detrimental effects on project decoupling that we outlined in the previous section.

Conclusions

In the first part of this series, we've explored a basic component for the JIRA customisation: schemes. Schemes are a flexible mean to decouple configurations from their scope (projects). Although you might be tempted to ignore custom schemes and just modify JIRA default schemes, I suggest you think it twice, take a large breath, reread this post and convince yourself that it's really a bad idea.

JIRA helps the administrator build schemes quickly allowing him to generate copies of existing schemes on the fly. Create a test project and start configuring it copying JIRA default schemes and modifying them. You'll be surprised by discovering how powerful and easy it is.

Next Steps

In another post (coming soon) I'll explore other types of JIRA schemes with particular emphasis to workflows and their customisation.