Documentation for JIRA 5.2. Documentation for other versions of JIRA is available too.

Skip to end of metadata
Go to start of metadata

About workflow

A JIRA workflow is the set of steps (or 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'. This workflow, also known as the 'system workflow' cannot be edited, but you can customise the issue lifecycle by initially copying the system workflow or creating new workflows from scratch. Each workflow can be associated with particular projects and (optionally) particular issue type(s), via a workflow scheme.


JIRA's system workflow

About steps and transitions

JIRA workflows consist of steps and transitions:

  • A step represents a workflow's current status for an issue. An issue can exist in one step only at any point in time. Each workflow step corresponds to a linked status. When an issue is moved into a particular step, its status field is updated to the value of the step's linked status. In the diagram above, the blue boxes represent steps/statuses.
    When defining a step, you can optionally specify properties, one of which allows you to make an issue uneditable while it is in that step.
    (tick) Although steps and statuses are treated separately when administering workflows, they are effectively synonymous concepts in JIRA and as such, it usually helps to name a step after its linked status.
  • A transition is a link between two steps. A transition allows an issue to move from one step to another step. For an issue to be able to progress from one particular step to another, a transition must exist that links those two steps. Note that a transition is a one-way link, so if an issue needs to move back and forth between two steps, two transitions need to be created. In the diagram above, the arrows represent transitions.
    The available workflow transitions for an issue are listed on the issue's 'view issue' page. A user can execute a transition (i.e. move the issue through workflow) by clicking one of the available links, e.g.:

    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 after the transition is complete, e.g.:
      • Assign the issue to a particular user.
      • Send an email notification.
      • Update a field in the issue.

On this page:

See also:

About 'Open' and 'Closed' issues

Within JIRA (e.g. in the Assigned To Me gadget and other gadgets), 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).

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

Creating a workflow

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose Administration at the top right of your screen. Then choose Issues > Workflows to open the 'Workflows' page, which shows a list of all existing workflows in your system.
    (tick) Keyboard shortcut: g + g + start typing workflows

    (info) Some of the features in the screenshot above, such as Import From XML, will not available unless you have logged in as a user with the JIRA System Administrators global permission.
  3. Create a new workflow in JIRA using either of the following methods:
    • Create a 'blank' workflow by first clicking the Add Workflow button and in the resulting Add Workflow dialog box:
      1. Type a Name (usually 2-3 words) to identify your new workflow.
      2. (Optional) Type a detailed Description of your new workflow.
      3. Click the Add button. The workflow will open in edit mode, showing your new workflow containing a step called Open. If you are viewing your workflow in Diagram edit mode, you will see which has an incoming transition called Create.
    • Copy an existing workflow (useful if your new workflow can created by applying modifications to an existing workflow), by clicking the Copy link next to the existing workflow and in the resulting Copy Workflow dialog box:
      1. Type a Workflow Name (usually 2-3 words) to identify your new workflow.
      2. (Optional) Type a detailed Description of your new workflow.
      3. Click the Copy button. The workflow will open in edit mode, showing the layout of your copied workflow.
        (info) To access inactive workflows, click the Inactive list heading to expand the list of inactive workflows.
        (warning) If you are copying the system workflow (above) and wish to rename the workflow transition buttons on the 'view issue' page, you must delete the jira.i18n.title and jira.i18n.description 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 (below).
  4. Once you have created your new workflow (especially if you created a 'blank' workflow) you may want to customise it by adding and/or editing steps and transitions (below).
  5. When you have finished customising your new workflow, see Activating workflow for details on how to use it with a JIRA project.

Editing a workflow

Editing a workflow means that you are modifying the steps and transitions that make up a workflow. Read more about steps and transitions on this page.

There are slight differences between editing an inactive and an active workflow. Restrictions are placed 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 the workflow is applied to.

Editing an 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 simply edit the workflow's steps and transitions (below).

Editing an 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.

  • The 'draft' of your active workflow allows you to make modifications to the workflow with the benefit of real-time validations.
  • Once you have finished modifying your draft workflow, you can publish your draft, during which you have the option of saving 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):

  • Workflow steps cannot be deleted.
  • A step's associated Status cannot be edited.
  • If a step has no outgoing transitions, it cannot have any new outgoing transitions added.
  • A step's Step ID cannot be changed.

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

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. (For more information see What is a 'workflow scheme'?)

Since neither the 'jira' system workflow nor the default workflow scheme are editable, JIRA automatically creates an editable copy of the 'jira' system workflow (and accompanying workflow scheme) for your project, all within a few mouse clicks. This saves you the need to manually create both a new workflow (i.e. a copy the 'jira' system workflow) and a workflow scheme for your project, in order to begin modifying your project's workflow.

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 Administration at the top right of your screen. Then choose Projects from the menu bar and select the name of the project of interest. Otherwise, choose your project from the Projects list or Project Categories.
    (tick) Keyboard shortcut: g + g + start typing projects
  3. Do either of the following:
    • On the left of the Project Summary page, click the pencil icon in the Workflows section:
    • On the the project's Workflow page (accessed via the Workflow tab on the left), click the pencil icon at the top-right of the box displaying the jira system workflow:
    The following Edit Workflow message is displayed:
  4. Click Continue to proceed and JIRA will automatically do the following:
    • Create a copy the 'jira' system workflow named 'Your Project Name Workflow', where Your Project Name is the name of your project.
    • Create a new workflow scheme for 'Your Project Name Workflow' named 'Your Project Name Workflow Scheme'.
    • Associate any existing issues in your project with the new 'Your Project Name Workflow'.
    (info) Please Note:
    • If you have no (or only a small number of) existing issues in your JIRA project, this process will finish relatively quickly.
    • If you have many (e.g. thousands of) existing issues in your JIRA project, this process may take some time to complete while JIRA associates these issues with 'Your Project Name Workflow'. The following message is shown during this process:

      (warning) Be aware that 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.
    Once this process finishes, 'Your Project Name Workflow' appears in edit mode:

    (info) Since this workflow is being used by your project, you will be editing an active workflow and hence, working with a draft of the workflow in edit mode. If you are editing an active workflow for the first time, the Don't forget to Publish popup appears beneath the Publish Draft button (as shown in the screenshot above).

Editing any JIRA workflow directly

To directly edit any of JIRA's workflows:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose Administration at the top right of your screen. Then choose Issues > Workflows to open the 'Workflows' page, which shows a list of all existing workflows in your system.
    (tick) Keyboard shortcut: g + g + start typing workflows
  3. Click the Edit link (under Operations) associated with the workflow you want to edit, which opens the workflow in edit mode.
    (info) If the workflow you are editing is active, the word Draft will appear on your workflow in edit mode, along with the additional buttons, Publish Draft and Discard Draft.
    There are two types of edit mode, Diagram and Text. JIRA remembers the last type of edit mode you used and presents you with that edit mode upon editing your next workflow. Otherwise, JIRA assumes Diagram edit mode.
    (info) It is not possible to edit the system workflow (above). You can only create a copy of the system workflow. (See Creating a workflow above).
  4. Add and/or edit your workflow's steps and transitions (below) as required.
  5. If you are editing:
    • An inactive workflow, you do not need to proceed any further. However, you may wish to associate your edited workflow with a project, which in turn activates the workflow. (See Activating Workflow for more information.)
    • An active workflow:
      1. click Publish Draft at the top right of workflow page in edit mode. A confirmation dialog box will be displayed:
      2. Select whether or not you wish to save the original workflow as an inactive backup copy. If you choose Yes, enter a name for the inactive copy.
      3. Click Publish to publish your draft (i.e. commit your changes to the active workflow).

