Tips and Traps! Lessons Learnt with My First Jira Workflow

[#1]

Jira’s power comes from its workflows. That’s not a news flash and I thought I had a pretty good understanding of how Jira workflows worked – until I tried to create one.  It sounds simple enough. Workflows have statuses (where an issue is in the lifecycle) and transitions (actions that move an issue from one status to another). If you’re new to working with Jira workflows, I would recommend reading this article, even before you dive into the Atlassian documentation.

 
At my workplace, we use a Kanban project to manage our content. It’s useful, but as the self-designated Content Queen, the person who uses the Project Board and someone with Administer Project permissions, I figured I could make it more useful (at least for me!). So I decided to put on my JA hat and customize the workflow.

Where to Start Building a Jira Workflow

I read that article. I looked at the Atlassian documentation. I scrutinized our team’s existing workflows. Then I figured I was ready to dive in and make the changes I wanted.  I navigated the workflow used by the Content project.  A friendly message said that it was, “Shared by 1 Project.” Since that one project was the Content project, my project, I figured it was okay to start to making changes. So I went to Jira settings > issues > workflows, found my workflow and started editing.

Bad idea! Later that day I learned that I had screwed up the workflow for our development projects. Oops. You see while the workflow itself was not shared by any other projects, all of the statuses within that workflow were. That’s because statuses are global. This means a few things:

• If you change the name of a status in one place (like I did), you’ll be changing it in multiple places.
  
• If statuses have somewhat generic names, as recommended, the status you need may already exist and does not need to be created.
  
• Don’t mess around with a workflow that is used by a current project. Instead, make a copy of the workflow. The copy will be listed under the “Inactive” section of the workflow list in your Jira settings. From here, you can safely make all of the changes you want, then set the revised workflow to “active” on your project when you’re ready.

Jira Workflow Post Functions

While this was the biggest hiccup, I ran into a few other surprises. Examining one of my transitions, I noticed that it had 5 post functions. I hadn’t created these, so I figured they were just inherited from the workflow I was editing and weren’t needed. However, delete was disabled. I tried deleting and recreating the whole transition. Again, there were 5 post functions. It turns out, Jira creates these post functions by default, on every transition.  Generally speaking, you don’t need to change these.

I did make one alteration. Based on Rachel Wright’s recommendation I changed the “Fire a generic event…”, to a “Fire an Issue Closed event” on my last transition. I also set a post function to set the resolution as “DONE” when the issue reaches its final status.

Jira Workflow Approvals

Another puzzle was how to deal with approvals. There are a lot of different options for creating approvals in Jira depending on the project type, add-ons, etc. You don’t want to have more statuses than necessary, and multiple approval statuses can create a bottleneck.  The Jira Strategy Admin Workbook (page 86-88) describes how you can use transition buttons and field validators to enforce multiple levels of approval without creating extra statuses.

This fits with what appears to be the golden rule of workflows- Keep it simple!