Getting into the JIRA Flow Part 1: JIRA Workflow Tutorial

Ever since its introduction to the market, JIRA has been one of the most preferred options for Agile project tracking out there. Additionally, its rapid growth has positioned Atlassian as a leader in innovation for integration capabilities and customization, setting impressive milestones for similar initiatives. This JIRA workflow tutorial is the first in a trilogy of articles that will offer administration tips for project managers, Scrum Masters, and application administrators getting started with the JIRA flow.

First, we’ll start with an introductory explanation of JIRA workflow components. If you are already familiar with these topics or find them too basic, just wait for Part 2, where we will talk about business process abstraction, or Part 3, which will cover workflow customization.

So, without any further delay, let’s dive into this JIRA workflow tutorial.

The Questions

What is a workflow?

A JIRA workflow is a representation of an issue life cycle. This “issue” entity is, in turn, a representation of work intake in the form of a user story, task, bug, spike, etc.

The most known visualization of a workflow is on a digital dashboard that shows all of an issue’s statuses and the transitions between them.

Statuses, you said?

Statuses are essentially the different steps or phases an issue can flow through during its life cycle. They can be named whatever the team wants, and they usually start with an Open/Submitted/Created status and end in a delivery step whose acceptance criteria might have been fulfilled, deferred, or discarded.

And what about transitions?

A transition is the action of moving from one status to another. From a diagrammatic point of view, it can be visualized as the connecting line between statuses.

Here is where most of the workflow magic occurs (or could occur), because transitions have four configurable components: triggers, conditions, validators, and post-functions.

Before going through these, it is also important to mention that there is a special, additional type of transition within a workflow called a “global transition.” When a transition is declared global, it is displayed as an isolated status in the diagram, which can be moved anytime we want during our issue’s life cycle.

Ok, got it. So what are transition conditions?

A condition can be viewed as the requirements for a transition to be executed. This means conditions are evaluated before the user can even transition to a new status.

For instance, if you have defined a condition saying that only the assignee of an issue can perform the transition, the transition button will only be available to that person.

Or you could define a condition making a transition available only if code has been committed to a particular user story, which would allow the transition button to show up only if some code has been submitted on the related branch. Useful, huh? I know I got your attention here.

It’s starting to sound like fun! Tell me about validators.

As their name may indicate, validators check for specific input before going into the requested transition action. Imagine that you are about to close a user story, and you get presented with a screen containing the comment box, but the issue doesn’t transition — instead, it tells you that you must enter a comment. All that logic can be performed with a validator defined in the issue’s workflow.

There are several validators that don’t present a transition screen since they do not require interaction, but most of the time you will see them working together.

Cool! I can guess what’s up next. Post-functions are…?

Post-functions execute at the very last phase of a transition. Their most basic, default action is to move the issue to the next status in the JIRA flow, but we can perform several other nice things with this component:

Would you like to automatically assign the issue to the lead developer so it can be reviewed? You’ve got it!

Would you like to send an email to someone on the team to let them know this issue reached a specific status? You can do that, as well!

Or, do some fields need to be automatically filled in at this stage? Yes, that can also be done.

I think you’ve got the idea.

Wow! But, wait a minute… didn’t triggers come first in the list?

You caught me! Triggers execute before all of the previous transition components; the reason why I left them on the back burner is because, in most of the cases, they are integrated with other tools.

Triggers respond to input from external tools; for instance, if a new branch gets created in Sourcetree, you can automatically have the issue moved to the next status in the JIRA flow.

There are even some scripted triggers out there on the market that can perform very interesting chained behavior that I know will attract your attention; for those, stay tuned to future blog posts in this series.

Ok, so how do we relate workflows to a project?

For this, we use “workflow schemes.” This is our last concept in the workflow vocabulary.

A workflow scheme is a mapping of workflows and issue types. Within a project, a workflow scheme allows you to define what workflow a specific issue type (epic, bug, spike, task, user story, etc.) should use.

This allows you to define different behaviors for distinct issue types within the same project.

The best way to answer this question, though, is with some practice.

Hands-on JIRA Workflow Tutorial

For this JIRA workflow tutorial, it is recommended to use a “dummy” or practice project, preferably in a JIRA test or development environment. Images preceded by an “A” correspond to the JIRA server, while images preceded by a “B” correspond to the JIRA cloud version.

Creating a new workflow

1. Log in to JIRA as an administrator.

2. Click on the “Settings” button (cog icon).
(A. Server version: Top right side of the screen)
(B. Cloud version: Bottom left side)

A.                             B.

3. From this button’s drop-down menu, select the “Issues” category.

4. Now on the left panel menu, select “Workflows.”

A.                                               B.

5. In the “Workflows” section, click the “Add Workflow” button (you can also practice by cloning an existing one).

6. Name your new workflow and fill in its description.

7. You will be presented with the diagram view of the workflow with nothing but a circular object, which is the “Submitted” status of an issue. This is the very first creation event.

8. Click on the “Add Status” button and select one of the existing statuses from the list (“In Progress,” for example).

Note: Do not click the “Allow all statuses to transition into this one” checkbox, or it will become a global transition.

Now that the status has been added to our workflow diagram, we need to create a transition to get to it.

9. Click on the “Add Transition” button. Select the origin status and the target status; then, name it something relevant like “Start Progress.”

10. Now that our transition has been created, we can publish this extremely basic workflow by clicking on the “Publish Draft” button (which is not necessary right now since the workflow has not been used by any project yet).

Creating a new workflow scheme

In order to associate this new workflow with a project, we need to create a new workflow scheme.

1. On the left panel menu, under “Workflows,” select “Workflow Schemes.”

2. Click the button.

3. Name the workflow and click the “Add” button.

4. Once it is created, you will be presented with the configuration screen.

Here you have to add the workflow we just created by clicking on “Add Workflow” and then selecting the “Add Existing” option.

5. Select the new workflow we just created and click on “Next.”

6. Once the workflow is added, we need to associate it with specific issue types. In this case, we will associate it with all the available issue types.

7. Finally, click the “finish” button.

Changing your project’s workflow scheme

1. Click on the “Settings” button (cog icon), and select “Projects” from the drop-down list.

2. Select the project you wish to associate our new workflow scheme with.

3. Once inside, select “Workflows” from the left panel menu.

4. Then, click the “Switch Scheme” button.

5. Select the new workflow scheme we just created and click on “Associate.”

If any future issues arise in this project, we will be prompted to choose which issue types to include with the existing ones, but it doesn’t apply in this case.

6. In order to test it, create a new “Bug” issue and confirm that it only has the steps our very basic workflow has.

Adding a new condition to our workflow’s transition

1. Click on the “Settings” button (cog icon) and select “Issues” from the drop-down list.

2. On the left panel menu, select “Workflows.”

3. Find the very basic workflow we created and click on “Edit.”

4. Click on the transition line between the “Open” and “In Progress” statuses.

5. On the pop-up that appears on the right, click “Conditions.”

6. Click “Add condition.”

7. Select “Only Assignee Condition” and then “Add.”

8. Back on the transition’s main screen, click on “Publish Draft” for the changes to be stated.

9. Now on our test issue, we can verify the transition button doesn’t show up if we haven’t assigned the issue to our user.

10. It does show up, however, after we have assigned it to our account.

That’s all for now — stay tuned for Part 2 of the JIRA workflow tutorial, where we will talk about JIRA custom workflows.