(info) Please Note: After creating a draft of an active workflow, you will be able to edit the draft workflow as described in the sections below. Any changes that you make to the draft will not affect the active workflow until you publish the draft.

Using 'Diagram' edit mode

Diagram edit mode allows you to visualise the entire layout of your workflow as well as create and edit a workflow's steps and transitions visually.

The Diagram edit mode interface consists of the four areas indicated in the following diagram.

(info) Please Note:

  • The Statuses and Global Transitions panels are expandable. If these panels are not visible (i.e. collapsed), you can expand these panels by clicking the vertical bar (containing a small arrow mid-way along the bar) on the left-hand edge of the workflow design area.
  • Keyboard shortcuts are not available in Diagram edit mode.

Using the main toolbar

The main toolbar contains tools (on buttons) for visually arranging your workflow's steps/statuses and transitions on the workflow design area.

Button

Description

Select Tool
Selects, moves or edits any item on the workflow design area. Selected items are highlighted in red. Click away from any item in the workflow design area to clear the selection.

Create Transition — Straight Line
Creates a transition with a single straight line. See Adding a transition (below) for details.

Create Transition — Polygonal Line
Creates a transition with multiple straight lines. See Adding a transition (below) for details.

Create Transition — Bezier Line
Creates a transition with a curved line. See Adding a transition (below) for details.

Create Annotation
Adds a 'sticky note' to the workflow design area into which you can write a short description or annotation to add to your workflow's layout.
(info) Annotations only appear in the workflow design area and are not visible when viewing workflows from the 'view issue' page (via the View Workflow link).

Zoom In

Zoom Out

Save Snapshot Image
Saves an image of the current position of all items on the workflow design area in PNG format.

Toggle Transition Labels
Switches between hiding or revealing transition labels, each of which indicate their Transition (id).
(info) To be able to edit all aspects of a transition (including its conditions, validators, post functions and properties), transition labels must be visible. If transition labels are hidden, you can only edit the Transition Name, Description, Destination Step and Transition View of a transition by double-clicking its transition line. See the Add Workflow Transition page (below) for details.

Using the 'Statuses' panel

The Statuses panel lists all available JIRA statuses which have not already been associated with a step on the workflow design area. It also provides tools (on buttons) for adding new statuses or editing existing ones.

Button

Description

Refresh List
Refreshes the statuses list.

Add New Status
Adds a new global status to JIRA. See Defining 'Status' field values for details.

Status Editor
Opens the Status Editor dialog box which allows you to edit an existing global status in JIRA. This dialog box is functionality very similar in to the View Statuses page. See Defining 'Status' field values for details.

(tick) You can use the Statuses panel to add a step to your workflow. See Adding a step (below) for details.

Using the 'Global Transitions' panel

The Global Transitions panel lists all global transitions used in your workflow. A global transition is one in which the destination step of the transition has all other steps in the workflow as incoming steps, but provides the added advantage of only requiring you to edit or update this transition in one place.

(info) Please Note:

  • Global transitions are similar to (but not the same as) 'common transitions'. See Working with 'common transitions' (below) for details.
  • To avoid clutter, any global transitions added to your workflow do not appear on the workflow design area. However, they do appear in the Global Transitions panel as well as every step of your workflow in Text edit mode (below).

The Global Transitions panel also provides tools (on buttons) for adding new global transitions, as well as editing or deleting existing ones.

Button

Description

Add New Transition
Adds a new global transition to the workflow. See Adding a transition (below) for details.

Edit Selected Transition
Edits the currently selected global transition in the global transitions panel. See Editing a transition (below) for details.

Delete Selected Transition
Deletes the currently selected global transition in the global transitions panel, from the workflow.

Using the workflow design area

The workflow design area shows the layout of your workflow's steps as well as transitions, consisting of transition lines and labels.

Use the Select Tool (above) to move these items around workflow design area.

(warning) Please Note:

  • A workflow depicted in the workflow design area is what regular JIRA users will see when viewing the workflow from the 'view issue' page (via the View Workflow link).
  • Any changes that you make to items in the workflow design area (including their layout) is automatically saved whenever you leave Diagram edit mode for your workflow.

Editing or deleting annotations

Once you have added an annotation using the Create Annotation tool (above), you can do the following to edit or delete the annotation:

  • To resize an annotation, drag the edges or corners of the 'sticky note'.
  • To edit the text inside an annotation, simply click inside the annotation and begin modifying the text.
  • To remove an annotation, click the X at the top-right of the 'sticky note'. You will be prompted to confirm this action.

Working with steps

Adding a step

To add a new step to a workflow:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose Administration at the top right of your screen. Then choose Issues > Workflows to open the 'Workflows' page, which shows a list of all existing workflows in your system.
    (tick) Keyboard shortcut: g + g + start typing workflows
  3. Click the Edit link next to the workflow that you wish to add a step to.
  4. Use either Diagram or Text edit mode pages to add the new step to the workflow.

Using 'Diagram' edit mode to add the new step

  1. Ensure the Diagram button is selected, so that your workflow appears in Diagram edit mode. Your workflow's existing steps as well as the lines and labels of transitions between these steps are shown in the workflow design area.
  2. Drag an available status from the Statuses panel list and drop it onto the workflow design area. A new step will be added to your workflow.

    (info) Please Note:
    • The name of the status, which is equivalent to the Linked Status indicated in Text edit mode (below) is assigned to the step's Step Name (id). This step name is depicted on step you dragged from the Statuses panel to the workflow design area.
    • Because steps on the workflow design area depict step names, if you use the Statuses panel (in Diagram edit mode above) to change the name of a status that has already been added to the workflow design area, the step name will remain unchanged in this area. To change the name of a step, see Editing a step (below).

Using 'Text' edit mode to add the new step

  1. Ensure the Text button is selected, so that your workflow appears in Text edit mode. A list of existing steps making up the workflow and each step's Linked Status and Outgoing Transitions (under Transitions (id)) is shown.
    (info) Please Note:
  2. In the Step Name field, type a short name for the step.
    (tick) It is often useful to use the name of the corresponding linked status (in the following step).
  3. In the Linked Status field, select the status that corresponds to this step.
    (info) Each status can only correspond to one step in each workflow. Hence, if all statuses are linked to steps in this workflow, you may need to define a new status.
  4. Click the Add button. Your new step will appear in your workflow's list of steps in Text edit mode.

