Jira Workflow Best Practices - Part II

This series of Blogposts share some of the Jira Workflow Best Practices I garnered in my years of working as an Atlassian consultant.
03.03.2022
Tags

Welcome back to our blog on workflow best practices. We hope you found the first section interesting and useful. In this second installment, we will be covering

  • specific best practices you can apply directly to your workflow design,
  • suggestions on naming conventions,
  • the benefits of using Properties and
  • how to extend your Jira’s workflow functionality by using add-ons (also known as plugins) to offer features that are not baked into the base Jira offering.

Read on and we hope this helps.


Choose Your Name Wisely

It’s all in a name they say. It has to make sense. Oh, that’s what it’s for!

When creating workflow statuses, transitions, and even resolutions, naming should be considered very carefully. Make sure that names are as short and concise as possible, and that they MAKE SENSE to anyone looking at them. Avoid names with similar meanings or names which require consulting a dictionary.

Keep it simple, make sure it reflects your business, and is written in a language that anyone who just knows your business on a very basic level could even understand.

Once you’ve got that down, the following can be added as icing on the cake:

  • Status Names: try to always use NOUNS for your status names (e.g., Asset Owner Approval, Review) or a phrase describing the state (e.g. Awaiting Asset Owner Approval, Awaiting Review, Waiting for Customer)
  • Transitions: use VERBS for the names of transitions (Consider verbalizing the last action performed (e.g. Approved by Asset Owner, Reviewed) or the next action to be performed (e.g. To Review, Get Approval) or something that makes sense to your stakeholders.)
  • Resolutions: use VERBAL ADJECTIVES for the names of resolutions as they have to describe the conclusion of the ticket appropriately (e.g. Approved, Rejected, Done).

step names (status names)

The step names (status names) in the above image are short and concise; and are mostly nouns (or descriptive phrases); whereas the transition names under Transitions(id) column are mostly verbs reflecting the action to be performed.

