Configuring Workflow

A JIRA workflow is the set of statuses and transitions that an issue goes through during its lifecycle.

Workflows typically represent business processes.

JIRA ships with a built-in workflow called jira, which is the default system workflow and cannot be edited. However, you can make copies of this workflow to get started creating your own workflows quickly. You can also create your own workflows from scratch, or import them from Atlassian Marketplace, if you prefer. Each workflow you create can be associated with particular projects and, optionally, specific issue type(s) by using a workflow scheme.

JIRA's default system workflow

What is a status?

A status represents the state of an issue at a particular point in a specific workflow. An issue can be in only one status at a given point in time.

When defining a status, you can optionally specify properties.

What is a transition?

A 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, shown here.

Editing a workflow

Editing a workflow means that you are modifying the statuses and transitions that make up a workflow. There are slight differences between editing an inactive and an active workflow, described below. 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.

Active versus inactive workflows

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 simply edit the workflow's steps and transitions. For details on this, see Working in text mode.

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, as shown here.

You can then modify the draft as you see fit. Once you have finished modifying your draft workflow, you can publish your draft and, optionally, save your original workflow as an inactive backup.

Limitations when editing an active workflow

Please note that the following limitations apply when editing an active workflow (i.e. a draft workflow):

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

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

Workflow designer

Workflow designer, also referred to as Diagram edit mode, allows you to visualize the entire layout of your workflow as well as create and edit a workflow's steps and transitions. For versions of this feature prior to JIRA 6.1, see Classic mode workflow designer.

The JIRA workflow designer looks like this:

Statuses in the workflow designer

There are a number of different actions you can perform with statuses in the workflow designer. By selecting a status, extra information and actions also become available in the Properties panel on the right-hand side of the screen, where you can:

  • Add existing status – gives you a list of existing statuses to choose from.
  • Create new status – displays a dialog where you can create a new status in your JIRA instance.
  • Edit a status – lets you change the name and description of the status.
  • Remove a status – removes the status from the workflow, but not the JIRA instance.
  • Move the status on the screen – click and drag the status to reposition it in the diagram. Geometric snap lines appear to help you align the status with other statuses in the workflow.
  • Edit properties – properties are advanced configurations on a workflow. Please see Workflow properties for details.
  • Add a global transition – global transitions are transitions that allow every other status in the workflow to transition to the selected status.

Diagram showing a selected status, and the operations that can be performed on statuses

(info) Note: Statuses are global objects in JIRA. Changing the name of a status on one workflow also changes the name of the status on all workflows that use that status.

Transitions in the workflow designer

There are a number of different actions you can perform with transitions in the workflow designer. When you select a transition, additonal information and actions become available in the Properties panel on the right-hand side of the screen, where you can:

  • Add a transition – dragging a port of any status to a port of another status (see the illustration on the right) creates a new transition between the two statuses.
  • Reposition a transition – selecting a transition highlights the two endpoints of the transition with black dots. Clicking and dragging either of those dots gives you the ability to reposition a transition around its given status.
  • Delete a transition – click the Delete transition button or just use the delete key on your keyboard.
  • Edit a transition – lets you change the name and description. You can also change the screen that the transition uses, see  Working in text mode for details.
  • Configure advanced options – such as properties, post functions, conditions and validators. Please see the Advanced transition configuration  section below.


Drag a port from one status to another to create a new transition


Diagram showing a selected transition and the operations that can be performed on transitions

Workflow designer tips

  • Hover over a transition or a status to see the relevant transition labels. 
  • When dragging a status on the page, the red lines that display are geometric snap lines that can be used snap to other statuses.
  • 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.
  • On the View Issue page, all statuses except the current one are displayed with the white background and blue text. The current status displays a blue background with white text to give it more prominence.
  • The older Flash version of the workflow designer is still accessible from classic mode. For more information, see Classic mode workflow designer

Advanced transition configuration

