Working with workflows

Still need help?

The Atlassian Community is here for you.

Ask the community

  A Jira workflow is a set of statuses and transitions that an issue moves through during its lifecycle and typically represents processes within your organization. There are default built-in workflows that cannot be edited; however, you can copy and use these workflows to create your own.

You can also create your own workflows from scratch, or import workflows from Atlassian Marketplace. Workflows can be associated with particular projects and, optionally, specific issue types, by using a workflow scheme.

You need to log in as a user with the Administer Jira global permission to access and manage workflows.

 Here's an example of a default workflow:

Statuses and transitions

A status represents the state of an issue at a specific point in your workflow. An issue can be in only one status at a given point in time. When defining a status, you can optionally specify properties.

transition is a link between two statuses that enables an issue to move from one status to another. In order for an issue to move between two statuses, a transition must exist. 

A transition is a one-way link, so if an issue needs to move back and forth between two statuses, two transitions need to be created. The available workflow transitions for an issue are listed on the View issue screen.

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 issue types that use this workflow.

Workflow status Description

Inactive workflow

An inactive workflow is a workflow that is not currently being used by any projects. Because there are no issues currently transitioning through an inactive workflow, you can edit the workflow's steps and transitions directly. For details on activating a workflow, see steps below. For more detailed information, see Working in text mode.

Active workflow

An active workflow is a workflow that is currently being used by one or more projects. When you edit an active workflow, Jira first creates a draft of it, that you can then modify as you see fit. When you've finished, you can publish your draft and, optionally, save your original workflow as an inactive backup.

The following limitations apply when editing the draft for an active workflow:

  • It is not possible to edit the workflow name (only the description) if a workflow is active.
  • Workflow statuses cannot be deleted.
  • If a status has no outgoing transitions (Global transitions are not considered), it cannot have any new outgoing transitions added, regular or global. 
  • The step ID cannot be changed. See Cannot Add Transitions or Delete Steps in Draft Workflows.

To make any of the modifications listed above, you need to copy the workflow (see Creating a workflow), modify the copy, and then activate it. 

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 the Jira icon (, or ) > Settings > Issues.
  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 an issue type is not defined in the project's issue type scheme, that specific workflow is not used):

  1. In the sidebar, click Issue type schemes. You'll see which workflow scheme the project currently uses.

  2. Click Associate to begin the migration process. Each issue needs to have a valid status, so you may need to assign statuses to a select number of issues after you switch workflow schemes. 

A Jira project must always be associated with a workflow scheme, since all issues 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 the Jira icon (, or ) > Settings > Issues.
  2. Click Workflows Edit your selected workflow.
  3. Click the Text tab > Add Transition. Then fill in the details. 

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.

Adding a status to a workflow

  1. Select the Jira icon (, or ) > Settings > Issues.
  2. Click Statuses Add status.

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.
tip/resting Created with Sketch.
  • Statuses are global objects. Changing the name of a status on one workflow also changes it in all workflows that use that status.
  • Hover over a transition or a status to see the relevant transition labels. 
  • Zoom the diagram with your mouse wheel. Pan the diagram by clicking and holding the mouse while on white space, then moving your mouse across the diagram.
  • You cannot clone transitions in the workflow designer.
  • You cannot create annotations in the workflow designer.
  • You cannot directly set the issue. editable  property. To do this, simply add the issue. editable property to the status properties.
  • The workflow designer will automatically validate your workflow and highlight any statuses that have no incoming or outgoing transitions. The workflow validator will also highlight all transitions that have an invalid permission condition that you don't have available in Jira. The validator is particularly useful if you import workflows, or deal with complex workflows.

Creating workflows

Check out Adding and deleting an issue workflow for more information on the ways to import and create workflows. 

Configuring workflows

Check out Editing an issue workflow for more information about editing workflow triggers, transitions, validators, and post functions.  

Setting the resolution field

In Jira, an issue is either open or closes, based on the value of its 'Resolution' field — not its 'Status' field.

  • An issue is open if its resolution field has not been set.
  • An issue is closed if its resolution field has a value (e.g. Fixed, Cannot Reproduce).

This is true regardless of the current value of the issue's status field (Open, In Progress, etc). Therefore, if you need your workflow to force an issue to be open or closed, you will need to set the issue's resolution field during a transition. There are two ways to do this:

  • Set the resolution field automatically via a post function.
  • Prompt the user to choose a resolution via a screen. See Working in text mode for details on this.

Renaming workflow transition buttons

If you copied the system workflow and you wish to rename the workflow transition buttons on the View Issue 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.

Last modified on Jul 13, 2018

Was this helpful?

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