Set up a workflow in a team-managed software project

Prerequisites

• You have a license to a Jira Cloud site.

• You have a license to Jira.

• You have the permission to create and administer team-managed projects.

Mission

You’re a project lead for a web development team that’s just started using Jira to track work. You need to get your team’s working process into Jira to get your project up and running.

Your mission is to:

• Draft and develop your team’s working processes.

• Translate those processes into your team-managed project’s workflow.

Introduction

Jira starts you off with the basic recommended workflow. Almost any task you take on can easily fit into its three statuses: to do, in progress, and done. But as your team grows and matures, you may want to categorize your work in more granular ways.

Some reasons for this may be:

• Your team has more roles and you want easier ways to hand off tasks.

• Your legal requirements require more review built into your workflow.

• Your team wants to report its progress in a more robust way.

Luckily, you can customize Jira workflows to fit almost any working process you can think of. Even though we’re using a small web development project as our example, what you learn here can be applied to any type of team.

If you already have a workflow in mind and you’re just looking for steps on how to translate it into Jira, skip to Getting it all into Jira. Otherwise, let’s get started on turning our team’s process into a workflow.

Gather your stakeholders

When creating a workflow, chatting with people who know your process may be a good idea. We’re going to talk to representatives from these roles in our web development team:

• Product owners

• Tech leads

• Web developers

• Quality assurance champions

• Web designers

We’ll have an informal chat with them and cover:

• What we’re hoping to accomplish (to get our web development project up and running).

• What involvement in creating a workflow will look like (to help us draft what our team’s working process looks like).

• How each member would like to be involved (do they want to get into the details or just be a reviewer?)

Takes notes, if you can. You can even use Confluence to keep these notes handy.

Draft and review your workflows

After talking to your stakeholders, you probably have an idea of what your team’s working process looks like. Before we get it onto paper, though, let’s learn about two important concepts in Jira workflows: statuses and transitions.

Statuses are the noteworthy points in your team’s working process. They help people understand the state of a piece of work and can represent handoffs in a team’s process. For example, you might have a new status when a task moves from development to quality testing.

Transitions are the pathways between statuses. They describe what’s happening when a task moves from one state to another. For example, when a tech lead approves development work after a code review, they might have a transition called ‘Approved’ that moves the task into the ‘Done’ status. Or if they reject the change, they might have a transition called ‘Fixes needed’ that sends the task back to the ‘In development’ status.

While drafting our workflow, we’re going to draw statuses as boxes and transitions as arrows.

To draft and review your workflows:

1. Get a whiteboard or your favorite whiteboarding app. Anything that lets you draw boxes and arrows on a blank space will work great.

2. For each of your workflows, draw boxes to represent statuses and arrows to represent transitions.

3. Gather your stakeholders again. Walk them through your draft processes and have them give you feedback. Don’t worry about getting things perfect for now. If something needs to change, it’s easy to adjust in Jira.

4. When your stakeholders are happy, open up your workflows to your team. They’ll be directly affected by your proposed workflows, so it’s great to get their opinion before making anything concrete.

Here’s how our web development team’s process turned out:

Getting it all into Jira

The first thing you’ll need is to get your awesome drafts into your Jira project. If you don’t already have one, creating a project is easy:

1. Choose the Jira icon > Projects.

2. Select Create project.

3. Under Software development, choose a Kanban or Scrum template and then select Use template.

4. Select the Team-managed project as your project type.

5. Give your project a Name, Access level, and Key.

6. Select Create project.

Don’t worry about getting the project template wrong. If you’re unsure, start small and go with a Kanban project. You can easily enable more powerful Scrum features by going to Project settings > Features.

If you’ve worked through this tutorial up to here, you should have:

• A team-managed project ready to be customized.

• The first draft of your team’s working processes.

Add your statuses

Now it’s time to add your statuses. In Jira, workflows are assigned to issue types (categorizations of your team’s work), so that’s where we’re going to add them.

