How do I build the workflow I want?

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

The way tasks and processes are managed in Jira Core is through workflows. A workflow maps out the steps and statuses that a task can go though, and defines your process.

If your team does work that's more complicated than "to do, in progress, done", then you'll need to customize the way your typical processes are set up. You can edit the overall workflow used in a project, or modify the way particular task types are handled in the workflow.

Here's an example workflow for making website updates:

You need to be a Jira administrator to create and edit workflows.

Key workflow components

Jira Core workflows are made up of several key components:

Status: current state

Statuses represent the current state of the piece of work. A status usually aligns to the stage of a process, for example 'scoping', 'drafting' or 'review'.

Transitions: change events

Transitions are the actions that move a task between statuses, e.g. 'Sent to review'. 

Resolution: final state

When a task is finalised, and no longer open, it needs a resolution status.

The resolution closes the issue and represents the final state of the piece of work. For example, "done", "published", or "rejected".

Workflow steps are mapped to board columns

If you use boards, you'll notice there's a correlation between your workflows order and your board. Each step of a workflow is associated with a column on the board.

They may correlate one to one, or there may be multiple workflow steps associated with one column. For example, an issue with the workflow steps "draft", "review", "approve" might all appear in the "In progress" column.

Keep workflows simple

Jira Core workflows are designed to make your work processes easier, so make sure you keep them as simple as you can. Here's an example of a simple editorial process:

In the example above, a piece of work can only move forward in the process. However, we can simplify it a lot further by creating a review loop, instead of separate review statuses.

The loop allows us to move our work back and forth in a draft and review cycle. 

To help you simplify processes, map them out in full (like the top example), then look at where you can consolidate steps. Remember that each step represents the current state of a piece of work, so if it can be in one state multiple times, consider having only one status to reflect this.

tip/resting Created with Sketch.

Don't create a custom workflow for every variation of task that you do. Try to re-use workflows for as many processes as you can.

Update a project's workflow

If your project has a workflow that's pretty close to what you need, you can update it by adding statuses and transitions to suit your needs.

To update the existing project workflow:

  1. Go to the Jira icon (, , , or) > Projects, select a project, then click Settings 
  2. Choose Workflows
  3. Click the edit pencil to the right of the workflow
  4. Do either or both of the following:
    • Click Add status to add a new step to the workflow (you can add existing statuses or create new ones)
    • Click Add transition or drag from a node on one status to another to add a transition

      tip/resting Created with Sketch.

      To change to a different initial status (the first one after the circle), click the transition line then drag the arrow from the existing initial status to your new one.

  5. Click Publish Draft

When you publish your new workflow, Jira will ask you if you'd like to save a copy of the original. If you're not sure about your changes, or you just like to be cautious, save a copy of the original workflow so you can re-apply it to your project should you need to.

Here's a shot of the workflow editor in "diagram" mode. It lets you add statuses and draw transitions between them. Here we've added an approval stage and a Rejected resolution for those issues that aren't approved.

tip/resting Created with Sketch.

Notice the nodes on the "Approved" status in the example below. They appear when you hover over a status in the workflow designer. Click and drag from the nodes on one status to the nodes on another status to quickly add a transition.

In this example, you need to approve an issue (it'll then transition it to the Approved status) before you can complete it (transition it to Done). From Done, if the issue needs more work, you can either reopen it (transition it to Approved again) or send it to be reassessed for approval (transition it to the To Do status).

For more on creating and editing workflows, see Working with workflows.

Consult all stakeholders

If your process involves multiple people, teams or groups, then you need to develop a workflow that meets everyone's needs. Get stakeholders in a room to talk about requirements and minimum must-haves. Here are some things to think about:

  • What are the basic steps in the process? What steps are done by each group, team or person? Are any steps repeated or looped, such as review steps or approval gates?
  • What information is required to complete the process? For example, is there a request form? Are there designs or assets involved? What is the final output?
  • What restrictions does there need to be to ensure that the process is followed? For example, can some steps only be done by some people? Who are the approvers?

tip/resting Created with Sketch.

Low-tech tip: use a whiteboard to create a flow diagram that everyone can see and agree on.

Create a new workflow

If there isn't an existing workflow to meet your needs, you can create a new one then use it with your project.

  1. Go to the Jira icon (, , , or) > Settings > Issues
  2. Choose Workflows
  3. Click Add workflow at the top-right
  4. Do both of the following until you've built your workflow:
    • Click Add status to add a new step to the workflow (you can add existing statuses or create new ones)
    • Click Add transition or drag from a node on one status to another to add a transition

      tip/resting Created with Sketch.

      To change to a different initial status (the first one after the circle), click the transition line then drag the arrow from the existing initial status to your new one.

  5. Click Publish Draft
  6. Select the new workflow to use with your project
    1. Go to the Jira icon (, , , or) > Projects, select a project, then click Settings
    2. Choose Workflows
    3. Click Add workflow and choose Add Existing
    4. Select your new workflow and click Next
    5. Choose the issue types that'll use this workflow and click Finish
    6. Click Publish and click Associate to migrate any existing issues to the new statuses in your workflow

Manage task actions through transitions

You can take control over how your issues behave as they are progressing through the workflow by customizing transitions. For example, you can make sure issues are always assigned to a certain person when they are in a certain status. 

Note that this is an advanced task.


Control status changes using conditions

Use conditions to determine who can change issues from one specific status to another. For example, make it so that only a particular assignee (like a reviewer) can change the issue status to "Ready to publish".

Set up validation tasks

Use validators to ensure that a status change gets validated before it happens. For example, before changing to a Review status, a validator can check if a draft is ready.

Create automatic actions

Use post-functions to trigger specific changes on issues after they've passed conditions and validators. For example, you can set a post-function to make sure a resolution reason is always given when the resolution is set. 

Control assignees for specific statuses

You can make it so that whenever an issue status is changed, it forces the user to choose a new assignee. This ensures that the next part of the work gets one by the right person.

Manage transition properties

Jira Core recognizes some properties on transitions. The most common one is to limit resolutions displayed to the user on a given transition. For example, we might want the resolution scratched to show up for disk media when retiring, but not for books.

For more information about these tasks, see Advanced workflow configuration.

tip/resting Created with Sketch.

Get the most out of your workflows

  • Before you edit a workflow make sure it isn't being used by any other projects! Any changes made to a shared workflow will impact all the projects using it.
  • To re-use a workflow in another project, select "Create with shared configuration" when you create the new project or update the default workflow in the new project to the one that you want.
  • Remember to hit Publish to make new or edited workflows active in your project.

Other useful resources

Last modified on Mar 7, 2018

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.