(info) Be aware that some gadgets (such as Assigned To Me and In Progress) will not display data for issues in and after the Resolved step.

Editing a step

To edit an existing step in a workflow:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose Administration at the top right of your screen. Then choose Issues > Workflows to open the 'Workflows' page, which shows a list of all existing workflows in your system.
    (tick) Keyboard shortcut: g + g + start typing workflows
  3. Click the Edit link next to the workflow whose step you wish to edit.
  4. Ensure the Text button is selected, so that your workflow appears in Text edit mode. A list of existing steps that make up the workflow and each step's Linked Status and Outgoing Transitions (under Transitions (id)), is shown (as indicated in Adding a step above).
    • In 'Text' edit mode, you can click the following link of any step:
      • Add Transition — to add an Outgoing Transition to that step. See the Add Workflow Transition page (below) for details.
      • Delete Transitions — to delete one or more Outgoing Transitions of that step. (info) This link is only available if the step has at least one outgoing transition.
      • Edit — to edit the step's Step Name or Linked Status.
      • View Properties — to view and edit the step's Properties. See Using step properties (below) for details.
      • Delete Step — to do just that. (info) This link is only available if the step has no Incoming Transitions.
    • Alternatively, you can access a step's View Workflow Step page to edit the step.
      To access this page, click the name of the step you wish to edit in the Step Name (id) column (e.g. Open). The step's View Workflow Step page is displayed.

      • On the View Workflow Step page, the following information is shown about the step:
        • On the left of the View Workflow Step page:
          • Linked Status — the status (used globally throughout JIRA) to which your specific workflow step is linked.
        • In the Workflow Browser section on the right:
          • Incoming Transitions — transitions whose Destination Step is the step you are currently viewing. To allow issues to move into this step, there must be at least one incoming transition.
          • Outgoing Transitions — transitions whose Originating Step is the step you are currently viewing. To allow issues to move out of this step, there must be at least one outgoing transition.
      • On the View Workflow Step page, you can:
        • Click 'Add outgoing transition' to do just that to the step, as shown under Adding a transition below.
        • Click 'Delete outgoing transitions' to delete one or more Outgoing Transitions of the step. (info) This option is only available if the step has at least one outgoing transition indicated in the Workflow Browser section.
        • Click 'Edit step' to edit the step's Step Name or Linked Status.
        • Click 'Delete Step' to do just that. (info) This option is only available if the step has no incoming transitions indicated in the Workflow Browser section. See Deleting a step (below) for details.
        • Click 'View step's properties' to view and edit the step's Properties. See Using step properties (below) for details.
        • View and edit any of the step's Incoming Transitions or Outgoing Transitions, by clicking the name of a transition in the Workflow Browser section. See Adding a transition, Adding a validator and Adding a post function (below) for details.

Using step properties

You can use a workflow step's properties to prevent issues from being edited when they are at that particular workflow step. For example, in a copied system workflow (above), issues in the Closed step/status cannot be edited, even by users who have the Edit Issue project permission.

(info) Please Note:

  • Issues which cannot be edited cannot be updated using Bulk edit either.
  • You can only edit the properties of a workflow's step if that workflow is editable (i.e. if that workflow is either inactive or a draft of an active workflow). See Editing an inactive workflow for more information.

To stop issues from being editable in a particular workflow step (by setting the step's jira.issue.editable property to false) or to set any property of a step:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose Administration at the top right of your screen. Then choose Issues > Workflows to open the 'Workflows' page, which shows a list of all existing workflows in your system.
    (tick) Keyboard shortcut: g + g + start typing workflows
  3. Click the Edit link next to the workflow whose:
    • step you wish to make uneditable or
    • step's property you wish to set.
  4. Use either Diagram or Text edit mode to set the workflow step's property.

Using 'Diagram' edit mode to set the step's property

  1. Move the mouse pointer over the relevant step and click the cog icon that appears to the right of the step to reveal a popup menu.
  2. From the popup menu, select Issue Editable to remove the tick from that menu item. This action sets the step's jira.issue.editable property and its value to false.
    (info) Please Note:
    • Selecting Issue Editable from the popup menu again (to add the tick) sets the value of the jira.issue.editable property key to true. Conversely, deleting the step's jira.issue.editable property in Text edit mode (below) adds the tick back to the Issue Editable popup menu.
    • Selecting Step Properties from the popup menu opens the Edit Properties dialog box, which allows you to specify additional properties (other than the jira.issue.editable property) on a step.

      On the Edit Properties dialog box, you can:
      • Add a new property to the step.
      • Edit a property's key or value, by simply clicking the property's key or value to begin editing it.
      • Delete a property, by clicking the (minus) icon to the right of the property and its value.

Using 'Text' edit mode to set the step's property

  1. Ensure the Text button is selected, so that your workflow appears in Text edit mode. A list of existing steps making up the workflow is shown (as indicated in Adding a step above).
  2. Click the View Properties link that corresponds to the relevant step. The View Workflow Step Properties page is displayed, showing the step's existing properties (if any). The Add New Property form appears below the list of existing properties (if any have already been defined).
    (info) The Add New Property form will not appear if the step's workflow is not editable.
  3. In the Property Key field, type: jira.issue.editable (or any other Property Key you wish to add).
  4. In the Property Value field, type: false (or any other Property Value you wish to add).
  5. Click the Add button.

(info) Please Note:

  • It is not possible to edit a step's properties on this page. To change any property's key or value (or both), you must first delete the property you wish to change and add the new updated property.
  • It is possible to implement restrictions on steps using step properties. For more information, see Workflow Properties.

Deleting a step

(info) Please Note: A step can only be deleted if it has no incoming transitions.

To delete a step from a workflow:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose Administration at the top right of your screen. Then choose Issues > Workflows to open the 'Workflows' page, which shows a list of all existing workflows in your system.
    (tick) Keyboard shortcut: g + g + start typing workflows
  3. Click the Edit link next to the workflow whose step you wish to delete.
  4. Use either Diagram or Text edit mode to delete the step from the workflow.

Using 'Diagram' edit mode to delete the step

  1. Ensure the Diagram button is selected, so that your workflow appears in Diagram edit mode. Your workflow's existing steps are shown in the workflow design area (as indicated in Using 'Diagram' edit mode above).
  2. Move the mouse pointer over the relevant step and click the cog icon that appears to the right of the step to reveal a popup menu.
  3. From the popup menu, select Delete Step to remove the step from the workflow.
    (warning) Please note that any incoming transitions to the step you delete will also be deleted.

Using 'Text' edit mode to delete the step

  1. Ensure the Text button is selected, so that your workflow appears in Text edit mode. A list of existing steps making up the workflow is shown (as indicated in Adding a step above).
  2. Click the Delete Step link that corresponds to the relevant step.
    (info) This link will only be shown if the step has no incoming transitions (unlike the equivalent Delete Step function in Diagram edit mode (above), which when used on a step with incoming transitions, will also remove these incoming transitions).

Working with transitions

Adding a transition

To add a transition to a workflow:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose Administration at the top right of your screen. Then choose Issues > Workflows to open the 'Workflows' page, which shows a list of all existing workflows in your system.
    (tick) Keyboard shortcut: g + g + start typing workflows
  3. Click the Edit link next to the workflow you wish to add a transition to.
  4. Use either the Diagram or Text edit mode to add the transition to the workflow.
    (tick) Diagram edit mode provides more options for creating your new transition, such as the ability to use 'common transitions'.

Using 'Diagram' edit mode to add the transition

  1. Ensure the Diagram button is selected, so that your workflow appears in Diagram edit mode. Your workflow's existing steps as well as the lines and labels of transitions between these steps are shown in the workflow design area (as indicated in Using 'Diagram' edit mode above).
  2. Click the appropriate Create Transition button in the main toolbar (above), according to the type of transition line you wish to create.
  3. In the workflow design area, click the step that will be the Originating Step of the transition.
  4. Click the step that will be the Destination Step of the transition.
    (info) If you selected either the Create Transition — Polygonal Line or Bezier Line buttons, you can click other areas of the workflow design area first (before clicking the Destination Step) to control the appearance of your transition line.
    Once you have clicked the Destination Step, the Add Transition dialog box opens.
  5. Choose between creating a new transition (New Transition), copying an existing transition (Clone Transition) or using a 'common transition' (Use Common Transition).
    • If you choose either New Transition or Clone Transition:
      1. In the Transition Name field, type a short name for the transition.
        (info) This name will be shown to users on the relevant transition button, within the 'operations bar' of the 'view issue' page.
      2. (Optional) In the Description field, type a short description of the purpose of the transition.
      3. If you chose:
        • New Transition, then 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).
          • The name of a screen 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 want to create a new screen.
            (info) Many of JIRA's default screens are used in a copied system workflow (above) and named after the transitions they are used in (e.g. Start Progress and Resolve Issue).
        • Clone Transition, then in the Transition To Clone field, select the transition you wish to copy.
          (info) Copying an existing transition creates a new independent copy of a transition, which does not result in a 'common transition'.
    • If you choose Use Common Transition, select an existing transition (currently used in your workflow which also leads to your Destination Step) from the Transition To Reuse dropdown list. See Working with 'common transitions' (below) for details.
      (info) Please Note:
      • Existing transitions in your workflow which do not lead to your Destination Step will not be available from the Transition To Reuse dropdown list.
      • You can select either an existing 'common transition' or an ordinary transition (i.e. a transition that has only been used once on the workflow). If you select an ordinary transition, it will be converted to a 'common transition'.
  6. Click the OK button to complete the addition of your transition.