When defining a transition, you can optionally specify:

  • A screen to be displayed to the user — this is useful if you need the user to provide input before completing the transition.
  • Conditions — these control who can perform a transition (i.e. who can see the transition link on the View issue page).
  • Validators — these check that any user-supplied input is valid before performing the transition. 
  • Post functions — these perform particular actions, such as:
    • Assign the issue to a particular user.
    • Send an email notification.
    • Update a field in the issue.

For more information on working with conditions, validators, and post functions, see Advanced workflow configuration.

Workflow transition screen, displaying the steps that use this transition (at the top) as well as the conditions available (at the bottom)

Transitions into and out of a specific step (the "In Progress" step)

Differences from the classic mode

JIRA workflow designer changes

Features that exist in the classic mode of the Flash-based workflow designer, but not in the current workflow designer:

  • Create common transitions
  • Clone transitions
  • Global transitions with no result status
  • You cannot reassign the target of a transition – in other words, you cannot grab the arrow and make it point to something else – you need to remove the transition and recreate it instead
  • You cannot directly set the issue.editable property. To do this, simply add the issue.editable property to the status properties.

JIRA workflow transition changes

  • Post-functions, conditions, and validators cannot be viewed together in one long list. 
  • Workflow transition IDs are no longer displayed in the user interface. (You can still see it when viewing a workflow text mode.)

Configuring a workflow

Creating a workflow from an existing workflow

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose > Issues. Select Workflows to open the Workflows page, which displays all of the workflows in your system.
  3. Copy an existing workflow using the Copy link in the Operations column (shown above).
    1. Enter a name and description for your workflow.
    2. Click the Copy button. The workflow opens in edit mode.
  4. Once you have created your new workflow, you may customize it by adding and/or editing steps and transitions.

When you have finished customizing your workflow, see Activating workflow for details on how to use it with a JIRA project.

Creating a workflow from scratch

(info) For advanced administrators

  1. Follow Steps 1 and 2 as described above (in "Creating a workflow from an existing workflow").
  2. At Step 3, click the Add Workflow button instead of copying an existing workflow.
  3. Enter a name and description for your workflow. Click the Add button.
    The workflow opens in edit mode and contains a step called Open. If you are viewing your workflow in Diagram mode, you see an incoming transition called Create.
  4. Continue with your workflow customizations, by adding and editing steps and transitions.

Importing a workflow

Please see the documentation on Importing from Atlassian Marketplace.

Setting the Resolution field

Within JIRA an issue is determined to be Open or Closed based on the value of its Resolution field — not its Status field.

  • An issue is determined to be Open if its Resolution field has not been set.
  • An issue is determined to be 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:

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.

Editing a project's workflow for the first time

Whenever a new JIRA project is created, your project automatically uses the default workflow scheme, which associates all available issue types in the project with the JIRA system workflow. Since neither the JIRA system workflow nor the default workflow scheme are editable, JIRA creates an editable copy of the system workflow and workflow scheme for your project.

To begin editing your project's workflow for the first time:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose > Projects.
  3. On the Project Administration page, select Workflows.
  4. In the displayed workflow, click the Edit icon at the top-right of the box (shown here):

    A message is displayed letting you know that you are editing your workflow for the first time. Click Continue to proceed.
  5. JIRA automatically does the following:
    • Creates a copy of the system workflow named Your Project Name Workflow.
    • Creates a new workflow scheme for Your Project Name Workflow named Your Project Name Workflow Scheme.
    • Associates any existing issues in your project with the new Your Project Name Workflow.

You can now edit your draft workflow. When you are finished, you are presented with a dialog where you can publish your draft and, optionally, save your original workflow as an inactive backup.

Usage notes:

  • If you have only a small number of existing issues in your JIRA project, this process is relatively quick.
  • 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 cannot be paused or cancelled . Please avoid editing or transitioning any issues within your project while this process is taking place.

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 transitions

For more information on workflow transitions, including built-in JIRA conditions, combining conditions into groups, applying validators and post functions, see Advanced workflow configuration.

Last modified on Sep 16, 2013

Was this helpful?

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