jira-custom-workflow-tutorial
Image: BalanceFormCreative/Adobe Stock

What is Jira?

While originally designed as a bug tracker, over the years Atlassian’s Jira has become the 900 pound gorilla in the enterprise for managing software development projects.

There are a number of reasons for that popularity, from its pivotal role in Atlassian’s larger DevSecOps toolchain, to the extensive number of third-party plugins available through Atlassian’s marketplace. One contributor to that popularity is the flexible way Jira handles workflows, allowing teams to adapt the tool to the way value moves through their workstream, versus modifying the way the team works to align with the tool.

SEE: Hiring kit: Back-end Developer (TechRepublic Premium)

What’s a workflow?

In software development, a workflow defines the steps and statuses that tasks move through as a part of a team’s process. Out of the box, Jira provides a three step simple workflow (Figure A).

Figure A

jira-workflow-bill-2
Image: Bill Francis/TechRepublic.

You can imagine if you were developing, say, a mobile ordering app for a quick service restaurant, and your team was tasked with adding the ability to accept credit card payments, how this work might flow from left to right.

Your product owner would write up the requirements, and when it was ready, place the task to implement this feature in To Do. A developer would then start working on this feature marking it In Progress. When she completes that work, the build gets handed to a tester. If everything works as expected, the tester moves the task to Done.

Throughout the process, Jira provides visibility to all the stakeholders who aren’t in the code, in effect allowing a project manager to keep up with schedule and indirectly budget.

How software gets developed

In reality, software development is not a linear process. It has starts and stops and often has to repeat steps of the process until the desired result is achieved. Even our simple out of the box workflow doesn’t actually just flow from left to right. Here’s a more realistic representation of how tasks flow across even the simplest of Jira workflows (Figure B):

Figure B

jira-workflow-bill-3
Image: Bill Francis/TechRepublic.

Key workflow components

Before we get too deep into what’s an ideal workflow and how to create it using Jira, it’s important to level-set on the key components of a workflow as defined by the tool.

Status

This is the current state of a discrete work item. In our simple workflow, a task is either To Do, In Progress or Done.

Transitions

These are the actions taken in the tool to move a task from one state to the next. In our example, the act of assigning something in the To Do state to a developer might transition that item to In Progress.

Resolution

When a task is finally completed it needs some associated resolution. The resolution is the disposition of the final state of a work item. It’s considered finalized or no longer open. In our simple workflow, this is Done, but in a more advanced workflow, you may have other resolutions possible such as Canceled or Published.

Boards

The majority of software teams today using Jira for project management are managing their projects using some form of agile development. This means – in a group setting – the team frequently works from some kind of board, typically kanban or scrum. It should come as no surprise then that workflows in Jira correlate to the columns on your boards.

Recommended software development project management workflow

There are no right or wrong answers for what your software development project management workflow should be in Jira. Workflow can vary, even within a team, for different types of tasks.

For example, the workflow of a software bug is likely going to be different than that of a new feature. Even with slight naming variations to align with your organization, there are some best practices you can look to for guidance.

Categories

A category is one of the most important and often overlooked, properties of creating a project management workflow in Jira. Within Jira there are only three categories, and you’ve already seen them (Figure A).

In the simplest, out of the box workflow, categories and statuses are the same. However, as we build out and customize our workflow, all new statuses must map to one of these three categories. Why? For reporting and automation. Jira has a number of canned reports, like the burn down, that only function if regardless of how many states you add to your custom workflow, everything maps back to one of these three preordained categories (Figure C).

Figure C

jira-workflow-bill-1
Image: Bill Francis/TechRepublic.

Backlog

This is the rough list of all the known work your team has sorted in priority order. All tasks that enter the workflow start in the backlog.

To do

Once sufficient requirements are gathered and a task is deemed ready, it gets moved into the To Do state where it is available for a developer to begin coding.

In progress

As the task is being completed by the developer, it is considered in progress. When the developer finishes the task to his satisfaction, he will move it to Test.

Test

As a best practice, a developer doesn’t test his own work. So items marked as Test are undergoing evaluation by another team member, usually a quality assurance engineer or the product owner, to ensure all the acceptance criteria are met.

Done

Tasks that successfully pass the test phase get resolved with a status of Done.

Canceled

If for any reason from the time a task enters the backlog, up until the time it is marked done, the team decides the work won’t be completed it gets resolved with a status of Canceled. This ensures we can track that the task was considered, and in some cases started, versus just deleting it which would provide an incomplete picture down the road.

Blocked

At any point once the work begins if a team member can’t continue working on the item, it gets moved to Blocked. The intent here is to draw attention to an item that was committed to and now not being worked on so that the team can swarm around the issue and get it unstuck.

How to configure Jira

Creating the workflows in the Jira tool itself is fairly straight-forward and can be found on the Atlassian site.

Note that workflows get created differently depending on whether you have a “company-managed” project or a “team-managed” project. If you aren’t sure which applies to you, look at the lower-left corner of your project sidebar. It should either say “you’re in a team managed project” or “you’re in a company-managed project.”

Once you are satisfied with which type or project you have, follow the appropriate links on the Atlassian support page. If you aren’t quite sure you want to tackle setting up your own project management workflows for software development, consider a plugin from Atlassian’s marketplace to do it for you.

4 tips for creating custom Jira workflows

When setting up your workflows, keep in mind these tips.

  • Don’t overthink it: The simpler the better.
  • Group categories: It’s generally bad practice not to have all your In Progress steps together as it impacts your ability to measure cycle time.
  • Consult all your stakeholders: The idea is to create workflows that meet everyone’s needs.
  • Lean into your transitions: This will allow you to create validation steps, automation rules and even control assignees.

Subscribe to the Developer Insider Newsletter

From the hottest programming languages to commentary on the Linux OS, get the developer and open source news and tips you need to know. Delivered Tuesdays and Thursdays

Subscribe to the Developer Insider Newsletter

From the hottest programming languages to commentary on the Linux OS, get the developer and open source news and tips you need to know. Delivered Tuesdays and Thursdays