situ

In the first part of this tutorial we learnt the importance of JIRA schemes and how to configure some of them:

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

In the second part of this tutorial we'll discover other types of schemes that JIRA provides to fine tune our projects:

Permission scheme.
Issue security scheme.

In this part we'll discover what workflow schemes and notification schemes are and how to use them.

Workflow Scheme

A workflow scheme let an administrator establish a relation between an issue type and a workflow and it has got a special entry to assign a workflow to all unmapped issue types as well.

What A Workflow Is

The concept of workflow is central in JIRA and it's where most of JIRA power resides in. Let's start with an example: in your project you define a couple of custom issue type called risk and documentation. So far they're just a name: a moniker that helps you categorize your projects issues into named sets but with no additional value. The next thing you'd probably do is to define custom fields for the new issue types of your projects to store the additional data you might need (such as a document author, a document title and so forth.)

As soon as you start using the new issue types in your project you'll realize (or your users will do) that it's not very intuitive to open, resolve and close a document (or a risk). Moreover, users will start complain that some operations are missing: reviewing a documentation, escalating a risk, etc.

JIRA workflows solve this problem: they let you define the process which an issue (of a specific type) will go through. The process is modeled as a finite state machine with transitions between state where you can even hook security policies and business rules (conditions and validators).

Additionally, JIRA will let you specify other information that will let you glue together the features that JIRA offers (such as screens) to fine tune your project and provide your users the interface they expect.

An Use Case

For the sake of simplicity we'll start with a very simple example. Let's suppose that you've got a dependency with a third party that, sometimes, takes charge of an issue for part of its lifetime: it might be, for example, the software quality assurance department of your organization to which your code changes are submitted for validation. Then, you might want to put issues in a waiting state to explicitly reflect this fact.

A goot starting point to implement this custom workflow is copying the default JIRA workflow and using it as a starting point. The modifications you'll need to apply to the default state machine are:

Create a new state: Waiting for feedback.
Create new transitions to the new state:

Ask feedback transition from the In Progress state to the Waiting for feedback state.

Create new transitions from the new state:

Continue transition from the Waiting for feedback state to the In Progress state.
Resolve Issue transition from the Waiting for feedback state to the Resolved state.
Close Issue transition from the Waiting for feedback state to the Closed state.

The resulting steps are shown in the following picture.

Screens for Transition Views

When you toggle the state of an issue, you can assign the transition a screen that will be presented to the user. You can choose one of the bundled JIRA screens or create a screen of your own. If during a transition you want the user to input some additional data, a transition screen is the place where you can ask the user to do so.

For the new Resolve Issue transition, for example, I replicate the settings in the default JIRA workflow Resolve Issue transition, that is using the Resolve Issue Screen during the transition.

Conditions

Conditions are propositions that must hold for the transition to complete successfully. Conditions, for example, are often used to create a security policy for a workflow transition. Some of the conditions that JIRA offers are:

Only assignee
Only reporter
Permission
User is in group
User is in project role
User is in group custom field

In this use case, for example, we want the Ask feedback and Continue transitions to be initiated only by the current assignee of an issue:

In the case of the Close Issue and Resolve Issue transitions, we replicated the conditions on the corresponding default JIRA workflow transitions, that is, check if the user has got the Close Issue permission or the Resolve Issue permission.

How To Create a Workflow

To create a workflow you've got to:

Define the state machine for you workflow.
Create a new workflow or copy an existing workflow that could be used as a starting point.
Implement the state machine adding all the states you defined and all the possible transitions between the states.
Optionally define and assign the screens you need to display during the workflow transitions.
Define the conditions that must hold for a each transition to complete: pay attention to take into account JIRA standard permissions (such as the Close Issue and Resolve Issue) in the conditions for your transitions.

How To Create a Workflow Scheme

Before creating a workflow scheme, all of the required workflows for the issue types you're going to manage in a specific project must have been prepared. To create a workflow scheme, you've got to:

Create a new workflow scheme.
Assign the default workflow to be used for unmapped issue types.
Assign a workflow to every issue type whose state machine you want to modify in the current scheme.

Apply the workflow to a project and the modification will take effect.

Please note that changing the workflows that are used in a project with existing issues is a potentially disruptive task that must be performed with care. Changing the workflow for an issue type might require mapping existing issues that find themselves in states that are no longer valid to valid states of the new workflow. JIRA will detect such conflicts and will ask the administrator to establish these mappings when changing a workflow or a workflow scheme for a project.

Best Practices

