Work with work item workflows

A Jira workflow is a set of statuses and transitions that a work item moves through during its lifecycle, and typically represents a process within your organization. Workflows can be associated with particular projects and, optionally, specific work types by using a workflow scheme.

Jira has built-in workflows that you can use without needing to make any changes, or you can start fresh and create your own. You can't edit the built-in workflows, but you can copy them and use the copy as a basis to create your own.

Another option is to import workflows from the Atlassian Marketplace.

 Here's an example of a default workflow:

Statuses and transitions

Two concepts define a workflow:

1. Statuses: the steps in your team’s working process that describe the state of a task. Read more about statuses

2. Transitions: usually, how a piece of work can move between statuses. In order for a work item to move between two statuses, a transition must exist. A transition is a one-way link, so if a work item needs to move back and forth between two statuses, two transitions need to be created. The available workflow transitions for a work item are listed on the View work item screen. Transitions can also be "looped," meaning the status remains the same. These transitions are used to open transition screens so users can perform actions without setting a new status or for workflow triggers.

Active and inactive workflows

There are slight differences between editing an inactive and an active workflow. We place restrictions on the modifications you can make to an active workflow, due to the impact the changes will have on projects and/or work types that use this workflow.

Activating a workflow

All workflows are inactive until you associate them with a workflow scheme, which can then be associated with a project. To activate a workflow: 

1. Select > Work items.

2. Click Workflow schemes.

3. Either click Add workflow scheme or edit an active workflow scheme. 

4. Add your workflow to the scheme. (See Configuring workflow schemes for more detailed information.)

To finish activating your workflow, associate the workflow scheme it's in with a project (if a work type is not defined in the project's work type scheme, that specific workflow is not used):

1. In the sidebar, click Work type schemes.

2. Click Associate to begin the migration process.

Each work item needs to have a valid status, so you may need to assign statuses to a select number of work items after you switch workflow schemes. 

A Jira project must always be associated with a workflow scheme, since all work items must move through a workflow. To disassociate a custom workflow scheme from a project, simply associate that project to the default workflow scheme instead.

Adding a transition to a workflow

To add a transition, open your workflow in text mode:

1. Select Settings (), then Work items.

2. Select Workflows, then for the workflow you want to update select More () then Edit.

3. Select the Text tab, then Add transition.

4. Fill in the details then select Add.

   • Alternatively, select Reuse a transition to if you have multiple statuses that need to transition to the same status. For example if you have To do, Backlog, and Triage statuses that all need to transition to In progress, you can select Reuse a transition instead instead of creating 3 different transitions. Note that transitions can’t be used across workflows.

In the Transition View field, select either:

• No view for transition — choose this if you do not need to prompt the user for input before the transition is executed (i.e. the transition will occur instantly when the user clicks the transition).

• Or, the name of a screen (from the dropdown menu) that will be shown to users, asking for input before the transition is executed. You can choose one of Jira's default screens or any other screen you have created. If no existing screen is suitable, you may wish to create a new screen for the transition.

You can edit a transition to a workflow by following the first two steps above, then:

1. Select the Text tab, then in the Transitions (id) column, select the name of the transition you want to update.

2. Select Edit.

3. Edit the details of the transition, then select Update.

For transitions to Done statuses, we also recommend adding a post-function to ensure that Resolutions are automatically set.

Adding a status to a workflow

See Add statuses to a Jira workflow to learn about adding statuses to an existing workflow.

Add a work item action

Transitioning a work item can mean moving it to another status, or performing a "looped" transition where the transition allows you to perform an action but keep the work item in its current status. We refer to these looped transitions as work item actions. Sometimes you may just want to perform an action to a work item without moving its status through the workflow.

To add a work item action:

1. Select > Work items.

2. Click Workflows > Edit your selected workflow.

3. Click Add Transition.

4. Select a From status. If you choose Any status, your work item action will be able to be performed from anywhere in the workflow. Otherwise, it can only be from the status you choose.

5. For To status, select Itself.

6. Choose a name and fill in the rest of the details, then select Add when you're done.

Actions show on the work item next to the status like this:

Workflow designer

 The workflow designer is a graphical tool that allows you to see the layout of your workflow and to create and edit a workflow's steps and transitions. You will need to log in as a user with the Administer Jira global permission to access the functionality described below.

With the workflow designer, you can:

• Manage status and transitions: add, click and drag, or select to edit properties (Workflow properties) to rename, or delete (from the workflow but not Jira).

• Add a global transition that allows every other status in the workflow to transition to the selected status. Select Allow all statuses to transition to this one in the properties panel for the transition.

• Change the screen that a transition uses. See Working in text mode for details.

• Configure advanced transition options, such as triggers, conditions, validators, and post functions. See the Advanced workflow configuration page.

Creating workflows

Check out Adding and deleting a work item workflow for more information on the ways to import and create workflows. 

Configuring workflows

Check out Editing a work item workflow for more information about editing workflow triggers, transitions, validators, and post functions.  

Setting the resolution field

In Jira, a work item is either open or closed, based on the value of its resolution field (not its status).

• A work item is open if its resolution field isn't set.

• A work item is closed if its resolution field has a value (fixed or can't reproduce, for example).

This is true regardless of the work item’s current status (open or in progress, for example). If you need your workflow to force a work item to be open or closed, you will need to set the resolution field of the work item during a transition.

Renaming workflow transition buttons

If you copied the system workflow and you wish to rename the workflow transition buttons on the View work item page, you must delete the following properties from all transitions in the copied workflow:

• jira.i18n.title

• jira.i18n.description

Otherwise, the default names (i.e. values of these properties) will persist. Read more about transition properties.

Working in text mode

Text mode is an advanced way of working with workflows, and it shows the difference between steps and statuses. In text mode, you work directly with steps. For details, see Working in text mode.

Advanced workflow configuration

See the documentation on Advanced workflow configuration.