Changing Issue Trackers: Meeting & Understanding the Beast

We recently switched issue trackers—and while a feat in and of itself—half the battle was getting our arms wrapped around the replacement… JIRA. When discussing the topic with one of our clients they remarked, “JIRA gives you sooooo much rope, it’s almost impossible not to hang yourself with it all!”

JIRA is a beast.

It’s completely customizable and can handle infinite, complex layers of permissions, users, work-flows, fields, types and flavors of ice cream. And like a teenager in a sports car, that power is easily used to everyone’s detriment.

JIRA’s flexibility makes it one of the most difficult (if not the most difficult) issue tracker to setup. Most software comes with defaults. Your phone for example, from the moment it emerges from the plastic wrap, will ring using a default ring tone. A background or color theme is selected; your carrier’s help line is programmed into the address book; etc. If JIRA was a phone, it would come in a sofa sized box full of random parts; block letters across the top reading, “Team Lift, Assembly Required.”

Hence what prompted this post. Getting my head wrapped around JIRA and getting it to work for-and-with us; not against us, feels about like I imagine summiting Everest feels… maybe not as cold, but similar otherwise.

To follow I’ll do my best to break-down JIRA into understandable bits… taking the sofa sized box of parts and placing each part into neat piles.

What I won’t do is go over how to use JIRA. I won’t review how to use search, or GreenHopper, or navigate issues. There is plenty of documentation out there on all of that—I plan to fill the void I found when using JIRA; understanding it well enough to set it up for use.

Some issue trackers call issues, issues; some call them bugs; some tickets. Here within, when I say “issue”—I mean the ticket that represents a task.

Getting There

I’ll save you the trouble of figuring out where all this crap in JIRA lives. After logging in, click Administration, a link on the far right of the screen by your name. Everything I describe lives in this Admin land somewhere in the convoluted menu.

Like a lions den, these doldrums are damp and scary and confusing; but over time you learn your way around and end up calling it home.

JIRA Hierarchy

All issue trackers have some form of hierarchy that enables you to organize issues in a way that resembles your business. For us, our clients are the parent-hierarchy—followed next by projects or budgets. In other words, every issue can belong to both a budget and a client.

Those who only have internal projects, your highest hierarchy may be departments (marketing, sales, quality, etc.) or product lines (line ‘x’, line ‘y’). JIRA is again flexible and customizable—but without doing too much tweaking here’s how JIRA outlines issues.

• JIRA Account (OnDemand or self-hosted; the constraint here is who you give access to)
  • Project (We created one for each client—our highest level of hierarchy in our business structure)
    • Versions (We created a different one for each client’s project and/or budget)
    • Component (This is a way to categorize within versions at the same hierarchy—for example ‘architecture’ or ‘database’ is a component that multiple versions could belong to)
      • Standard Issue (This is as deep as some may need to go. This is the actionable, assignable issue)
        • Sub-issue (This is a way to categorize tickets under a larger issue. For example, we created the issue types Epic [issue] and Sub-epic [sub-issue])
          • Labels, External ID, etc. (These are other fields that you may or may not choose to use; but each are fully supported in JIRA’s powerful search and filtering. For example, you might label all tickets within a version with the type of work, skill set needed, etc.)

Workflow, Status and Transitions

In JIRA, workflow is the path an issue travels along. Issues travel from stop-to-stop along transitions; and stops are called status. You can create as many types of workflows as you like; the issue type is what determines which workflow an issue follows.

Read that last sentence again; the issue type is what determines which workflow an issue follows.

The default work-flow in JIRA is fairly simple and may be all that is needed for some users (above).

Here status is represented by the gray boxes with icons (Create Issue, Open, Resolved, etc); and transitions the blue boxes that label arrows between statuses (Resolve Issue, Close Issue, Reopen Issue, etc). Users can create more transitions or statuses depending on their needs.

Tips

• Being a visual person who loves flow-charts; I found the Workflow Designer (pictured above) the easiest way to create workflows rather than using Edit Workflow Steps (below, which is an outline or list view of the same thing).
  
• You cannot edit a workflow that is assigned to a project; you’ll notice a theme here with every aspect of JIRA. Bottom-line, assign attributes to projects last. Once assigned, most cannot be edited.
  • If you make a mistake and need to change a scheme later, then (1) make a copy of the existing attribute (workflow scheme); (2) assign all projects from the original attribute to the copy (so nothing changes but the name); (3) make your changes to the original; and then (4) move all the projects back over.

Creating a workflow will be the most difficult step in setting up JIRA for many. My understanding was that we (Planet Argon) avoided the JIRA switch previously for this very reason.

JIRA forces you to use a workflow. Which means you’ll have to define your workflow. If you organization is currently hap-hazard and things happen on a whim and without process—you’ll struggle here. No doubt you can re-create any workflow no matter how complex (or crazy); but, you will have to recreate it in visual form. And if you have any desire to maintain usability, then you’ll need to define and reproduce your process in as consolidated and intuitive method as possible.

Things to consider

• Once up and running, those statuses you choose for your workflow show everywhere in JIRA. In search…
  
  and within tickets…
  
  Notice also that the version, priority, issue type, labels and resolution also show here.