Using 'Text' edit mode to add the transition

  1. Ensure the Text button is selected, so that your workflow appears in Text edit mode. A list of existing steps that make up the workflow and each step's Linked Status and Outgoing Transitions (under Transitions (id)), is shown.
  2. Identify the step from which your new transition will originate and click the Add Transition link next to the step. The Add Workflow Transition page is displayed.
  3. In the Transition Name field, type a short name for the transition.
    (info) This name will be shown to users on the relevant transition button, within the 'operations bar' of the 'view issue' page.
  4. (Optional) In the Description field, type a short description of the purpose of the transition.
  5. In the Destination Step field, choose the step to which issues will move when this transition is executed.
  6. 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).
    • The name of a screen 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.
      (info) Some of JIRA's default screens are used in JIRA's system workflow (above) and reflect the transitions they are used in (e.g. Resolve Issue Screen).

Editing or deleting a transition

To edit or delete an existing transition of a workflow:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose Administration at the top right of your screen. Then choose Issues > Workflows to open the 'Workflows' page, which shows a list of all existing workflows in your system.
    (tick) Keyboard shortcut: g + g + start typing workflows
  3. Click the Edit link next to the workflow whose transition you wish to edit or delete.
  4. Use either Diagram or Text edit mode to edit or delete the transition of the workflow.

Using 'Diagram' edit mode to edit or delete the transition

  1. Ensure the Diagram button is selected, so that your workflow appears in Diagram edit mode. Your workflow's existing steps as well as the lines and labels of transitions between these steps are shown in the workflow design area (as indicated in Using 'Diagram' edit mode above).
  2. Move the mouse pointer over the relevant transition label and click the cog icon that appears to the right of the label to reveal a popup menu.
  3. From the popup menu, you can:
    • Select Edit Transition to edit the Transition Name, Description, Destination Step and Transition View of the transition. See the Add Workflow Transition page (above) for details.
    • Select Delete Transition to do just that.
    • Select Transition Properties to edit the transition's Properties. See Working with transition properties (below) for details.

Using 'Text' edit mode to edit or delete the transition

  1. Ensure the Text button is selected, so that your workflow appears in Text edit mode. A list of existing steps that make up the workflow and each step's Linked Status and Outgoing Transitions (under Transitions (id)), is shown (as indicated in Adding a transition above).
  2. In the Transitions (id) column, click the link of the Outgoing Transition of the step you wish to edit. The Transition page is displayed.

    On the Transition page, the following information is shown about the transition:
    • On the left of the Transition page:
      • Transition View — the screen (usable globally) that your specific workflow transition uses. If your workflow transition does not require a view (i.e. no screen has been specified), then None - it will happen instantly is shown.
    • In the Workflow Browser section:
      • Originating Steps — steps whose Outgoing Transition is the transition you are currently viewing.
        (info) If the transition has more than one originating step, then it is either a global or common transition.
      • Destination Step — the step whose Incoming Transition is the transition you are currently viewing.
  3. On the Transition page, you can:
    • Click 'Edit this transition' to edit the Transition Name, Description, Destination Step and Transition View of the transition. See the Add Workflow Transition page (above) for details.
    • Click 'Delete this transition' to do just that. (info) This link is only available if the step has at least one outgoing transition indicated in the Workflow Browser section.
    • Click 'View properties of this transition' and edit the transition's Properties. See Working with transition properties (below) for details.

Using a screen with a transition

When a user clicks a particular transition, a screen can be used to gather input from the user before the transition is executed.

Example: using a screen to set the 'Resolution' field

For a particular step in a workflow, you might need to create a transition that will move the issue to a 'closed' status (e.g. Closed, Resolved, etc) - see 'open' and 'closed' issues. As part of this transition, you might need the user to set the Resolution field. To do this:

  1. (Optional) Create a screen (e.g. named Resolution Screen), that contains the Resolution field (and any other fields you want to show). See Defining a screen for details.
    (tick) JIRA already includes a screen named Resolve Issue Screen, which contains the Resolution, Fix Version/s, Assignee and Log Work fields.
  2. Create or edit your transition and then choose the screen that contains the Resolution field (e.g. Resolution Screen) in the Transition View field:

Applying conditions to transitions

