What's in a workflow?

First, let’s take a look at what defines a workflow. A workflow has four unique components: statuses, transitions, assignees, and resolutions. As an example, libraries have well-known workflows surrounding materials they lend out to the public. Each item could be stored in Jira Core as an issue, and administered in the following simple workflow:

Statuses: where

Statuses represent the position of the issue within a workflow. In the library example, a book can be in one of three places: at the library, with a customer, or retired from inventory. Every status should be a unique state in your workflow.

Transitions: how

Transitions are the bridges between statuses; the way a particular issue moves from status to status. At the library, books are loaned out by librarians, returned by customers, and evaluated by library staff to see if they’re fit for circulation. Note that customers cannot evaluate if an item is fit for inventory – that must be decided by the library staff. With JIRA Core, you're able to set workflow permissions that allow only the right people to transition an issue.

Assignees: who

Workflows guide how people work together. In Jira Core the assignee dictates the responsible party for any given issue. In the library example, we would set the assignee to the borrower every time a book is loaned out, so that the library knows which customer has that book. When the book is returned from inventory, we would then remove the assignee when we transition the book back to inventory.

Resolutions: why

Resolutions explain why an issue transitions from an open status to a closed status. The act of retiring a book removes it from inventory, therefore, we can put a resolution on that book. In this example, we might use resolutions such as damaged, out of date or lost. The two biggest mistakes new Jira Core administrators make are:

• Confusing resolution with status – Status describes where an item is in the workflow whereas resolution explains why an item is no longer in flight. In order to effectively use these features to retire a book from circulation, our librarian should create a status called retired, and options for resolution that include things like lost, damaged, or out of date. Searching for everything that’s retired (or resolved) – with the ability to search for why it’s retired via the resolution options gives much better reporting metrics. That’s why JIRA Software uses resolution to know if the issue is considered inactive by the organization. The best way to check to see if you’ve got it right is to use the created versus resolved gadget. You can have a workflow between when an issue is tagged with a resolution and officially closed. Many organizations verify resolved issues to ensure they're resolved for the right reasons.

• Setting resolution correctly – You must set a resolution when an issue moves from an open state to a closed state. Likewise, resolution needs to be removed when an issue gets reopened. At the library, if the librarians decide to put the book back into circulation, they would need to remove the resolution from that book. For example, a book that is able to be checked out should not have a resolution of lost.

How do I create the workflow I need?

Building the workflow you need can be challenging. Remember, it's all about building what you and your team need to work more efficiently and effectively. That may involve you and one other person, or it could involve several departments and many people. Here's a few pointers to get you going.

Gather all of your stakeholders

Workflow is about scaling culture, and culture is about people. Whenever it comes time to build a process around a set of people, identify all of the stakeholders in that workflow. For example, if you’re trying to build a workflow between product management, software development, and support, ensure you have one representative from each organization in the meeting. As the person designing the workflow, spend time talking with each stakeholder about what’s important to them. Before the meeting starts, draw a draft workflow on the whiteboard, then walk through each case in the meeting and gather stakeholder feedback. Workflows are touchy as they govern how people work, so be patient, and your investment will pay off later.

Use a whiteboard in low fidelity so it’s easy to get feedback and make changes at this stage.

Keep the workflow simple: less is more

Most of the time, stakeholders want to have statuses for each part of the workflow. Generally, that’s a good thing, but remember: each status adds more transitions and complexity to the workflow. Workflow is designed to make things simple and scalable. Whenever you're adding a new status to a workflow, ensure that the stakeholder has no other option but to grow the workflow. Let’s look at two examples.

• For many news papers, articles needs to be reviewed and this is an important part of the editorial process. Jane, the editorial manager, wants to add a specific status called article review so that it’s clear to the team what issues are still being written, and which issues are waiting review. Reviewing articles is distinctly different from writing articles. It makes sense to add a new state as the review state will indicate an article has been written, and a different person (assignee) is now responsible for review.
• Bill, the editor, wants to add a new status called rejected for all issues that don’t pass review by his team. I’d advise against doing this, as the writing team can simply reopen any issue that fails review. An alternative option is to move the issue into a resolved state with the resolution rejected.

As a Jira Core administrator you owe it to yourself and your users to keep workflow simple.

Make every transition count

Jira Core has a number of options administrators can employ when transitioning issues between states.

• Conditions – Conditions control who can perform a transition. For example, only someone in the library can retire a book from inventory.
• Validators – Validators ensure that a transition can happen given the state of the issue. For example, if a book is to be retired because it’s allegedly damaged by a customer, we’d like to ensure the book has been checked out at least once to verify that claim.
• Post functions – Post functions execute actions on issues after both conditions and validators pass. The most common post function is to clear the resolution when reopening an issue. In the library example, we would use a post function to clear the reason a book was retired when it got put back into service. Jira Core keeps a detailed history of issues, so we could look up when the issue was retired and why.
• Assignees – Whenever a transition occurs, always ask who the new owner of the issue is. Ensure that in every transition there's a default action to route the issue to the right place. Users can override the default action as well.
• Properties – Jira Core recognizes some properties on transitions. The most common one is to limit resolutions displayed to the user on a given transition. For example, we might want the resolution scratched to show up for disk media when retiring, but not for books.

Building your workflow

Check out the Jira administrator documentation on workflows for all the information on how to build the workflow you want. Once you’ve built your workflow in Jira Core, you should take the time to ensure the workflow is robust and doesn't have any dead ends, or unexpected behaviors. You'll want to share the workflow with all of your stakeholders for a final round of feedback. You should also enable the option in Jira Core to easily show where the current issue is in the workflow. All users have to do is click view workflow.

Tips and tricks

There's a few things you should check, and a few tricks you can use you get the most out of your workflows:

1. • If you intend to change the workflow you're using for your project, make sure that the workflow isn't being used by any other projects! Any changes made to a shared workflow will impact all the projects using it.
   • If you already have a workflow that works for you, and you want to use it in another project, you can either create the new project and select "Create with shared configuration", or once you've created the project you can change the default workflow to the existing workflow that you want.
   • Once you edit your workflow, remember to publish it! Publishing the workflow effectively makes it active on your project.