To navigate to the workflow editor:

1. From the sidebar, select Project settings > Issue types.

2. From the sidebar, select the issue type whose workflow you want to change.

3. Select Edit workflow.

The workflow editor visualizes your issue type’s workflow by showing statuses and transitions in a flowchart.

Each status falls into one of three categories: ‘To do', ‘In progress’, and ‘Done’. You can add multiple statuses in each of these categories, but most projects get the most use out of the in-progress and done statuses.

To add a new status:

1. In the toolbar at the top of the editor, select a status category for the status you want to add.

2. Search for an existing status or type to create a new one.

3. Select Add.

4. Repeat steps 1-3 until all your statuses are in the editor.

New statuses will have a transition that allows issues in Any status to move to it. It’s usually a good idea to keep this transition so people can freely move their work. But if you have strict compliance guidelines, you might want to remove these transitions.

Add your transitions

Now that you have your statuses, it’s time to add how work moves between them by getting your transitions in.

To add a transition:

1. In the toolbar at the top of the editor, select Transition.

2. Select the start of your transition in the From status dropdown.

3. Select the destination of your transition in the To status dropdown.

4. Give your transition a name

5. Select Create.

Our web development team came out of this with this workflow:

Automate your workflow with rules

Rules automate things you’d normally do when transitioning an issue. You can restrict access to a transition, check details before transitioning, and perform actions after the transition. If you find yourself moving an issue to ‘In progress’ and assigning it to the same person over and over again, for example, Jira can automate that for you.

To add a rule:

1. In the toolbar at the top of the editor, select Rule.

2. Select the rule you want.

3. Select the transition you want to add the rule to.

4. Add the requested details and select Add.

Learn more about available workflow rules.

Here are the rules we’re going to add to our web development project:

Rule 1: Restrict who can move an issue

To ensure the quality of our code, we only want software engineers approving code and moving an issue past In code review. And to ensure the quality of our product, we only want quality assurance champions to move an issue past In staging.

In Jira, our disciplines are mapped to roles, including:

• Software engineer.

• Quality assurance.

Learn more about managing project roles.

Using the Restrict who can move an issue rule, we’re going to add these restrictions:

• For issues moving from In code review → In staging, restrict who can move the issue to the role Software engineer.

• For issues moving from In staging → Testing in production, restrict who can move the issue to the role Quality assurance.

Rule 2: Restrict to when an issue has been through a specific status

Our team wants to make sure our work has always been through the In staging status. If we don’t, then our work might be pushed out to customers without ever having been tested on real people. To ensure a high level of quality in our work, we’re going to make Jira test this for us.

To do this, we’re going to add the Restrict to when an issue has been through a specific status rule:

1. In the toolbar at the top of the editor, select Rule.

2. Select Restrict to when an issue has been through a specific status.

3. Select the Any status → Done transition.

4. Select In staging for which status it should go through.

5. Select the Include the issue’s current status option.

6. Select the Only consider the issue’s most recent status option.

7. Select the Ignore status updates from looped transitions option.

Now work can only move to Done if the most recent status was Testing in production.

Rule 3: Update an issue field

For traceability and reporting, we want to add custom date fields to our issue types to track key dates:

• Handed to development

• Handed to code reviewer

• Handed to QA champion

They can create simple rules that update these hand-off date fields to the current date of when someone moves the issue to a certain column or status:

• For issues moving to To do → In progress, update the Handed to development field to the current date/time.

  For issues moving to In progress → In code review, update the Handed to code review field to the current date/time.

  For issues moving to In code review → In staging, update the Handed to QA champion field to current date/time.

Congratulate yourself on a job well done

After going through all this, you should have:

• A workflow in Jira

• Automated the easy stuff for your team

Your software project should be up and running now. Share the great news with your team and give yourself a pat on the back! And remember: you can always iterate on your workflow. You can edit your statuses and transitions, and add more rules whenever you want.