Hopefully, JIRA won't even let you modify the default system workflow (unless you hack it). Different projects usually mean different users and, although the words we use might be the same, the meaning we give them might differ a lot so the recommendation is the same: always create a custom scheme for your project when in doubt. It's easier to consolidate multiple equivalent schemes into one than decoupling projects that share schemes that were supposed to never change. JIRA lets you copy many of the objects it manages including workflow and workflow schemes.

Notification Schemes

JIRA can notify users when some event has happened. The notification scheme establishes a relation between the type of event and the users who will receive a notification.

Event Types

Some of the types of event that JIRA offers are:

Issue Created.
Issue Resolved.
Issue Closed.
Work Logged On Issue.

The complete list can be checked in the official JIRA documentation. JIRA also offers a Generic Event that can be fired, for example, from a workflow transition, that can be used to extend the set of JIRA events should you need a new one.

Users Who Can Receive Notifications

The identities whom JIRA lets you send notification to are:

Current Assignee.
Reporter.
Current User.
Project Lead.
Component Lead.
Single User (chosen from a list).
Group (chosen from a list).
Project role (chosen from a list).
Single email address (input by the user).
All Watchers.
User from a custom field.
Group from a custom field.

An Use Case

Let's suppose that you're a project or a component leader and you want to receive a notification every time an issue is resolved or closed: it will be sufficient to create a custom scheme, for example by copying JIRA default notification scheme, and adding a notification for the desired event to the appropriate receiving identity.

How To Create a Notification Scheme

To create a notification scheme it's necessary to perform the following operations:

Create a new notification scheme or copy an existing one to use it as a starting point.
For every event you wish to handle, add a notification and assign the set of receiving identities.

A notification scheme can be associated to a project and it will take effect immediately.

Tuesday, 16 November 2010

Atlassian JIRA Configuration Tutorial: JIRA Schemes (Part 2)

In the first part of this tutorial we learnt the importance of JIRA schemes and how to configure some of them:

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

In the second part of this tutorial we'll discover other types of schemes that JIRA provides to fine tune our projects:

Permission scheme.
Issue security scheme.

These schemes are used to tune the security policies you may want to establish over your JIRA instance, your projects and the issues they manage.

Before You Start

If you haven't done it yet, please read: Atlassian JIRA Configuration Tutorial: Overview of JIRA Security.

Permission Scheme

An introductory discussion about JIRA security and JIRA permissions is the subject of another blog post.

A permission scheme defines a the set of permissions to apply to a project.

An Use Case

The default JIRA permission scheme distinguishes between the following project roles:

Administrators
Users
Developers

Users are granted the right of submitting issues into project (Create issues, Create comments, etc.) while developers are granted the right of working on issues and take them into completion (Edit issues, Close issues, etc.).

This is a starting point for refining your security policies adding actors (a project role) in your process and assigning them permissions. A first refinement might be requiring a project manager to check the developers' work on an issue before transitioning into the Closed state and letting developers transition an issue only up to the Resolved state.

How To Setup a Permission Scheme for Your Project

To setup a permission scheme for your project:

Define the project roles your project needs: this is an optional step, since you can assign permissions to users and groups, but it's desirable to clearly organize JIRA users in sets (project roles) according to their status in each project.
Assign users and groups to your project roles.
Create a permission scheme for your project (possibly copying an existing permission scheme).
Assign permissions to users, groups and project roles in the permission scheme.
Assign the permission scheme to your project.

Issue Security Scheme

As we've seen in another post of this series, issue security scheme let administrators establish security policies to protect issues in a project. An issue security scheme defines a set of security levels and grants permissions to a set of identities to access issues in a given security level.

An Use Case

Issues in your projects could be organized in security level so that the visibility of certain issues is reduced to a subset of the users that can access a project.

In another scenario you could be sharing a project with some of your clients and would not like a client of yours having visibility of all of the issues managed in that project for confidentiality reasons.

An issue may be changing security level according to the workflow transitions it performed: just after creation, an issue could be transitioned to another security level so that a subset of users (such as a group of developers) might asses the issue and decide what to do with it. In a later time, the issue can be transitioned to another security level to be available to a wider audience.

How to Setup an Issue Security Level for Your Project

To setup an issue security scheme for a project of yours you have to:

Create a new issue security scheme.
Define the number of security level your project needs and create them in the issue security scheme.
Grant permissions to a set of users for every security level in your scheme
Assign the issue security scheme to your project.

Next Steps

In the following part of this series we'll explore the last two kinds of schemes that JIRA provides: the workflow scheme and the notification scheme.

Sunday, 14 November 2010

Atlassian JIRA Configuration Tutorial: Overview of JIRA Security

