Exploring Jira Workflow

Working with any tool for the first time can be daunting. Researching it and watching tutorial videos is a good start, but finding yourself surrounded by a huge pile of documentation is its own hurdle. This is a quick, practical summary of how workflows work in Jira, along with the reporting options. It assumes no prior Jira experience.

A note on naming: Atlassian has renamed several of these products over the years — Jira Software and Jira Service Desk are now Jira and Jira Service Management, and the styling is “Jira” rather than “JIRA”. The concepts below are unchanged; only the labels and the screens have moved.

What is a workflow in Jira?

A workflow is a series of sequential steps that need to be completed in order to reach a certain goal. In Jira specifically, a workflow is a set of statuses and transitions that an issue travels through during its lifecycle, and it normally represents a real process inside your organisation.

The simplest version has three states: create the issue, work in progress while it is being fixed, and closed once it has been verified.

It helps to separate the two building blocks clearly, because people mix them up constantly:

• A status is where an issue currently is — To Do, In Progress, In Review, Done.
• A transition is the permitted move between two statuses. Transitions are where the logic lives: who is allowed to make the move, what must be true first, and what happens automatically as a result.

There is also a third concept worth knowing early: the resolution. An issue can be in a Done status without having a resolution set, which is the single most common cause of “why is this still showing in my backlog?” Make sure a resolution is set on transitions into your done statuses.

Team-managed vs company-managed projects

This distinction did not exist when this post was first written, and it changes almost everything about how you edit a workflow — so it is worth understanding before you go looking for a setting you cannot find.

• Team-managed projects are configured by the project’s own administrators. Workflow editing is simpler and self-contained, and changes only affect that project. Good for autonomous teams.
• Company-managed projects use shared schemes administered centrally. More powerful and more consistent across an organisation, but changes can affect many projects at once and usually need a Jira administrator.

If a tutorial’s instructions don’t match what you see on screen, this is usually why.

Working with workflows in Jira

There are pre-defined built-in workflows that can’t be edited directly; you copy one and adapt it to create your own.

Some advice before you start editing: resist the urge to model your process in full.

New administrators tend to build elaborate workflows with fifteen statuses and conditional routing, and then discover the team quietly stops updating tickets because it is too much friction. Start with the simplest workflow that reflects reality and add states only when the absence of one is causing a genuine problem.

Limitations when editing an active workflow

When you edit the draft of a workflow that is already in use, some limitations apply:

• The workflow name cannot be edited
• Existing statuses cannot be deleted
• If a status has no outgoing transitions, none can be added — regular or global
• The step ID cannot be changed

The workflow designer

The workflow designer is a graphical tool that lets you see the layout of your workflow and create or modify its steps and transitions. You can add statuses and transitions, drag them around, and edit their properties to rename or delete them.

You can also add a global transition, which allows any status in the workflow to move to a selected status — useful for something like Cancelled, which should be reachable from anywhere. You can change the screen a transition uses, and configure advanced options: conditions, validators, post functions and triggers.

Those four advanced options are worth distinguishing, since the names give little away:

• Conditions decide whether the transition is even shown — for example, only a project lead can move an issue to Approved.
• Validators check the transition is allowed to complete — for example, a fix version must be set before an issue can be resolved.
• Post functions run automatically after the transition — setting the resolution, assigning the issue, updating a field.
• Triggers fire the transition from an outside event, most commonly a linked commit or pull request in your source control.

Two workflow examples worth copying

A simple software delivery workflow

Much of what used to require post functions can now be handled more readably through Jira’s automation rules, which sit outside the workflow and are far easier to audit and change. If you are building something new, look there first.

To Do → In Progress → In Review → Done, with a global transition to Blocked and back. Set the resolution on the transition into Done. This covers the needs of most delivery teams and is easy for everyone to follow.

A bug workflow with verification

Open → In Progress → Ready for Test → Verified → Closed, with a transition from Ready for Test back to In Progress for failed verification. Add a validator so an issue cannot reach Verified without a tester assigned.

How does a service desk work in Jira?

Customers and agents work together to resolve a request like this:

• The customer submits a request through a portal or by email
• Agents see the request in their queue and investigate
• The customer and other participants discuss the request through the portal or by email, while the agent works in the tool
• The agent completes the request

Service management workflows differ from delivery workflows in one important way: they are usually governed by SLAs, so the time an issue spends in each status is itself measured. That makes the design of “waiting for customer” states genuinely consequential rather than cosmetic.

Reports in Jira

To find reports, go to the board and open the Reports section, then switch between report types from there. Jira provides different reports within a project to show statistics across the lifecycle — some for analysing issues, and others specific to Scrum and Kanban.

Kanban projects: Control chart, Cumulative flow diagram.

Scrum projects: Sprint report, Control chart, Burndown chart, Cumulative flow diagram, Epic report, Release burndown, Velocity chart, Version report.

Issue analysis: Average age report, Created vs resolved issues, Pie chart, Recently created issues, Resolution time, Time tracking, User workload, Version workload, Workload pie chart.

If you only ever look at two, make them the cumulative flow diagram and the control chart. The burndown tells you whether you are on track this Sprint; the cumulative flow diagram tells you where work is actually piling up, and the control chart tells you how long things really take. The second pair changes how you run the team; the first mostly just reports on it.

Where to go next

If you are new to the tool more broadly, start with an introduction to Jira and the post on issues and issue types. Once you are comfortable with workflows, creating release notes in Jira is the natural next step. And if the question behind your search was really about ways of working rather than the tool, read “Are Jira and Agile the same thing?” — a tool does not make a team Agile.

No matter the ever-changing dynamics of my life, it has been your comments and reviews on my blogs that keep me going. Your support and suggestions are welcome.