JIRA allows you to define quite flexible workflows with lots of configuration options but when working on a JIRA development project it becomes really hard to keep track of things. 

The Need and the Goal

Most of the time, JIRA customization is a project all by itself which includes analyzing customer processes (which by the way can be internal business units or external customers), designing and developing JIRA workflows to realize those processes. These projects include not only JIRA configuration but also groovy script development or even Java development. 

From a practicality point of view, it is hard to see all things in JIRA workflows. JIRA UI shows you workflow steps, transitions, screens, conditions, validations, post-functions in separate windows or tabs. There is not a single unified user interface page that shows all details of a workflow with detail. This makes comprehension of an existing workflow very hard. 

On the other hand we have a similar need while analyzing and designing the workflows. How do you document the workflow? What do you show the customer to agree on? What do you give your team to implement? How can you collect all details on a single sheet of paper so everybody can easily see all of it. 

These questions do not have perfect answers but in this blog post I tried to summarize the technique we use at OBSS to for designing and documenting JIRA workflows. The document format explained below is merely a proposition for a starting point but I must say it did well so far, even in projects with 30+ workflows. 

Please note that this document format is to configure a workflow on JIRA, it does not aim at documenting your business processes. (This document might reference your business process documents if you have them tough) 

The Document

Each workflow is documented using only Confluence and Gliffy, on a single Confluence page. The main goal of the document, as mentioned above, is to build a single point to see all details of the workflow which will act as an analysis and technical design document along the way. (You can find the complete document W1_SampleRequestWorkflow.pdf)

First, the name of the workflow

As you see, the document starts with the workflow name. The name is anything you want but it should better be the name of the workflow you will use in JIRA so you can find it easily both ways. The name should be in "Wx_<workflow_name>" format. For example: W1_SampleRequestWorkflow. Giving a number to any work product is a good practice and it sure pays off here as well. (We will name our custom developments or SLA definitions as sub items of this number later)

Purpose

The statement of the purpose of the workflow from a business perspective. What does this workflow do? What will it accomplish? Something like: "This workflow will be used to track user requests from inception to the point where the request it complete. Workflow covers manager approvals of both business and IT."  

Workflow

After that comes the workflow itself drawn in Gliffy. 

The small circle marks the beginning of the workflow. Each box is a different status and each connecting line is a transition. (So arrows have directions). Each status has an associated number code and we will reference statuses later by their numbers. Each transition has a name but does not have a number. Each transition has a name because that name will also be shown on the transition button on the view screen; but does not have a number because we will reference transitions by the numbers of statuses they originate from and go to.

You may also add swimlanes to the the diagram to visually define participants of the workflow but that is optional because it might make sense for one workflow but might not for another.  

Workflow Table

Below the workflow is the workflow table. The table includes all details that are needed to configure this workflow and each row in the table represents one transition.

The first column is the transition code which is created by combining the numbers of the statuses the transition originates from and goes to. For example: A transition from 1:Open to 2:In Progress is coded 1-2. (There might be more than 1 transition from one status to the next. In that case transition should be named like 1-2a, 1-2b, etc.)

The second column is Transition Name and naturally shows the name of the transition. The value in this column is the same with the text on transition line on the diagram and this text will be shown on the workflow transition button of the issue.

The next two columns are From and To columns. They show the origin and the destination statuses of the workflow.

The next two are Condition and Validation columns.

The next one is the Fields column and it shows the names of fields and field types that will be asked on the transition screen. For "select list" fields, the options of the field is given when the field is appears in the table for the first time. (See field Request Type on create transition). Required fields are checked with validators most of the time but they are shown in the fields column as well because this notation increases readability. (See comment field on transition 1-5)

Next comes the Post-Functions column. This column shows the post-functions added by us, not the default ones added by JIRA because default ones are … well … defaults. There is no point in showing them.

And finally is the Notes column which is empty most of the time but if you want to add notes for that transition for some reason, that is the place.

There are some remarks to be made here:

First, some columns in the table (namely Transition Name, From and To columns) actually duplicate the information already shown in the diagram. We could well get away with just showing the transition code but that destroys readability. If you do that, you can not read any row in the table without going back and forth to the flow diagram. So, better keep those columns. On the other hand we could try to load all information on the table to the diagram but that also has a few drawbacks. First off all at some point you will probably discuss this workflow with the customer and the more detail there is on the diagram harder for the non-IT user to understand. Second, diagrams can not be compared but Confluence page text can be. The workflow design will go through many changes thoughout its lifetime and at every design change, the admin will need to see what was changed and implement it to the workflow. You can not compare changes on a Gliffy diagram but sure you can compare Confluence pages.

Another point: The same field might be used on a number of transitions on the workflow or even across different workflows. So why not create a separate Fields page (to serve all workflows) with field types, options, etc and reference those fields here? Or create a separate "Screens" page that defines the screens so we can reference them here. Actually we tried that and found it to be very slow and much less productive. It becomes very hard to create and maintain the document so we decided it is better to show it in the Fields column.The configuration expert knows the basics of screen reusability so does it the best way he/she can.

And finally, any custom development that will be implemented via Groovy scripts or Java development is referenced here with a "blah blah (Custom Dev Wx.y )" reference. More on that below.

Edit and View Screens

Two lists of fields that will take place in Edit and View screens are given in the tabs and the order they will appear on the screen. There is no Create screen here because the fields column of the first row in the workflow table acts as the create screen definition.

Custom Developments

There might be many features in your workflow that will be implemented via Groovy scripts of Java development. Things can not be done with conventional JIRA configurations. These developments are listed here with a four column table.

The first column is the code which is something like "Custom Dev Wx.y" where x is the number of the workflow and y is the index number of the custom development. The second is the type of development, which most likely has a value like Groovy of Java. Third is the Title of the development and fourth is the detailed description of the development. (If it is too large of a development and needs a detailed analysis document, you might choose to prepare a separate page for that analysis somewhere else and just reference it here)

Most Custom Dev's should have a reference in the workflow table but that is not a must. You might implement some certain features completely outside the workflow configuration but might consider it to be related to this workflow somehow so show it here. A nightly running background service that closes all inactive issues might be a good example.

And finally, if you have similar custom development items or maybe identical custom developments that run with different parameters (even across different workflows) show them here as separate rows and reference one another in the description. This way you can see how many development items there are for this workflow and the developer can also see what other development to look for existing codes.

SLAs

This section is used if you use JIRA Service Desk. Once again a table. This time with 8 columns:

The first column is the SLA code and is like SLA Wx.y . X is the number of the workflow and y is once again the index number of the SLA timer. The second column is the name of the timer (which will also appear on the issue view screen and reports) Next 3 columns are start, pause and stop statuses respectively. The next column is the definition JQL. The final two columns are the target time and calendar. Please note that the first five columns are for defining the metric and the last three are repeated for each target.

This is all there is for the configuration document. This amount of information prety much sums up what a JIRA admin will need to configure the document.

For a scope with multiple workflows it would be beneficial to summarize the projects and issue types in a higher level table. (Most likely on a different page)

Lifecycle of Document

Your JIRA project will go through different stages and this document will serve many purposes along the way. At the analysis phase it will serve as a document to see the complete workflow and act as a workdesk to work on with the customer. At the end of analysis it will act as the foundation of your agreement with the customer. During implementation it will let your team see the whole workflow together and will let you make impact analysis for change requests from a single point. Also it will grow during implementation with more and more technical design decisions and implementation details. At this point you might want to take a copy of your page so keep the original page as "agreed analysis" and the latter to improve with technical details.

Challenges

The document is simple and easy to prepare but …

Customers (especially non-IT minds) might find it difficult to understand the document. The document itelf mostly does not contain anything technical but the existance of the workflow table and terms like Conditions, Validators, Post-Functions make it look more like a technical design document. This might cause some resistance from some customers. In this case you can add a new section to the document that summarizes the workflow in a few paragraph of text with a daily use language.

Conclusion

This format serves as a good starting point for any analysis and design need. It serves as an analysis document in the beginning, then a design document during the project and then a reference document for later but since no two projects are the same, it will always change for the needs of your specific project. As I said earlier, this is what we start with at OBSS and it has done pretty well so far. Hope you benefit from it too.

Emre TOPTANCI

OBSS Atlassian Team Lead