JIRA flexibility is notorious and its security features are no exception. This blog post is an overview of JIRA security features and how to configure permissions to secure JIRA, your projects and all of your issues.

Users, Groups and Project Roles

At the global level, JIRA organizes users into groups and project roles. Groups are named sets of users and project roles are named sets of users and groups:

The administrator can create, edit an delete any number of users, groups and project roles.

Although, at first, the existence of both groups and project roles might seem redundant, project roles are important since they provide an additional level of indirection to decouple permissions from user accounts in a project. JIRA permissions at the global level (Global Permissions) can only be granted to groups. JIRA permissions at the project level can be granted at any combination of users, groups and project roles. An effective organization of your users (and groups) into project roles will help you create and maintain clean security policies in your project by:

Defining the project roles you need.
Assigning permissions to your project roles in a permission scheme.
Assign a permission scheme to a project.

At the global level, to ease administration of a great number of projects, JIRA lets you define a project role's default members.

Global JIRA Permissions

Global JIRA permissions are (as of JIRA 4.2):

JIRA System Administrators.
JIRA Administrators.
JIRA Users.
Browse Users.
Create Shared Objects.
Manage Group Filter Subscriptions.
Bulk Change.

Most of them are self-explanatory and further information about each of them can be found in the official JIRA documentation.

JIRA Users

This permission is required for users to be able to log in into JIRA. By default, groups that are granted this permissions will be assigned to any newly created user.

Disabling an User

Revoking this permission to an user, that is removing the users from every group that is granted the JIRA Users permission, will effectively disable the user and it won't count against your JIRA license limit.

Project Permissions

Project permissions are defined by JIRA and can be granted to an identity in a permission scheme. Assigning a permission scheme to a project will make those permissions effective in that project context.

Examples of most commonly used permissions are:

Administer project
Browse project
Create issue
Edit issue
Resolve issue
Close issue
Add comment
Delete comment
Work on issues

For the complete list of permissions for a given JIRA version please check JIRA documentation or navigate to the Edit Permissions window of your JIRA installation accessible at the following URL:

http://your.jira/secure/admin/EditPermissions!default.jspa?schemeId=0

Further information about assigning project permissions to users, please check out this blog post.

Securing Workflow Transitions

The permissions seen so far make no mention of workflows and workflow transitions. Obviously, workflows are a fundamental part of JIRA functionality and it's essential for an administrator to be able to establish security policies at the workflow transition level.

Permission requirements can be associated to workflow transition using Conditions.

Conditions

Conditions essentially are validation rules that must be satisfied for a workflow transition to be executed. JIRA ships many built in conditions and many of them can be used to establish fine tuned security policies at a workflow transition level. The available security-related workflow transition conditions are (as of JIRA 4.2):

Only assignee.
Only reporter.
Permission.
User in group.
User in group custom field.
User in project role.

These conditions can be used to build security policies using any kind of identity seen so far: group and project role. Moreover, other identities related to a specific issue are available such as assignee and reporter.

Conditions are basic JIRA-provided parametrizable propositions that can be used to build more complex statements using the JIRA administration console as shown in the following picture:

Validators

Validators are similar to conditions with the difference that validators are executed against input parameters. As far as it concerns security policies, conditions is the way to go. Anyway, a Permission validator is available to check if the current user has a specific permission.

Securing Issues in a Project

We've seen many ways an administrator can secure its JIRA installation so far: at the global level, at the project level and at the workflow transaction level. There's case we haven't considered yet, though: applying distinct security policies to issues inside a project.

To achieve this goal in a flexible way, JIRA provides the ability to categorize a project's issues in the so-called security levels. A security level is an attribute of an issue that can be set in the usual ways:

By using a screen that configured to edit such a field.
By a workflow transaction.

An issue in a security level can be accessed only by identities (users, groups or project roles) that are granted permissions. The link between a security level and the identities that are granted access is established by means of an issue security scheme.

As usual, as soon as a project is associated to a security scheme, the scheme security policies are enforced. You can now create as many security level as your project needs and grant permissions to the corresponding users for every security level.

The available identities to grant permissions to in a security level are:

Reporter.
Group.
Single User.
Project Lead.
Assignee.
User custom field value.
Project role.
Group custom field value.

Next Steps

In this blog post we've introduced the facilities that JIRA provides to secure the operations it offers and the object it manages with flexible security policies.

In the next part of this series we'll examine what JIRA schemes are and how they can be used to decouple configurations from the context in which they are applied.

Thursday, 11 November 2010

Atlassian JIRA Configuration Tutorial: JIRA Schemes (Part 1)