Lastly for choosing names, try to make the names of your statuses as distinct as possible, but also consider making them reusable for future workflows (e.g. Awaiting Approval is a status name that could be easily reused, however if a status is named Awaiting < enter your stakeholder here >'s Approval, this restricts the usage only to processes in which the stakeholder role is present).

Properties Please

The bright red house with tinted windows on 15th Street. The spicy Thai curry.

In these examples, each of the highlighted properties for the house and for the curry tells us more about the item in question. The same is true for workflow properties in Jira. They not only help you define:

  • what is shown to users (e.g. Options of a custom field),
  • when it is shown (e.g. during a step or during a transition),
  • which group of users can perform what action when (e.g. only members of role A can edit the issue when it is in the done status), and
  • it also helps the admin ensure that workflows are as concise as much as possible (e.g., define what resolution field options are shown in a specific project).

Properties are usually entered in this format:

  • property key: the assigned key of the property you are applying to the workflow (e.g. jira.field.resolution.include which states the resolutions to be included in the workflow property) and
  • property value: the value you are parsing to the property key. When multiple values are to be entered, separate them with a ‘,’. (the property values are either in the form of ids: ‘10000,11000,11011’ or strings: ‘jira-administrators’)

(Info) Enter respective properties on new lines but keep similar properties in one entry to avoid duplication.

Some great examples of the use of properties include:

Property What it does Where you put it
jira.field.resolution.include By default, Jira shows us all options on the instance in the resolution field. This property allows us to narrow that list down to just the relevant ones, using the resolution IDs. Transition
jira.permission.edit.denied Project permissions set what's allowed by whom on the project level. But we can narrow that down even further on the status level. For example, making it so users cannot edit an issue when it's in the Closed status.
    Status
opsbar-sequence Jira shows you three transition options on an issue. If there are more options available in the workflow, Jira will show two options and then a dropdown with the remaining. This property allows us to define the order of these transition buttons when a user views the issue. The lower the number, the further left the transition button appears. Transition

Accessing the workflow via the diagrams screen

Accessing the workflow via the diagrams screen

Properties are entered in a Key, Value pair. The diagram is the presentation for Workflow Step properties.

Properties are entered in a Key, Value pair. The diagram is the presentation for Workflow Step properties.

The diagram shows Workflow transition properties. This i18n property key (jira.i18n.title) for example allows for the translation of the transition.

The diagram shows Workflow transition properties. This i18n property key (jira.i18n.title) for example allows for the translation of the transition

With so many options available, where do we find them all? The following are two resources that are helpful:

However, there are some drawbacks to the above which tie back to the first point mentioned: proper documentation:

  1. Changes made here are only visible to the Jira Administrator. When an error occurs, it is the job of the administrator to properly diagnose the error as the error returned to users can be quite confusing.
  2. When a resolution is removed, its ID still remains in all workflows that used it. When migrating, this could lead to issues as you do not know what the ID is related to.
  3. Properties would mean more frequent changes to your workflow: For example, more permissions needed, people shouldn’t be able to add attachments, etc. As a process changes, so do the tasks for the admin.

Once you are aware of the power of properties and you have documented your processes properly, you have less to worry about. Tweaking and making changes would come as a breeze with time.

Resolutions Matter

Often times, you see tickets in the status Done, Completed, Canceled, Rejected. Yet people have equally complained, “We have all these tickets completed, but our reports show a different number,” or “Although this ticket has been re-opened, it appears as resolved in our reports.”

This, my friends, is why I say “Resolutions Matter.”

By default, Atlassian Jira only considers tickets with a resolution set as resolved. As a Jira Administrator, it is then your responsibility to ensure that when a ticket is going to the final state you can either:

  • prompt people to set a resolution by adding a screen to the transition leading to the final status, and on this screen adding the Resolution field or
  • you automatically set a resolution for the tickets by making use of post-functions.

Likewise, when a ticket is reopened, remember to use a post-function to clear out the resolution field. There is nothing nice about seeing a ticket giving you false information in your reports, but before blaming the tool, consider checking your process flow and ensuring that the right resolutions are set when they need to be set.

Extending Jira Workflows

As comprehensive as any designer may think his/her product is, there are often one or two things the tool right out of the shed cannot provide. This is equally true here as the amount of customizations possible are quite limited. Fortunately for us all, Atlassian provides a Marketplace and encourages independent developers to build upon the platform. These come in the form of add-ons. Here are a few ways in which you could further extend your Jira workflows:

  1. Familiarize yourself with workflow add-ons. Understand the Atlassian marketplace and how to access the various add-ons available there and what they have to offer. Add-ons such as Jira Suite Utilities, Jira Misc Workflow Extensions, Scriptrunner, Jira Workflow Toolbox or Power script extend the possible admin functionalities of your Jira workflow, however, learn the ramifications of their failures should an error occur. Also, learn when to implement a solution based on one rather than the other. For example, if I have to create a single sub-task or make a field required, I would likely consider a tool like Jira Suite Utilities as it provides a much easier user implementation. However, for something more complex, such as, I need 15 sub-tasks assigned to multiple users with specific fields to be set being a requirement, I would look to either Scriptrunner or Power script or even a custom add-on development for such an implementation as they tend to be much cleaner and more practical to manage.
  2. The add-on Glass Project Documentation is a tool that I feel will greatly help with documenting your respective projects. It also makes it easier to pull all information about your project’s configuration and save this to a Wiki or export as a PDF. This is a fairly new add-on and it could have some unknown bugs so I will recommend using it cautiously. The vendor is however quite friendly and is happy to assist should you have problems.

Conclusion

I hope this is not too much information to take in. There is so much more, and please note that the above may be considered “best practice,” however apply each based on your own specific scenario.

See you all for the third part of this series. Give us feedback or suggestions if you like. I have learned a lot from reading similar articles.