Working with 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 .
A 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.is a link between
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 .
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.
|An inactive workflow is a workflow that is not currently Working in text mode.. Because there are no issues currently transitioning through an inactive workflow, you can edit the workflow's and . For details on this, see|
An active workflow is a workflow that is currently . 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:
You will need to log in as a user with the 'JIRA System Administrators' global permission to access the functionality described below.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.
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.
- 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.editableproperty. To do this, simply add the
issue.editableproperty 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.
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
- Choose > Issues.
- Select Workflows to open the Workflows page, which displays all of the workflows in your system.
- Copy an existing workflow using the Copy link in the Operations column (shown above). Enter a name and description and select the Copy button.
- Customize it by adding or editing steps and transitions.
When you have finished customizing your workflow, see Managing your workflows for details on how to use it with a JIRA project.
Create a new workflow
For advanced administrators
- Click Workflows in the left-hand nav panel, then Add Workflow at the top of the screen.
- Enter a name and description for your workflow. Click Add.
The workflow opens in edit mode, and contains a step called Open and an incoming transition called Create.
- Continue with your workflow customizations, by adding and editing steps and transitions.
Import a workflow
Please see the documentation on Importing workflows.
Configuring a workflow
Editing a project's workflow
Whenever you create a new JIRA project, your project automatically uses the are editable, JIRA creates an editable copy of the system workflow and workflow scheme for your project.associates all available issue types in the project with the JIRA . Since neither the JIRA system workflow nor the default workflow scheme
- Choose > Projects, and select the relevant project.
- On the Administration page for the project, click Workflows.
- Click the 'edit' icon at the top-right of the box, and JIRA automatically does the following:
- Creates a draft copy of the system workflow named 'Your Project Name Workflow (Draft)'.
- Creates a new for the workflow named 'Your Project Name Workflow Scheme'.
- Associates any existing issues in your project with the new workflow.
- You can now edit your draft workflow. Click on a status or transition to see editing options in the panel that appears.
- When you are finished, click Publish. The dialog allows you to publish your draft and, optionally, save your original workflow as an inactive backup.
- 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 cannot be paused or canceled. Please avoid editing or transitioning any issues within your project while this process is taking place.
Setting the resolution field
In JIRA, an issue is either open or closed, 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 Working in text mode for details on this. . See
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:
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.