Conditions control who can perform a transition and the circumstances under which they can perform the transition (such as their project permissions, the status of any sub-tasks, or the state of source code associated with issues).

If any part of a transition's condition fails, the user will not see the transition link on the 'view issue' page.

JIRA's built-in conditions

JIRA includes the following individual conditions, which can be added immediately to any transition:

Condition

Description

Additional Parameters Required

Only Assignee Condition

Only allow the issue's current assignee to execute the transition.

None

Only Reporter Condition

Only allow the issue's reporter to execute the transition.

None

Permission Condition

Only allow users with a given permission to execute the transition.

A project-wide permission

Sub-Task Blocking Condition

Only allow a parent issue's transition to execute if all its sub-tasks have at least one of a specified set of statuses.

One or more statuses

User Is In Group

Only allow users in a given group to execute the transition.

A group

User Is In Group Custom Field

Only allow users in a given group-type custom field to execute a transition.

A custom field of type "Group"

User Is In Project Role

Only allow users in a given project role to execute a transition.

A project role

Code Committed Condition

Only allow the transition to execute if code either has or has not been committed against the issue.

Specify whether or not code must be committed

No Open Reviews Condition

Only allow the transition to execute if no related Crucible reviews are still open against the issue.

None

Unreviewed Code Condition

Only allow the transition to execute if no unreviewed changesets related to the issue exist.

None

(info) You can also create your own conditions via the plugin system. See the Workflow Plugin Modules for details.

Adding a condition

To add a condition to a transition:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose Administration at the top right of your screen. Then choose Issues > Workflows to open the 'Workflows' page, which shows a list of all existing workflows in your system.
    (tick) Keyboard shortcut: g + g + start typing workflows
  3. Click the Edit link next to the workflow whose transition you wish to add a condition to.
  4. Use either Diagram or Text edit mode to add the condition to the transition.
    • Using 'Diagram' edit mode to add the condition to the transition:
      1. Ensure the Diagram button is selected, so that your workflow appears in Diagram edit mode. Your workflow's existing steps as well as the lines and labels of transitions between these steps are shown in the workflow design area (as indicated in Using 'Diagram' edit mode above).
      2. Move the mouse pointer over the relevant transition label and click the cog icon that appears to the right of the label to reveal a popup menu.
      3. From the popup menu, select View Conditions to view a list of the transition's existing conditions. The Edit Transition dialog box's Conditions tab and a list of the transition's existing conditions is displayed.
    • Using 'Text' edit mode to add the condition to the transition:
      1. Ensure the Text button is selected, so that your workflow appears in Text edit mode. A list of existing steps that make up the workflow and each step's Linked Status and Outgoing Transitions (under Transitions (id)), is shown (as indicated in Adding a transition above).
      2. In the Transitions (id) column, click the name of the relevant transition. The Transition page is displayed.
      3. Click the Conditions tab (if not already selected) and a list of the transition's existing conditions is displayed.
  5. Click the Add link (in the Conditions tab). A list of all available conditions is displayed. See above for a list of JIRA's built-in conditions.
  6. Select a condition from the list and click the Add button.
    (info) If the condition requires additional parameters (e.g. the name of a group or project role), the Add Parameters To Condition  dialog box/page will be presented.
    • Specify your criteria on the Add Parameters To Condition dialog box/page and click the Add button. (Some criteria may require more than one step.)
  7. The Conditions tab is displayed again, showing your new condition at the bottom of the list of conditions.
    (info)From here, you can:
    • Click the Edit link next to the condition's name to edit its additional parameters (if applicable to the condition).
    • Click the Delete link next to the condition's name to remove the condition.
    • Combine your conditions into AND/OR groups. See Combining conditions into groups (below).

Combining conditions into groups

You can construct complex conditions by combining two or more 'individual conditions' (added using the procedure above) using AND or OR boolean logic to form a 'grouped condition'. For example, the following simple grouped condition could be constructed:

  • Only the assignee of this issue can execute this transition
    AND
  • Only users in group jira-users can execute this transition

This grouped condition will only be true (and hence, allow execution of the transition) if the user is the assignee of the issue AND the same user is in the jira-users group.

An overall 'complex condition' can be constructed for your transition by combining multiple grouped conditions using AND or OR boolean logic or even nesting grouped conditions. A transition with a complex condition (as such), can only be executed if all individual and grouped conditions that constitute the complex condition, have been satisfied, e.g:

Converting an individual condition into a grouped condition

To convert an individual condition into a grouped condition:

  1. Follow the Adding a condition procedure (above) to step 3.
  2. Instead of clicking the Add link at step 4, click the Add grouped condition link of the individual condition you wish to convert into a grouped condition.
  3. Continue on from step 5.
    (tick) Please Note:
    • You can use this procedure to create grouped conditions out of individual conditions which are already part of another grouped condition. This allows you to nest grouped conditions.
    • If you only have a single individual condition on the 'Conditions' tab, the 'Add grouped condition' link will not be available on that condition. Hence, just click the Add button instead to create your grouped condition.

(warning) Please also note: It is not possible to add an individual condition that is separate from the outermost grouped condition. Clicking the Add button only adds an individual condition to the outermost grouped condition. Bear this in mind when creating a complex condition and refer to JRA-25179 for more information.

Adding individual conditions to a grouped condition

To add an individual condition to a grouped condition:

  1. Follow the Adding a condition procedure (above) to step 3.
  2. Instead of clicking Add link at step 4, click the Add condition to group link associated with the grouped condition you want to add your individual condition to.
  3. Continue on from step 5.
Switching a grouped condition's logic

The logic of all individual conditions within a grouped condition can be switched between AND and OR. To do this, simply click the Switch to OR or Switch to AND link associated with the grouped condition whose logic you wish to switch.

(info) If you need to switch the logic of only some (not all) individual conditions within a grouped condition, create a nested grouped condition as described above.

Applying validators to transitions

Validators check that any input available to the transition (such as user-supplied input) is valid before the transition is performed. For example, a validator can be used to ensure that the comment entered by a user on a transition's screen meets a certain project permission criterion.

If a transition's validator 'fails', the transition's post functions will not be executed and the issue will not progress to the destination step of the transition.

JIRA ships with a couple of default validators that validate whether or not the user who performed the transition had a particular project permission, which can be added immediately to any transition.

(info) You can also create your own validators via the plugin system. See the Workflow Plugin Modules for details.

