Introduction
At Wassa, we use JIRA in combination with our own development process which contains a code reviewing stage. The default JIRA workflow is not compatible with our process so we need to change it. As you have probably experimented, JIRA is a powerful, complex and extremely customizable tool. However, it is not user friendly at all. This article will show you how to prevent some obstacles we had encountered at Wassa.
Workflows & Workflow schemes
What is it?
Definition can be found in JIRA help, but Workflow are nothing more than simple machine state diagrams for issues. As you already know, issues can progress from ‘to do’, to ‘in progress’ then to ‘done’ status, by default.
You can add as many states and transitions as your project manager can dream of.
The workflow applies to issue types (bug, story, etc.). For example, all bugs will follow the same workflow. An issue type can only have one workflow, but in the same project, all issue types can have a different workflow. For example, our next improvement step at Wassa is to add validation of screens by the graphic designers who designed them. We will add a new issue type such as 'ScreenTask', with a specific associated workflow. Here comes the Workflow Scheme. The workflow scheme is a collection of workflows (each of them applies to one or more issue type) that are used in a project.
Example of Scheme that use 2 different workflows, depending on the issue type.
Important notice: once you have a different workflow for different issue types, you cannot modify the type of an issue to another which does not follow the same workflow. Be careful you need to choose the right issue type when you first create the issue, or else you will need to delete it and recreate a new one.
Common issues
The one million workflow scheme list
Problem: For every project I create, I get a new workflow and a new workflow scheme (with the project key in its name). We are using JIRA for years and have thousands workflow schemes. What can I do?
Symptoms: In facts every time you use a default configuration for a new project (i.e starting a new project from standard project template from JIRA), it will create a copy of the default configuration for that particular project (identified with its key), such as ‘Software Simplified Workflow for Project ABC‘. It will also create ‘ABC : Kanban Issue Type Scheme’, ‘ABC: Kanban Issue Type Screen Scheme’, ‘JIRA Service Desk Field Configuration for Project ABC’ etc…
Our solution at Wassa: create a project template, with the latest configuration (and update it every time when the configuration needed to be changed). Then, when creating a new project, do not use a default new project. Instead, choose the small option at the bottom: “Create with shared configuration”, and select your template. We also recommend to fill in the template with Issue type, Issue type Scheme, Sub task types, Screens, Screen schemes, Issue type Screen schemes, Statues, Resolutions and everything you might need that are not default.
Advantages: if you update your workflow scheme (because of continuous improvement), you only have to change it once, and it will apply the updates to all the projects.
My super new ‘In Review’ Status does not appear on my scrum board
Problem: I spent one hour to update my workflow and my new status is not visible on the Kanban or Scrum board.
Symptoms: The new status is not mapped to any columns of the board.
Solutions: Click on board > Configure > select the columns menu. Then
optionally create new column(s) drag and drop unmapped status in corresponding column
Customize transitions
I want to force my developer to enter their work log at every change of column into the board. It is simple, 2 steps:
Create a screen (go to admin tools > issues > screens > Add screen (top right corner)) name it. Add the fields you need. You may add tab bar with fields in each page. (Our recommendation: make it simple and quick to fill in; if not the developers will not do the job) Back to your workflow, select your transition, click on edit. The last selector is the transition view. Select the one you created previously.
I want that only the project manager is allowed to do a specific transition. It is simple:
First make sure there is a user group where you are the only one in this group, let's says ‘Kings’, ‘Gods’,‘Projects Managers’. Create one if needed. Then select the transition you want to restrict, go to condition Tab, and ‘Add condition’, select ‘user is in group’ option + ‘Add’, select the ‘Kings’, ‘Gods’,‘Projects Managers’ group. That’s all.
Understand the Resolution field
Status and Categories
Statuses are states of the workflow, states of your state machine, stages of development. It is very much linked to the development process and could be configured as well. Usually statuses are (as default scrum) ‘To do’, ‘In Progress’ and ‘Done’. You can enrich it with ‘In review’, ‘open’, ‘waiting for customer input’, or whatever your mind can think of…
The category is like a status type. The categories are deeply fixed in the JIRA system and are not editable. They are ‘To do’, ‘In Progress’ and ‘Done’.
What is Resolution?
When managing an issue from the beginning of the workflow until its end, the result is the Resolution. The status is (for example) ‘Done’, but the Resolution could be ‘Done’, ‘Closed’, ‘Not reproducible’, ‘Rejected’, ‘Declined’… Resolution field is generally associated to a terminated Status. i.e. a status that you cannot transit from. Since Resolution, Category and status can have the same name and each one can have various translations according to different languages, IT IS CONFUSING.
It took me a loooong time to understand the differences between Status, Categories, and Resolutions.
Moreover, we use a Service Desk plugin in our JIRA. In service desk plugin, the main field used to differentiate terminated issues from others is the Resolution field. In the service desk portal, the term displayed for the customer is "Status", but this status actually matches the resolution field. This has made me crazy for days.
The confusion was due to a combination of few factors:
Some of our statuses were ‘Done’ or ‘Declined’ (names of some statuses are the same as some Resolution names as well as Category names) The Resolution field is not visible most of the time in any JIRA screen and mostly it is not authorized by permission schemes. The action associated to terminal States did not set the resolution field In the service desk portal (for customers) the Resolution field is named status.
Set up the workflow end to update the resolution.
After understanding all that differences …
When creating a workflow, the starting states are usually ‘Open’, ‘Backlog’ or ‘To do’. And the final Statuses are generally ‘Done’, ‘Declined’, ‘Abandoned’ … A final status has at least one inbound transition. You need to edit each of these transitions and add a post function.
(if it is missing, click ‘Add post function’, select ‘Update issue filed’, click ‘Next’, select issue field ‘Resolution’, set it to ‘Done’, then click ‘Add’.)
Here is an example for Reviewing code which is one of our steps for standard Task. If you have an Abandoned step, set the Resolution field anyway with the corresponding Resolution value.
Finally, (and importantly) if you have outbound transitions for a terminal Status, you have to clear the Resolution field by adding a post function and set up the Resolution field to ‘none’.
How to know if it configured properly?
In the done column of your project board, if you get some done task which are not striked out, then you can be sure that the resolution field is not set.
Too late, I have many issues that are done without setting the resolution field. What can I do ?
There are several possibilities:
Simple: if you have the permission to edit the resolution field, then select all concerned issues, and make a bulk change then setup the Resolution field.
Complex: Add the resolution field to your ‘edit’ screen, or to your transition screen. Edit the issue, select Configure field at the top right corner of the ‘edit’ screen; Where is my field? (top right corner) and select Resolution.
Now, you will see a list of what is to be done and you will be able to edit in the resolution field. We can admit that it is not crystal clear, but this is generally a good start. Most of the time, you can add it to the ‘Create Issue Screen’ or whatever you have called it. Then add the resolution field.
Once it is done, select all concerned issue, bulk change and the resolution field. (perhaps think about hiding this field again). You may have to setup several screen to achieve this goal if there are many workflows in your workflow scheme.
Overkill: Another solution is to duplicate you workflow, add a new state named; for example, ‘bad done state’. From ‘bad done state’, add a transition from ‘done’ to ‘bad done state’. Then add a transition from ‘bad done state’ to ‘done’, with a good post function and save it. Apply that new workflow to your project workflow scheme, associate the concerned issues (could be all), then apply the conversion. Select all concerned issues, bulk change a transition, to the ‘bad done state’. Then Select all concerned issues which include the new ‘bad done state’ and bulk change a transition to ‘done’ state. Now your issues are in a good Resolution. Set it back to your regular workflow.
Last words
As you may have seen, JIRA is very powerful tool but also very complex as soon as you want to walk outside the narrow path, it has traced for you. We hope these few tips will help you mastering JIRA and save you some time, which is what it was made for in the first place.
Stay tuned for new post about JIRA in the future!