Best Practices for Creating a Custom Workflow

If you’re on a software team, you probably use the default Jira workflow or something close to it.  But what if you’re on a business team or the default options don’t fit the way you want to work?  Then it’s time to create a custom workflow.

A workflow is a standard set of statuses (steps) and transitions (movement between steps) that each issue follows in its lifecycle.  Statuses take an idea from “conception” to “completion”.  Each Jira project can have its own workflow and each issue type within a project can have its own workflow as well.  For example, the Legal team has a specific process for contract review and a general process for all “other” types of requests.  Their Jira project might include issue types like the standard “Task” and a custom type like “Contract.”

• The “Task” issue type has a very simple workflow, with the statues “To Do” and “Done.”
• The “Contract” issue type requires additional statuses for approval and execution steps that occur in a contract review process.

  RECOMMENDATION
In the beginning, keep workflows as simple as possible, until you’ve uncovered a deficiency or process step that needs special attention.

Custom Workflow Tips

The steps below outline the best practices for creating a workflow:

1. Before creating a new custom workflow, have the user explain their real life process to you.  The workflow should be as simple as possible.
2. First, draw (preferably on paper) a workflow to ensure it makes logical sense and all forward and back transitions are accounted for.  You can use the “Custom Workflow Documentation” template in the Jira Strategy Admin Workbook or in ThinkTilt’s Process Template library as a way to communicate and document workflows.
3. After drawing the workflow, write the workflow out in words. This can uncover additional needs you may have neglected to draw or consider.
4. Include logical backwards transitions so users can self-manage issues.
5. Give users options to abandon or stop progress on issues at appropriate times.
6. Give project-level administrators appropriate options to fix improperly transitioned issues.
   • Example:  Include a “reopen” transition button in the final status to address issues that were improperly closed.
7. Use transition conditions sparingly.  If a condition is needed, set the restriction to a project role, rather than to an individual, for easy maintenance.
8. Use transition validators and post functions to minimize the amount of manual work a user has to do.
   • Automatically assign an issue to the reporter when moving to an “information needed” or “verification needed” type of status.
   • Automatically assign an issue to the Project Lead in a “triage” type of status.
   • Automatically move a parent issue to “In Progress” when a child issue starts progress.
9. Name your statuses:
   • Name statuses so they reflect the current state.  Good status names immediately tell a user what is occurring and what state an issue is in the workflow process.  For example, “Pending Review”, “In Review”, “Being Reviewed”, “Awaiting Review”, etc.
   • Make any status names short and easy to understand what is happening.  Long, multi-word names are harder to query and may be truncated on certain screens.
10. Name your transitions:
    • A Transition name should be short and reflect an action taken.
    • Good transition names immediately tell a user what action to perform to progress an issue.  Example:  For an issue in “Pending Review” status, a good transition name would be:  “Review Complete.”  If you need a “pass/fail” situation, where an action must pass a test before a transition can occur, good transition names would be:  simply “Pass” and “Fail.”
    • Bad transition names confuse the user about how to move forward.  Example:  “Review.”  A transition button should signify the start or end of an action.  The word “Review” is ambiguous.  If a user clicks “Review,” does that mean they should start a review or that the review has already occurred?

It’s easy to customize workflows and therefore easy to go overboard, creating more structure than you really need.

Phased Approach

It’s certainly possible to capture every little step in your work process and build that into a complex and long Jira workflow.  An alternative however, is a phased approach.  Simply break your process into phases that represent a collection of smaller steps.  The phases represent key decision points. An issue can’t be moved to another phase until the requirements of that phase have been satisfied.  Your Jira status represents the entire phase, rather than a status for every small step in the phase.

Example:  Your company is signing a partnership agreement 
The contracts process requires a review of the contract by both parties and potential edits before final execution.  It’s a predictable process requiring a short workflow like:

Open > In Review > In Execution > Closed

  TIP
A generically named status like “In Review” is better than a legal-specific name like “In Contract Review”.  Other Jira projects can use the generic version regardless of what type of thing needs review.  You want to share assets and schemes between projects as much as possible.

The Legal team is doing many things in the background that may not need to be reflected in the workflow.  For example:

In the “In Review” phase, the Legal team is reviewing the contract, researching legal topics, communicating with internal teams, negotiating terms with the external company, etc.

In the “In Execution” status, the CEO is finding his favorite signing pen, both companies are trading paperwork, and your Legal team is entering the final result into their contracts database.

In the above example, is it useful to create a status for every step that occurs in the contracts process?  Do you need to track how many times the contract was modified during the review process?  Do you need to track which parties have signed the agreement so far?  If the answer is “no” a phased approach may be more useful.  Also, it might be more useful to track signature collection in a custom field.

  RECOMMENDATION
If you’re not going to report on something (ex: “How many contracts have been signed by us?” in the above example) that status or custom field may not be necessary or useful.

Don’t over-complicate your custom workflow with steps and statuses you don’t really need.  Your end users will thank you for it.