(info) How do validators differ from conditions?

  • Conditions are used to determine whether an issue's transition can be executed by a particular user, including a range of other circumstances such as the user's project permissions and the current state of the issue. However, conditions cannot validate input parameters provided by the user on the transition's screen, since if a condition fails, the user is prevented from executing the transition and cannot access the transition's screen.
  • Validators have access to any input available to the transition (such as input gathered from the user on a transition's screen) and thus, can validate this input.

Adding a validator

To add a validator to a transition:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose Administration at the top right of your screen. Then choose Issues > Workflows to open the 'Workflows' page, which shows a list of all existing workflows in your system.
    (tick) Keyboard shortcut: g + g + start typing workflows
  3. Click the Edit link next to the workflow whose transition you wish to add a condition to.
  4. Use either Digram or Text edit mode to add the validator to the transition.
    • Using 'Diagram' edit mode to add the validator to the transition:
      1. Ensure the Diagram button is selected, so that your workflow appears in Diagram edit mode. Your workflow's existing steps as well as the lines and labels of transitions between these steps are shown in the workflow design area (as indicated in Using 'Diagram' edit mode above).
      2. Move the mouse pointer over the relevant transition label and click the cog icon that appears to the right of the label to reveal a popup menu.
      3. From the popup menu, select View Validators to view a list of the transition's existing validators.
    • Using 'Text' edit mode to add the validator to the transition:
      1. Ensure the Text button is selected, so that your workflow appears in Text edit mode. A list of existing steps that make up the workflow and each step's Linked Status and Outgoing Transitions (under Transitions (id)), is shown (as indicated in Adding a transition above).
      2. In the Transitions (id) column, click the name of the relevant transition. The Transition page is displayed.
      3. Click the Validators tab and a list of the transition's existing validators is displayed.
  5. Click the Add link (in the Validators tab). A list of all available validators is displayed.
  6. Select a validator from the list and click the Add button.
    (info) If the validator requires additional parameters (e.g. the name of a group or project role), the Add Parameters To Validator  dialog box/page will be presented.
    • Specify your criteria on the Add Parameters To Validator dialog box/page and click the Add button.
  7. The Validators tab is displayed again, showing your new validator at the bottom of the list of validators.
    (info)From here, you can:
    • Click the Edit link next to the validator's name to edit its additional parameters (if applicable to the validator).
    • Click the Delete link next to the validator's name to remove the validator.

(info) Please Note:

  • The logical relationship between multiple validators applied to a transition is AND only.
  • Unlike Conditions, it is not possible to create 'grouped validators' or to change the logical relationship between multiple validators.

Applying post functions to transitions

Post functions carry out any additional processing required immediately after a transition is executed, such as updating an issue's fields, generating change history for an issue, adding a comment to an issue, or generating an event such as an email notification. There are two categories of post functions in JIRA — essential and optional.

Essential post functions

JIRA includes the following 'essential' post functions, which are automatically added to every newly-created transition and performed in this order:

Essential post function

Set issue status to the linked status of the destination workflow step.

Add a comment to an issue if one is entered during a transition.

Update change history for an issue and store the issue in the database.

Re-index an issue to keep indexes in sync with the database.

Fire an event that can be processed by the listeners.

These 'essential' post functions cannot be deleted from a transition or reordered relative to each other, as this could compromise other issue functionality within JIRA. However, you can insert other (optional) post functions around or between them.

Optional post functions

JIRA includes the following optional post functions which can be added to transitions:

Optional post function

Description

Assign to Current User

Assigns the issue to the user who is executing the transition.

Note, this post function will be ignored unless the user has the Assignable User permission. You may want to use a condition to ensure that the logged-in user has this permission before executing the transition.

Assign to Lead Developer

Assigns the issue to the component lead (if one exists) or project lead.

Assign to Reporter

Assigns the issue to the user who created the issue.

Create Perforce Job Function

Creates a Perforce Job (if required) after completing the workflow transition.

Notify HipChat

Sends a notification to one or more HipChat rooms. See Using a post function to send HipChat notifications (below) for more information.

Before you can use this post function, you must first have configured your JIRA installation with HipChat. See Configuring JIRA with HipChat for Workflow Transition Notifications for more information.

Trigger a Webhook

Fires the specified webhook after completing the workflow transition.

When you add this post function, you will be asked to specify a webhook. This webhook must already be defined in JIRA (see Managing Webhooks).

Update Issue Field

Updates one of the issue's fields to a given value. Fields which can be updated include:

  • Assignee
  • Description
  • Environment
  • Priority
  • Resolution
  • Summary
  • Original Estimate
  • Remaining Estimate

(info) Note that this post function cannot update custom fields.

(info) Please Note:

  • Depending on your particular JIRA installation and its installed plugins, other post functions may be available to you.
  • You can also create your own post functions via the plugin system. See the Workflow Plugin Modules for details.

Note that the six optional post functions must be positioned before the Update change history for an issue and store the issue in the database post function (above), with the exception of the Create transition.

The initial transition ('Create' or 'Create Issue')

When creating an issue, it is sometimes useful to be able to perform specific processing tasks (such as setting a particular field's value). You can perform such tasks by adding post functions to the workflow's 'initial transition'.

The 'initial transition' is executed whenever a user creates an issue, which in turn, places the newly-created issue into the workflow's 'initial step'. Every workflow has only one 'initial step', which is the first step in the issue's workflow and is the 'initial step's' first incoming transition. By default:

  • The 'initial transition' is called Create (if you created a 'blank' workflow) or Create Issue (if you copied the system workflow).
  • The 'initial step' is called Open after having created a workflow above.

JIRA includes the following 'essential' post functions which are specific to a workflow's 'initial transition'. These post functions are automatically added to this transition of every newly-created workflow (and performed in this order):

Essential post function ('initial transition' only)

Creates the issue originally.

Fire an event that can be processed by the listeners.

The optional post functions (above) can also be added to a workflow's initial transition, as well as the following optional post functions (which, with the exception of Store Issue, are essential to all other newly-created transitions):

Optional post function ('initial transition' only)

Description

Create Comment

Adds a comment to an issue if one is entered during a transition.

Re-index Issue

Re-indexes an issue to keep JIRA's indexes in sync with the database.

Update Issue Status

Sets the issue's status to the linked status of the destination workflow step.

Store Issue

Stores updates to an issue (no change history is created).

(warning) Please be aware that a bug in JIRA (JRA-25070) currently prevents these optional post functions from being deleted once they have been added.

Optional post functions added to the workflow's Create transition (for example, an Update Issue Field post function to set the Assignee field to a particular user when an issue is created), must be placed before the Creates the issue originally post function.

Special case:

If you need to set the Resolution field when creating an issue, add the Update Issue Field post function after the Creates the issue originally post function and after that, use the Store Issue post function. The Store Issue post function is useful for setting the Resolution field during issue creation.

(warning) However, keep use of the Store Issue post function to a minimum, since this post function:

  • Does not generate change history.
  • Is incapable of persisting fields that have a one-to-many relationship with the issue (e.g. Version or Component).

Adding a post function

To add a post function to a transition:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose Administration at the top right of your screen. Then choose Issues > Workflows to open the 'Workflows' page, which shows a list of all existing workflows in your system.
    (tick) Keyboard shortcut: g + g + start typing workflows
  3. Click the Edit link next to the workflow whose transition you wish to add a post function to.
  4. Use either Diagram or Text edit mode to add the post function to the transition.
    • Using 'Diagram' edit mode to add the post function to the transition:
      1. Ensure the Diagram button is selected, so that your workflow appears in Diagram edit mode. Your workflow's existing steps as well as the lines and labels of transitions between these steps are shown in the workflow design area (as indicated in Using 'Diagram' edit mode above).
      2. Move the mouse pointer over the relevant transition label and click the cog icon that appears to the right of the label to reveal a popup menu.
      3. From the popup menu, select View Post Functions to view a list of the transition's existing post functions.
    • Using 'Text' edit mode to add the post function to the transition:
      1. Ensure the Text button is selected, so that your workflow appears in Text edit mode. A list of existing steps that make up the workflow and each step's Linked Status and Outgoing Transitions (under Transitions (id)), is shown (as indicated in Adding a transition above).
      2. In the Transitions (id) column, click the name of the relevant transition. The Transition page is displayed.
      3. Click the Post Functions tab and a list of the transition's existing post functions is displayed.
    A copied system workflow (above) has the following built-in post functions for the Resolve Issue transition:
  5. Click the Add link (in the Post Functions tab). A list of all available post functions is displayed.
  6. Select a post function from the list and click the Add button.
  7. If the post function requires one or more configuration parameters (e.g. the name of an event), the Add Parameters To Function dialog box/page will be presented. Enter the appropriate information and click the Add button.
  8. The Post Functions tab is displayed again, showing your new post function at the bottom of the list of post functions.
    (info) From here, you can:
    • Click the Edit link next to the post function's name to edit its configuration parameters (if there are any).
    • Click the Move Up link to move the post function higher up in the list (i.e. it will be executed earlier).
    • Click the Move Down link to move the post function lower down in the list (i.e. it will be executed later).
    • Click the Delete link next to the post function's name to remove the post function.

Using a post function to set a field

You can use an Update Issue Field post function to set the value of an issue's field(s) after a particular transition is executed.

Example: Using a post function to set the 'Resolution' field

For a particular step in a workflow, you might need to create a transition that will move the issue to a 'closed' status (e.g. Close, Resolved, etc) - see 'open' and 'closed' issues. As part of this transition, you might want to automatically set the 'Resolution' field. To do this:

  1. Create or edit your transition (above).
    • In the Transition View field on the Add Transition dialog box or the Add/Update Workflow Transition page (above), select either No View For Transition or the screen that does not contain the Resolution field (such as the Add Comment And Assign screen).
  2. Add a new post function of type Update Issue Field (above).
  3. Do the following on the Add Parameters to Function page:
    1. Select Resolution from the Issue Field select list.
    2. Select a suitable resolution from the Field Value select list.
  4. Click the Add button and the transition's list of post functions will be displayed with your added post function highlighted in blue:

(info) To create a transition that clears the Resolution field, follow the same steps above for adding an Update Issue Field post function to your transition. However, on the Add Parameters To Function page, select None from the Field Value select list.
The list of post functions for this transition will include the following statement:

  • The Resolution of the issue will be cleared.

Each time one of these transitions is executed, the Resolution of the issue is automatically set or cleared as specified in these post functions.

Using a post function to send HipChat notifications

You can use a Notify HipChat post function to send a notification to one or more HipChat rooms whenever an issue passes through a transition with this post function. You can also apply a JQL query to filter issues in your Notify Hipchat post function, so that if an issue transitions with this post function but its JQL query does not retrieve that issue, the HipChat notification will not be sent.

(info) Before you can use the Notify HipChat post function, you must first have configured your JIRA installation with HipChat. See Configuring JIRA with HipChat for Workflow Transition Notifications for more information.

To do this:

  1. Create or edit your transition (above).
  2. Add a new post function of type Notify HipChat (above).
  3. Do the following on the Add Parameters to Function page:
    1. Specify an optional JQL query in the field provided if you want to send notifications to issues which not only pass through this transition but are also retrieved by this query.
      (info) Leaving this field empty to send notifications to all issues which pass through this transition.
    2. Select the HipChat Rooms you want to link with your workflow transition.

Using a post function to send email notifications

You can use the Fire an event that can be processed by the listeners post function to fire the Generic Event, which is a built-in JIRA event that can be used to trigger the sending of email notifications after a particular transition is executed.

Alternatively, you could fire a custom event that you have created specifically for this transition.

When a transition is performed, JIRA will:

  • Look up the notification scheme associated with the issue's project and identify the users associated with the fired event;
  • Send an email notification to each user.
    (info) The fired event is also propagated to all registered listeners.
Example: Using a post function to fire the 'Generic Event'

Use the Generic Event to send email notifications.

To do this:

  1. Create or edit your transition (above).
  2. Click the transition's Post Functions tab and edit the Fire an event that can be processed by the listeners post function.
  3. On the Update parameters of the Fire Event Function for this transition page, select Generic Event from the list of events.

Working with transition properties

Properties are key-value pairs that are can be used to further customise transitions. For example, transition properties help to extend a copied system workflow (above) to allow language translations.

To view and edit the properties of a transition:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose Administration at the top right of your screen. Then choose Issues > Workflows to open the 'Workflows' page, which shows a list of all existing workflows in your system.
    (tick) Keyboard shortcut: g + g + start typing workflows
  3. Click the Edit link next to the workflow whose transition's properties you wish to view or edit.
  4. Use either Diagram or Text edit mode to view or edit the properties of a transition.

Using 'Diagram' edit mode to view or edit the properties of a transition

  1. Ensure the Diagram button is selected, so that your workflow appears in Diagram edit mode. Your workflow's existing steps as well as the lines and labels of transitions between these steps are shown in the workflow design area (as indicated in Using 'Diagram' edit mode above).
  2. Move the mouse pointer over the relevant transition label and click the cog icon that appears to the right of the label to reveal a popup menu.
  3. From the popup menu, select Transition Properties, which opens the Edit Properties dialog box that allows you to view a list of the transition's existing properties and edit them.

    On the Edit Properties  dialog box, you can:
    • Add a new property to the transition.
    • Edit a property's key or value, by simply clicking the property's key or value to begin editing it.
    • Delete a property, by clicking the icon to the right of the property.

Using 'Text' edit mode to view or edit the properties of a transition

  1. Ensure the Text button is selected, so that your workflow appears in Text edit mode. A list of existing steps that make up the workflow and each step's Linked Status and Outgoing Transitions (under Transitions (id)), is shown (as indicated in Adding a transition above).
  2. In the Transitions (id) column, click the name of the relevant transition. The Transition page is displayed.
  3. Click the 'View properties of this transition' link. The View Workflow Transition Properties page is displayed listing the properties currently set up for the transition. You can this page to add and delete properties for this transition.
    (info) It is not possible to edit a transition's properties on this page. To change any property's key or value (or both), you must first delete the property you wish to change and add the new updated property.

(info) It is possible to implement restrictions on transitions using transition properties. For more information, see Workflow Properties.

Customising workflow transitions on the 'view issue' page

When viewing an issue, most of the operations and workflow transitions accessible to a user are available from a row of buttons towards the top of the issue, known as the 'Operations Bar'. As shown in the following screenshot, workflow transitions appear in the right-most set of buttons of the operations bar.


Screenshot: Workflow transitions on the 'view issue' page

By default, the first two transitions appear as separate buttons in the set of transition buttons. Any additional transitions 'spill over' into the Workflow button dropdown menu. The order in which these buttons appear on the view issue page is based on the order of the system workflow (above), or for custom workflows, the order in which a JIRA administrator has added transitions to the custom workflow.

Hence, in the example above, the workflow transition order is: Start Progress -> Resolve Issue -> Close Issue.

JIRA provides the ability to customise the appearance and order of these transitions on the View Issue page.

Changing the number of transition buttons

To change the number of transition buttons from the default of two (with any remaining transitions spilling over into the 'Workflow' button dropdown menu):

  1. Shutdown JIRA.
  2. Edit the jira-config.properties file in your JIRA Home Directory.
    (info) See Making changes to the jira-config.properties file for more information.
  3. Change the value of 'X' in the ops.bar.group.size.opsbar-transitions = X property of this file to the number of transition buttons required before the Workflow button.
    (info) If this property does not exist in your jira-config.properties file, add it. Otherwise, a default value of 2 is assumed.
  4. Save the updated jira-config.properties file.
  5. Restart JIRA.

Changing the order of transition buttons and 'workflow' menu items

To change the order of transition buttons, including additional transitions in the 'workflow' dropdown menu on the 'view issue' page, you need to add the property key opsbar-sequence to each workflow transition that you wish to re-order. Each opsbar-sequence property key requires a property value that defines the order of the transition action on issue views.

To add an opsbar-sequence property key and value to a workflow transition:

  1. Access the workflow transition's properties, as described in Working with transition properties (above).
  2. In the Add New Property section of the workflow transition's View Workflow Transition Properties page, type opsbar-sequence into the Property Key field.
  3. In the Property Value field, type a positive integer value (starting at '0') that defines the order of the transition action on issue views.
    (tick) For each workflow transition, you may wish to use gaps in your opsbar-sequence property values (for example, 10, 20, 30, etc.) rather than consecutive values. This will allow you to 'insert' new workflow transitions more easily at a later point in time.
  4. Click the Add button.

Working with 'common transitions'

A 'common transition' is a transition that is defined only once in a given workflow but is used more than once in the same workflow. A common transition has more than one originating step leading to a single destination step, but provides the added advantage of only requiring you to edit or update the transition in one place.

(info) Please Note: Global transitions (above) are similar to common transitions and provide the same editing advantages. However, they differ from each other in the following respects:

  • For common transitions, the destination step of the transition has only a subset of the remaining steps in the workflow as incoming steps.
  • For global transitions, the destination step of the transition has all remaining steps in the workflow as incoming steps. Be aware that global transitions can only be deleted in Diagram edit mode (above).

You can turn an ordinary transition into a common transition in 'Diagram' edit mode by following these steps:

  1. (Optional) Create a transition from one (target) step to another (destination) step as described in Adding a transition (above).
  2. Create another transition from a different target step to the same destination step in step 1, but in the Add Transition dialog box, choose the Use Common Transition option.
  3. In the Transition To Reuse dropdown menu, select the transition you created in step 1 above or, if you did not perform step 1, select an existing ordinary transition (which also leads to the same destination step) from this dropdown menu.

(info) You can edit existing common transitions in Text edit mode, but as described in Adding a transition (above), they cannot be created from this page — only in Diagram edit mode.

If you are only able to use Text edit mode to create or edit workflows, you can do either of the following to edit common transitions in a JIRA workflow:

  • Copy the system workflow — the system workflow (above) contains common transitions (e.g. Start Progress, Resolve Issue, Close Issue). Although you cannot edit the system workflow, you can copy it and then edit its steps and transitions (via XML) to suit your requirements.
  • Create your workflow in XML — see Using XML to create a workflow (below).

Using XML to create a workflow

JIRA's workflow editor generates OSWorkflow XML definition files that are stored in JIRA's database. If you need to take advantage of an OSWorkflow-based feature that is not available in JIRA's workflow editor (such as 'common transitions' above), you can define the workflow in XML and then import it into JIRA as described below.

Once the XML workflow has been imported, JIRA's workflow editor should be able to display most OSWorkflow definitions even if it does not support creating or editing them.

For example, conditional results of workflow transitions are displayed in the Other tab on the 'View Workflow Transition' page. (info) The Other tab is only visible if a transition has elements that the editor does not directly support.

Importing an XML workflow into JIRA

To import an XML workflow into JIRA:

  1. Log in as a user with the JIRA System Administrators global permission.
  2. Choose Administration at the top right of your screen. Then choose Issues > Workflows to open the 'Workflows' page, which shows a list of all existing workflows in your system.
    (tick) Keyboard shortcut: g + g + start typing workflows
  3. Click the Import from XML button to open the Import Workflow dialog box.
  4. In the Name field, type a name (usually 2-3 words) to identify your new workflow.
  5. (Optional) In the Description field, type a detailed description of your new workflow.
  6. For the Workflow Definition  option, you can do either of the following:
    • Upload an XML workflow definition file — to do this, choose the Provide a full path to an XML file... option and in the File Path field, type the full path to your XML workflow definition file.
      (warning) This path must be local one, so your XML workflow definition file must be located on your JIRA server.
    • Paste the contents of an XML workflow definition file into JIRA — to do this, choose the Paste the workflow XML definition option, copy the contents of your XML workflow definition file and in the Workflow Definition (XML) field, paste this copied content.
  7. Click the Import button.

Copying a workflow between systems

Sometimes it is useful to create a workflow in a test system and then copy it into a production system. To do this:

  1. In the test system, export the workflow to XML by clicking the XML link next to the workflow in the list shown on the View Workflows page (above) and save the output into a file.
  2. In the production system, import the file via the 'import a workflow from XML' link as described in Using XML to create a workflow (above).

(minus) When importing an XML workflow into JIRA:

  • JIRA's XML workflow definitions contain references to JIRA meta attributes. For example, the id of the linked JIRA status of each workflow step is stored as a 'jira.status.id' meta attribute in the step's definition. Therefore, when manually creating workflows in XML, please ensure that all referenced external entities exist before you import the workflow into JIRA.

(minus) When copying a workflow between systems:

  • Please note that conditions, validators and post functions can have parameters that might be valid in one system and not in another. For example, different systems might contain different sets of values for the 'Resolution' field (since it is possible to define your own values). This would be a problem if the 'Update Issue Field' post function is used to set the 'Resolution' field to a value that exists in one system but not the other.

3 Comments

  1. Anonymous

    Hi

      I create a project and assign different flows to it based on different Issue Types. I want to know how can I use different permission schemes for each flow.        Thank you!

  2. Anonymous

    Where does it say how to add/remove vertices to polygonal transition lines in diagram mode?

  3. Anonymous

    Hello.

    Can you please give me an example of what could ve a validator to a transición?

    Not sure if I understand the use of it.

    Thanks