Working with workflows

To access and manage workflows, you must be logged in as a user with the Jira administrators global permissions.

Users with project admin rights can’t create new workflows and have limited editing permissions. They can only edit non-default workflows and any workflows that aren’t shared with other projects.

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.

You can create workflows from scratch, copy the existing ones, or import workflows from Atlassian Marketplace or an file. Workflows can be associated with particular projects and, if needed, specific issue types using a workflow scheme

There are default built-in workflows that can't be edited, but you can copy and use these workflows to create your own.

On this page:

Here's an example of a default workflow:  

Workflow statuses and transitions

A status represents the state of an issue at a specific point in your workflow (e.g. "In progress"). An issue can be in only one status at a given point in time. When defining a status, you can specify properties if needed. 

A transition is a link between two statuses that enables an issue to move from one status to another. To move an issue 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.

See Defining a screen for details on adding and configuring issue screens.

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

Workflow statusDescription

Inactive workflow

An inactive workflow is a workflow that isn't currently being used by any projects. Since there are no issues currently transitioning through an inactive workflow, you can edit the workflow's steps and transitions directly.

To edit an inactive workflow, see Working in text mode.

tip/resting Created with Sketch.

Your changes will be automatically saved as you edit an inactive workflow. You won’t need to manually save or publish your changes.

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 so you can modify this workflow 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 a draft for an active workflow:

  • You can’t edit a workflow’s name if the workflow is active. You can only edit its description.

  • You can’t delete a workflow status if any issue has that status. You’ll need to move the issues to another status or project, and then delete the status.

  • The step ID (step’s name) can’t 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. 

You can access all the active and inactive workflows that exist on your Jira instance from the Workflows tab:

Active workflows are at the top of the page with the inactive ones listed underneath. Selecting the Inactive tab will expand the list of workflows that aren’t associated with any schemes or projects:

If you want to make the inactive workflow active, follow guidelines from Activating a workflow.

Using the workflow designer

 

You need to log in as a user with the Jira system administrators global permission to work with the workflow designer.

The workflow designer is a graphical tool that allows you to view a workflow’s layout, and create and edit its statuses and transitions. To access the designer, you only need to start editing a particular workflow.

With the workflow designer, you can:

  • Manage statuses and transitions by adding, clicking, and dragging.

  • Modify or delete workflow properties to update certain statuses and transitions. Note that you can delete the properties 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 status.
  • 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. Learn more on the Advanced workflow configuration page.
tip/resting Created with Sketch.

Statuses are global objects. Changing a status name on one workflow also changes it in all workflows that use that status.

Tips for using the workflow designer
  • Hover over a transition or a status to see the relevant transition labels. 
  • Use your mouse wheel to zoom into the diagram. Click and hold on white space to move across the diagram.

  • You can't clone transitions in the workflow designer.
  • You can't create annotations in the workflow designer.
  • You can't directly set the issue. editable  property. To do this, 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 a workflow

There are a few ways you can start a new workflow. These include cloning an existing workflow, creating a new workflow, and importing a workflow.

Copy an existing workflow

  1. In the upper-right corner of the screen, select Administration  > Issues.

  2. In the left-side panel, select Workflows to open the Workflows page, which displays all of the workflows in your system. 

  3. Copy an existing workflow by selecting the Copy link in the Actions column. Enter a workflow name and description, then select the Copy button
  4. Customize your workflow by adding or editing steps and transitions.

When you've finished customizing your workflow, see Managing your workflows for details on how to use it with a Jira project.

Create a new workflow

  1. In the upper-right corner of the screen, select Administration  > Issues.
  2. In the left-side panel, select Workflows.
  3. lect Add workflow.

  4. Enter a name and description for your workflow and then select Add.

    The workflow opens in edit mode, and contains a step called Open and an incoming transition called Create.

  5. Continue with your workflow customizations, by adding and editing statuses and transitions. 

    To edit or remove already added elements, select a particular status or transition and use editing options in the panel that appears.

  6. Make the workflow active by associating it with a workflow scheme for a particular project. See Configuring a workflow scheme outside of a project for details.  

Import a workflow

Follow guidelines from Importing workflows.

Configuring a workflow

Edit a project's workflow

If you can’t change or remove statuses or transitions when modifying an existing workflow, check out these articles for assistance:

Whenever you create a new Jira project, your project automatically uses the default workflow scheme. The scheme associates all available issue types in the project with the Jira system workflow.

Jira system workflows are read-only and can’t be edited. Jira creates an editable copy of the system workflow and workflow scheme for your project.

To edit a workflow:

  1. In the upper-right corner of the screen, select Administration  > Projects.
  2. Select the relevant project.

  3. In the Workflows section (left-side panel), select Workflows.

  4. Select the pencil icon in the Actions column to edit the workflow. As you enter the edit mode, Jira automatically does the following:


    • creates a draft copy of the system workflow named "Your Project Name Workflow (Draft)"
    • creates a new workflow scheme for the workflow named "Your Project Name Workflow Scheme"
    • associates any existing issues in your project with the new workflow
  5. You can now edit your draft workflow. Click on a status or transition to see editing options in the panel that appears.
  6. When you've finished editing, select Publish. The dialog allows you to publish your draft and, optionally, save your original workflow as an inactive backup.
Tips on performance when modifying workflows
  • The number of issues impacts the speed when configuring a workflow. For small numbers of issues, this process is relatively quick. However if you have many (e.g. thousands of) existing issues in your Jira project, this process may take some time. 
  • Once this process begins, it can’t be paused or canceled. Avoid editing or transitioning any issues within your project while this process is taking place.

Replace a project's workflow

If you want to use a different workflow in your project, you need to associate the current workflow scheme with a new workflow of your choice. See Configuring workflows for a workflow scheme.

Set the resolution field

After you finish working on a particular issue, you’ll likely need to update the issue and indicate that the work has been done. To achieve this, you need to set the “Resolution” field for the issue.

Note the difference between the Resolution and Status fields. The Resolution specifies why an issue is closed, while Status indicates an issue’s position in its workflow.

In Jira, an issue is either open or closed based on the value of its “Resolution” 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:

Rename 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.

Work 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.

Deleting a workflow

Delete a project’s workflow

You can't delete a workflow that's assigned to a workflow scheme. First remove the workflow from the scheme and then delete the workflow.

  1. In the upper-right corner of the screen, select Administration  > Projects.
  2. In the Workflows section (left-side panel), select Workflows.

  3. Scroll down to the Inactive tab and expand it to view the list of all inactive workflows.

  4. Find the relevant workflow, then select Delete.

Advanced workflow configuration

See the documentation on Advanced workflow configuration.

tip/resting Created with Sketch.

Do more with Jira

Customize the behavior of workflow transitions with advanced workflow configuration and discover even more ways to configure workflows with top workflow apps on the Atlassian Marketplace.

Last modified on Sep 24, 2022

Was this helpful?

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