2018
16
April

Jira’s Pre-configured Workflows vs. the Definition of Done

I frequently get asked: What’s the difference between resolved and complete? Why do I have more than one version of “Done”?

On my workflows (when I’m running a team) I usually remove the Resolved status. I prefer to make sure the resolution field options are appropriate and use workflow transitions that go to a single Done status.

This is a screenshot from Jira cloud. If you’re on Jira server, the Status Category colors for To Do will be blue and In Progress will be yellow.

 

Now you may be thinking: Wait a second there buddy. The Jira Default Workflow is a best practice based workflow that’s been in use for many years. What do you mean you remove the resolved status?

I’m used to running my projects a certain way. Your mileage may vary. If it’s useful for your team to use the Resolved1 status, please use it! This is why I usually remove it.

I remove any additional Done status to reinforce that my team has a single common understanding of what we mean by Done. It’s much easier to commit to our work when everyone on the team has a this common understanding of what Done means. Having multiple statuses that all communicate different aspects of Done, and being able to see these multiple Done states by viewing the workflow, either contradicts or clouds our understanding of what we mean by Done.

This approach is very useful with other more complex workflows as well. For example, here’s the Information Technology Services Management (ITSM) certified Service Request workflow that’s provided with the IT Support Jira Service Desk project configuration.

This workflow has three statuses that are considered Done:

  • Cancelled
  • Resolved
  • Closed

To see what work we’ve completed this week I’d have to use this Jira Query Language (JQL) search:

status in (Cancelled, Resolved) AND updated >= -7d

You’ll notice that we need to move from Resolved or Cancelled to Closed, but Resolved, Cancelled and Closed all mean we’re Done. To avoid matching those updates, I do not match on the Closed status. It’s ironic that, in this example, the ultimate final Done state is not used to see what we’ve completed.

Here’s what that workflow looks like after I’ve applied my changes.

Let’s zoom in on how we get to Done and show the transition labels.

Now everything leads to one Done status. To see what work we’ve completed this week, we can create a filter (by saving a search) with this JQL search:

status = Done AND updated >= -7d

Much simpler!

If I want to know why we’re done with that issue, that’s exactly what the Resolution Field is for.

To see all the issues that were marked Done because we really finished work, we just add the Resolution field parameter “resolution = Done” to that search.

status = Done AND resolution = Done AND updated >= -7d

To see work marked Done because those issues were cancelled, we just add the Resolution field parameter resolution = “Won’t Do” to that search.

status = Done AND resolution = "Won't Do" AND updated >= -7d

One last thing: To keep the resolutions data clean, I update the Transition Properties for the Resolve this Issue and Cancel Request transitions so the resolutions that are appropriate for those events are the only ones available. If we follow the Resolve This Issue transition, we shouldn’t be able to set the resolution field as Cancelled, Duplicate or Won’t Do. For the same reason, if we follow the Cancel Request transition to Done we shouldn’t be able set the resolution field as Completed, Finished or Done.

To set the Transition Properties refer to these instructions. You add a Property to the Workflow called:

jira.field.resolution.exclude

You set that property with a value of the resolution ID. This is because Jira is localized for over 20 languages so you don’t want to match the word used for a Resolution in just one language. You can provide a comma separated list of Resolution IDs. To find the Resolution Id, I use a REST call in my browser to retrieve a JSON list of all the resolutions. THe URL is: https://<YOUR Jira DOMAIN NAME GOES HERE>/rest/api/2/resolution. The response has the ID listed for every resolution. For example here’s the first line of the results from our server:

"self":"https://<YOUR Jira Domain Name IS HERE>/rest/api/2/resolution/6","id":"6","description":"","name":"Done"

So the ID for the Resolution of Done is 6 because the second key value pair is:

"id":"6"

This means on the Cancel Request Transition I’d set the property jira.field.resolution.exclude to the value of 6.

1 Resolved is intended to be used when someone thinks an issue is done, but someone should review it to make sure it’s really done. In the Jira Default Workflow the Closed status is also configured to prevent future edits to issues in the Closed status. Having a status like Resolved is also meant to represent that “We just finished this work but we may need to add something to the issue before we won’t have to touch it anymore.” Both of these cases are valid reasons to use this status, but I still usually rename it. I have always found it confusing that the Jira Default Workflow has a status called Resolved, while the Resolution field has a name based on the same concept. The Resolution field is far more important for reporting on why we know we are done with each work item.

Tagged with: , , , , — Posted in Atlassian

Leave a Reply