Documenting JIRA Workflows

In addition to administering JIRA, I also perform as a Business Systems Analyst. This involves running several worksessions with a business area, to understand what they need to track and how it needs to be controlled or managed, and then to determine how that can best be accomplished in JIRA.

As I’ve worked with business area users of all levels, I’ve found that it is essential that both the Systems folks and Business folks develop a common language when designing a JIRA project and its workflow. One technique I’ve developed for doing that is to create a workflow diagram that ‘explains’ the most important processing… all in a single diagram.

I produce the diagram using Microsoft Visio, but any diagramming tool, including Gliffy, will do.

The key elements captured in the diagram are:

  • The steps in the workflow, which correspond to the Statuses it supports
  • The transitions in the workflow, which indicate the name of the link that the user clicks to move an issue from one Status to another
  • The permissions or roles that can execute a given transition
  • The screen shown for that transition
  • The event triggered by the transition.

Below is one simple example. Click the image to view it full-size. Note that the legend for the screens is shown at the bottom, and it includes the key fields shown on each screen. Even ‘no screen’ is shown, denoted by S0.

Document Pull Request workflow

Document Pull Request workflow

The diagram also notes special processing that the workflow will perform, such as ‘Auto-assigned to current user’, as well as information that the business area might find useful, such as ‘If Mail Operations doesn’t have the check’.

As seen on the Closed Status, transitions that do processing without changing the issue’s Status are shown with a arrow that circles back to the originating Status.

This example concentrates on what is being done. The next example, through the use of a ‘swim lanes’ approach, concentrates on who is doing what.

Job Evaluation Request workflow

Job Evaluation Request workflow

This workflow also shown numbers next to each Transition (such as 2.1 by the Create Issue transition at the top of the diagram). These are cross-references back to the business requirement that the Transition supports.

Personally, I feel the ‘swim lanes’ approach should be used only when the JIRA project requires several distinct roles… which often means it uses a fairly sophisticated security scheme.

Although JIRA now includes a visual workflow designer, I still believe there’s a value in using diagrams like the ones above that summarize the bulk of the ‘intelligence’ behind the workflow. Both I and the business areas I work with find ourselves referring to them over and over again, through the JIRA project design effort, training, and as questions arise.

, ,

4 Responses to Documenting JIRA Workflows

  1. Andrew Webster May 10, 2012 at 12:59 pm #

    Hi Betsy,

    I love the idea of using the key for each screen, I”m stealing that!

    When I document using Visio, I use swimlanes to represent Status to be a guide for building filters and dashboard gadgets. Steps are effectively invisible to users.

    This also means that if I’m building out several different workflows to be used in the same workflow scheme I can show their steps and transitions mapped against the same statuses, again handy for roll-up reporting.

    Great blog, keep it coming.

    • Betsy August 3, 2012 at 6:28 am #

      Hmmm, I hadn’t thought about using Swimlands to represent Status, but I can see that would be helpful at times. Thanks for the comment.

  2. Larry Dribin June 8, 2012 at 10:01 am #


    I work at Walgreens where we are big JIRA, Confluence users. I like your documentation approach. JIRA’s “Workflow” is quite a bit different from the Business Process Modeling Notation (BPMN) that we would like to use at Walgreens to document processes.

    Have you, or do you know of any one who has mapped BPMN to JIRA “Workflows”?

    Thank you,


    • Betsy August 3, 2012 at 6:27 am #

      Sorry, Larry. I haven’t heard of anyone doing that… yet. Let me know if you learn of any though!

Leave a Reply

Simple Share ButtonsShare:
Simple Share Buttons