Creating workflows in JIRA might be a daunting task if you don’t get the foundation right. As a beginner, you need to understand first some basic concepts before implementing your first workflow or adjusting an existing one. I’ll share with you 3 easy steps to create your JIRA workflow.
I’ll explain below these basic concepts and will also provide a step-by-step guide on how to set up a basic workflow in JIRA. Keep in mind that in order to create workflows in JIRA you have to have JIRA administration rights, otherwise you won’t be able to manage workflows. Also, I created this tutorial for JIRA Cloud because it’s the most recent and accessible JIRA version. Most of the ideas presented here are also applicable to hosted versions of JIRA.
The use case I’ll use as a base for this tutorial is that of person who has a project in JIRA with a default JIRA template workflow and wants to replace it with a new one customized to her team’s needs.
The work flows from a series of steps, starting at an initial step and then moving forward, and sometimes backward, step by step until its completion. A step in JIRA is known as a “status”.
A status in JIRA represents the current situation for a particular issue on a given time. This one is easy to understand. For instance, we can say that a particular issue in “In progress” or “In Review”. Ths situational representation is what we call “Status”.
You can have as many statuses as you want in your workflow, but keep in mind that the less the better.
Transitions are the bridges from one status to another. A transition is an action and represents the movement of a particular work from one state to another.
For instance, one might want to “Start working” on a JIRA issue. Once you sign that you want to “Start working” on a JIRA issue, you’ll also execute a transition from the current state to a new one which says that now the issue is “In progress”.
On JIRA cloud, transitions will appear like this:
On JIRA Server, transitions will be usually represented as buttons at the top menu of the edit issue screen.
JIRA has three types of work category:
- To Do: Work that is waiting to start.
- In Progress: Work that is being worked.
- Done: Work that was finished.
No matter which status you create, you’ll have to define to which category the status belongs to is it has to be one of the three listed above.
Each category has its own colour as well. To Do is grey, In progress is blue, and Done is green, as seen in the image below:
Why this is like this? Well, I don’t exactly what was the reason, but it’s easy to infer that it was done this way to simplify a lot the way they do their reporting calculations. But that’s going off-topic. Let’s get back to the workflow creation topic.
Just as a curiosity, on JIRA Server, the colour representing the “In Progress” category is yellow and not blue as in JIRA Cloud.
Create Your First Workflow In JIRA
Step 1: Start With Pen and Paper
Before jumping into implementing the workflow in JIRA, start with pen and paper and do some research in order to understand which workflow you’ll have to create. Ask someone in the team to verbally describe their workflow. Take notes of the words they use and convert that into a list of steps.When creating workflows in JIRA, the best way to start is with pen and paper. Talk to people and ask them to verbally describe how they work. Take notes of the words they used and convert that to a draft workflow that you can use to start… Click To Tweet
Example of a conversation that you might have
Alice: Hey Bob, I’d like to design and implement the team’s workflow in JIRA, but first I’d like to understand how the team works. Could you describe to me which steps you usually do from the moment you get something to do to the moment you consider it done?
Bob: Sure, well, usually after our planning meeting we have a set of issues we selected from our backlog as the ones we’d like to implement during the week. Then, we assign ourselves to one of the issues we’d like to work and start the development. Once the development is done, I submit the code changes to code review, then I interact with people base on their feedback and fix any issue that might be reported to me. When the code review is done, then I integrate the code. This is the last step where I do the integration of the code into the main branch, wait for the feedback from the tests, check our internal dashboards and then if everything goes well I consider this work done.
Alice: Great. I think I got it. Thank you very much for your time.
Bob: No worries
From the chat above, Alice might come up with the following list of statuses (steps):
- Selected for Development
- In Progress
- In Review
With this list at hand, Alice can then layout the flow between these statuses and define the transitions as well.
Backlog => Selected For Development => In Progress => In Review => Integration => Done
Step 2: Create A New Workflow In JIRA
In order to create a new workflow, go to the JIRA Settings > Issues > Workflows:
Now that you know the hard way, I’ll share with you the shortcut. By typing the following URL you can easily access the workflows configuration screen:
If you landed on the screen below you’re in the right place.
Now, click “Add workflow” to start creating a new one.
Give a name to your workflow and add a description for it and click “Add”.
Once add your new workflow you’ll be presented with the “Workflow Editor” which will be similar to the one below:
Now let’s have some fun. I usually first add the statuses I need. In this case, they are:
- Selected for Development
- In Progress
- In Review
Don’t mind clicking the “Allow all statuses to transition to this one”. We won’t need that. You’ll notice that for some statuses you’ll have to create new ones since they might not exist yet on your JIRA instance. Don’t worry, just click “new”, provide a description and set the correct category as exemplified below:
After you added all the statuses, it’s time to wire them up using transitions.
Click “Show transition status” at the top bar on the workflow editor and let’s move on. Now, reconnect the “Create” transition that is connected to “Open” to the “Backlog” status and delete the “Open” status by selecting it and clicking on “Remove status” as highlighted below:
We’re almost there, don’t give up! Now, create the remaining transitions between the statuses. Do that by hovering over the origin status, in this case, “Backlog”, and dragging your mouse until one of the connection points on the target status, which in this case will be the “Selected for Development” status. See the images below for an example:
Now, give a name for your transition and add a description that will help people to understand what will happen when they execute this transition. Once that’s done, click “Add”, and Voilá! You just created your first transition.
Now repeat the same process for the remaining transitions and in the end you’ll have created your workflow and it should be similar to the one below:
If you reach this far, congratulations! Now you’re very close, just a few more steps and you’ll achieve what you want.
Step 3: Changing And Publishing the New Workflow
Changing The Workflow
Now we have to go to our project settings to change the project’s workflow to the one we just created.
Go to your project and click “Project Settings”.
Once in the project settings, click “Workflows”.
You have now two options, you can either change the workflow scheme or add an existing workflow. In our case, we want to add an existing workflow. So, click on “Add workflow” > “Add existing” and choose the one you created in the previous step on the selection screen.
Now, click “Next”, assign all the issue types to the new workflow and click “Finish”.
Great, now you should see the workflow screen again with the new workflow being displayed! Great!
Publishing The Changed Workflow
Now, click “Publish”. You’ll go through a two-step process. On step 1, click “Associate”. Wait for step 2 to finish and click “Acknowledge”.
Congratulations! You did it!
Step 4: Check The Result
I usually check after every workflow change if everything is working as expected. I advise you to do the same. Create a test issue and make sure it can flow through your workflow as expected.
Creating a JIRA workflow might not be as hard as you think if you just get to know some basic concepts and understand how to wire things up in JIRA. To make things easier, I prepared a one-pager that will help you with this task. You can download it for free below.
If you’re working with a different version of JIRA, perhaps JIRA Server and are having trouble to figure out how to do it, just let me know on the comments below and I’ll do my best to help you.
I’m not affiliated with Atlassian, the owner, and creator of JIRA, nor receive any benefits for creating this tutorial from Atlassian. This tutorial is totally independent and based on my own experience. Any mistakes, inaccuracies or misinterpretations are my own.