• The transitions show within each ticket as buttons—which is how you move from status to status. So pick descriptive names.
  

Screens, Fields and Resolutions

This part doesn’t fit here nicely (in my opinion), but when you’re creating a workflow JIRA asks you to determine which screens show during transitions. When you click the transition button in a ticket, a pop-up screen appears that allows you to make changes before the notification goes out. This is important because you want the right fields to appear—those that correspond with your reasons for changing the status. For example, if you select a screen that doesn’t have an ‘assignee’ field for the transition of Open to In Progress… you won’t be able to assign the ticket in the same action as moving the ticket.

The screen is the pop-up window that appears. Screens are filled with fields. Both are customizable, you can create new screens and add dozens of custom fields (which may be a text box, radio button, drop-down, etc.)

JIRA comes with two screen schemes set as defaults (default and resolve). The default screen is filled with all but one of the default fields—resolution.

A resolution in JIRA is what separates open or in progress tickets from resolved or closed ones. When resolving or closing a ticket the transition must use a screen that includes the resolution field (the default resolution screen scheme does). Resolutions in JIRA default to fixed, duplicate, invalid, etc… again these can be customized.

Resolutions are important because of how they affect GreenHopper and search. For example, if I search for any ticket due by the end of the week [advanced search: duedate <= endOfWeek()] then my result may look like this:

But what I wanted was any ticket not ‘resolved’ and is due by the end of the week [advanced search: duedate <= endOfWeek() and resolution = empty]; which looks like this:

Ahh… much better—now I only see what I have left to complete.

When/if we get to prioritization—you’ll see that without resolutions your rapid and planning boards get messy quickly.

Deep Breath

Just writing all that down has my eyes crossed… good luck making sense of it. I kid; take a deep breath and re-read it. The stuff above is paramount and imperative to understanding the next steps (which are all easier and simpler… I promise).

Schemes (Workflow, Notification, Permission, etc.)

After you hammer out a workflow (or two, or three), you can’t actually assign it to a project until it belongs to a scheme. JIRA uses schemes to organize project attributes for easy assignment to projects. Using schemes means you can build a complex set of attributes, and instead of recreating it for each project, simply apply that same scheme to each project.

Schemes are used throughout for attributes and the hierarchy is similar for each. There are generally…

• Item available for customization (i.e. workflow)
  • Relationship (This is how that item ties back to the project. For workflows, it is issue type)
    • Scheme is a combination of types or relationships (i.e. a workflow scheme)

This combination allows the user to create maybe a dozen types of workflows; all relating to a specific relationship (issue type); and bottle them into a number of schemes used for a specific client/project/product lines. When you assign a workflow to a project, you’re actually assigning a scheme—not a specific workflow.

Users, Groups, Roles and Application Access

A user is the account used to login and out. Each user can belong to as many roles and groups as you see fit—but can only access those applications which they have access. Application access is how you control who has rights to use JIRA, JIRA plug-ins (GreenHopper, Tempo, etc) and ‘attached’ Atlassian products (Confluence, Bamboo, etc).

Groups are a way to organize users into a bunch (i.e. department ‘x’ group, manufacturing group, client ‘y’ group, project ‘z’ group, etc.). This comes in handy later when granting users access to specific projects.

Roles, unlike a group, come with privileges and permissions. For example, ‘administrator’ is a default JIRA role that gives a user admin rights. Another is ‘developer’ which gives a user more rights than the role ‘user’.

So to recap…

Taking our internal project as an example (above); under the People tab (blue) you can see that we have created the roles (green) which users (orange) and groups (purple) can belong to. Users (individuals, like Robby) can be set to belong to a role or group automatically. For example, our developer group has all of our developers in it—so instead of listing them out individually for every project for the development role, I only need to list the group ‘developers’.

Permissions Schemes

Permissions are outlined in a scheme—so multiple versions can exist of the same permission attributes. Roles and groups are given or excluded from particular permissions; with groups being JIRA wide, and roles project specific. Roles appear on every project and give you a slot to elect a user or group to fill that specific permission attribute.

The cool part here is that using roles, groups and schemes—you could give someone admin access to one project, view only to the next, and somewhere in-between in a third.

Tip
Every user has to belong to the ‘user’ group to have access to the application; but including the user group on a project means everybody who has a sign-in can see that project. When a project asks for users and groups for the role “user”—input a group you’ve created of select users. In my example above you can see I created the group “planet argon users”. Had I input “users” in the group column of the user role row; everybody with a login would have had view-only access of our internal project (which we don’t want, since we’re sharing our JIRA account with clients).

Notification Scheme

Notification schemes work just like permission schemes—so since you’ve got those dialed you should have no problem here. A list of notification attributes allow you to assign groups or roles to each; creating a scheme. That scheme is then assigned to a project. Pretty simple, eh?

That’s All Folks

That should help you loosely grip the greasy bowling ball that is JIRA. Obviously, this isn’t comprehensive—and as I mentioned above, not intended to teach you how to use JIRA, or how to set it up. The thing is, JIRA can be setup however you see fit—but an understanding is needed first.

I’ve considered walking through how we setup our account and why—but question what value the community would find in it. If you think it helpful; or have specific questions you can find me on on the Planet Argon website here.