robotsnoindex

descriptionGet detailed descriptions for the rules you can add to your team-managed project's workflow. This reference helps you streamline your working process and automate repetitive actions.


Are you on the right help page?

The following information only applies to team-managed projects.

To check which type project you need help with, look at the bottom of your project’s left-hand sidebar:

This page describes each of the workflow rules you can add to your team-managed projects and gives an example of why you might want to use one. Learn how to add a rule to your team-managed project's workflow.

Assign an issue to someone

This rule helps ensure that the right people address the right issues at the right time. It takes the manual work out of assigning a team member after a stage in the workflow is complete.  

Jira can change the issue's assignee automatically when you move an issue between columns or change its status:

  1. Use the For transition dropdown to tell Jira the column or status that updates the issue's assignee field.
  2. Nominate the person who you want to assign the issue to in the Assign to dropdown.

You can assign issues to:

  • The reporter, usually the person who created it
  • The current user, or the person updating the issue's status
  • No one, making the issue unassigned
  • A specific person in your project

Example

Multi-discipline teams usually hand off tasks at different stages in their process. For example, a small feature team may have these columns on their board:

To do → In design → In development → In review → Done

You can create rules to assign issues to each discipline across the board:

  • For issues moving to In design, assign to the team's designer. They then provide implementation details, specifications, and requirements.

  • For issues moving to In development, assign to the team's feature lead. They then write the code or delegate to other developers in the team.

  • For issues moving to In review, assign to the team's quality assurance champion. They then provide testing notes or build automated quality tests.

  • For issues moving to Done, unassign the issue.

Restrict to when an issue is a specific value

This rule looks at the value of an issue’s field before allowing someone to use a specific transition. This virtual check can help your team better resolve issues by narrowing down the available paths in your workflow based on the information present on the issue. You can use it to enforce best practices for similar issues without having to create a new issue type and workflow.

To review the value of an issue’s field before allowing someone to use a specific transition:

  1. Use the For transition dropdown to tell Jira Software the transition that checks for the field’s value.

  2. Select the field whose value you want to check in the For this field dropdown.

  3. Optionally, adjust the Review its value as dropdown to change how you want to evaluate the field (see below for details).

  4. Use the Check if it dropdown to select how Jira Software should compare the field’s value (see below for details).

  5. Add the value you want to compare against to the This value field.

  6. Click Add.

Review its value as

This capability is included to support older configurations of Jira and advanced uses of this workflow rule. We don’t recommend changing this option from its default.

Jira Software allows you to evaluate the value entered in a field in a number of different ways. This can be useful when comparing numerals entered as text in a short text field to see if they are equal to an integer, for example.

Depending on the type of field you’re checking, you can evaluate its contents as:

  • a number - any positive or negative number, including decimal values, between -1 trillion and 1 trillion (100000000000000). Keep in mind:

    • The field will not accept a number expressed as a fraction.

    • The field only accepts one separator–the decimal. Other notation (for example, commas to denote places) will break the rule.

    • Jira rounds decimals to the nearest 10th place. For example, 5.555555 will be rounded to 5.6. 

    • You may enter large numbers using scientific notation. For example, the number 5000 can be entered as 5e3.

  • a selection - including the available options configured in the field for dropdown and checkbox fields, or user IDs in people fields.

  • a time stamp - including a date and, for time stamp fields, a time. We provide a calendar and clock to accurately select the date and time, so you don’t need to know specific formatting.

  • text - evaluated as a string, including special and non-Latin characters.

Check if it

The selection you make here tells Jira Software how they should evaluate the contents of the field you’re checking. For example, you can check if the value of a number field is greater than or less than a desired value.

Depending on the type of field you’re checking, you can compare the field’s value with these operators:

  • contains - for evaluating fields as either a selection or text, this operator looks to see if the desired string or selection is present in the field

  • doesn’t contain - for evaluating fields as either a selection or text, this operator looks to see that the desired string or selection is absent from the field

  • doesn’t equal - this operator looks to see if the field being evaluated doesn’t exactly match a specific pattern

  • equals - this operator looks to see if the field being evaluated does exactly match a specific pattern. For text, the evaluation is case sensitive and considers exact formatting.

  • is after - for date and time stamp fields, this operator looks for time stamps that occur after the desired value chronologically

  • is before - for date and time stamp fields, this operator looks for time stamps that occur before the desired value chronologically

  • is or is after - for date and time stamp fields, this operator looks for time stamps that occur at exactly the same time or after the desired value chronologically

  • is or is before - for date and time stamp fields, this operator looks for time stamps that occur at exactly the same time or before the desired value chronologically

  • is greater than - for number fields, this operator looks for values that are larger than what’s specified in the rule

  • is greater than or equal to - for number fields, this operator looks for values that are either exactly equal to or larger than what’s specified in the rule

  • is less than - for number fields, this operator looks for values that are smaller than what’s specified in the rule

  • is less than or equal to - for number fields, this operator looks for values that are either exactly equal to or smaller than what’s specified in the rule

Restrict to when an issue has been through a status

This rule helps ensure that issues go through one or more required stages in your team’s workflow. It lets you enforce automated checks in your workflow, and prevents issues from skipping steps in your process. Or, the rule can be set up to do the exact opposite – check that an issue hasn’t been through a particular status.

To check if an issue has been in a status before allowing a specific transition:

  1. Use the For transition dropdown to tell Jira Software the transition that check previous statuses.

  2. Select the status you want to check for in the Check that the issue has been through dropdown.

You can also select the following options:

Include the issue’s current status

By default, this workflow rule only looks at prior statuses when evaluating whether to allow a transition. If you want to also evaluate the current status, select the Include the issue’s current status checkbox. This can help prevent looping transitions, where a transition resets the status and it appears unchanged. It keep issues moving down your workflow. Read more about looped transitions below.

Reverse this rule

You can change the behavior of this workflow rule to check that an issue hasn’t been through a particular status before allowing the transition. This can enforce that bugs or feature requests that have been in a “rejected” status don’t make their way back onto your board.

Only consider the issue’s most recent status

By default, this workflow rule checks the entire history of an issue from its creation in the project. Selecting this option forces the rule to only evaluate the status set just prior to the issue’s current status. In some cases, this may be the same as the current status. We recommend also selecting the Ignore status updates from looped transitions option to ensure the rule evaluates the most recent different status from the issue’s current status.

Ignore status updates from looped transitions

Some projects use transitions to trigger notifications, automations in connected apps, or other actions. These transitions usually reset the issue’s status to the current issue status. If you’ve selected to Only consider the issue’s most recent status, the most recent status may be the same as the current status. Selecting the Ignore status updates from looped transitions option forces the rule to evaluate the most recent status that’s different from the issue’s current status.

Examples

Quality assurance example

The aim here is make sure that work goes through quality control before its complete. In this case, you can use your workflow statuses to help your team enforce that a quality assurance engineer has looked at your team’s work before deploying it to your customers.

For example, a small feature team may have these columns on their board:

To doIn developmentIn reviewDone

You can use a workflow status as a quality gate before allowing work to be completed in your project. Add the Check that an issue has been through a status rule to the final transition in your workflow, and you can ensure that work has been reviewed properly by your quality assurance engineer before marking the task as complete:

  1. Add a Check that an issue has been through a status rule to the “Any status” transition leading to your “Done” status.

  2. In the Check that the issue has been through dropdown, select the “In review” status.

  3. Select the Include the issue’s current status option.

  4. Select the Only consider the issue’s most recent status option.

  5. Select the Ignore status updates from looped transitions option.

Now, work can freely flow between any status. But, the transition to “Done” is only allowed if the most recent status was “In review”.

To add extra assurance, you may also add the Restrict who can move an issue rule to this transition, and restrict it to a “Quality assurance engineer” custom role. This way, only people in your “Quality assurance engineer” role can move the issue to done. Learn more about custom roles.

Interrupted status example

Your software team may need to consult with a coworker who doesn’t work on your project regularly. For example, a frontend task may need input from a designer while building out your user interface.

This type of input isn’t regularly needed in your workflow, but you want to be able to see and check in on the issues that are waiting for your designer’s input.

In this case, you can create a status for this kind of interruption called “Awaiting design”. Your workflow may look like this:

You can use the Check that an issue has been through a status rule to ensure the issue goes back to where it came from before the interruption in your normal workflow:

  1. Create a status for your interrupted state, and allow any status to transition into your new status. In the example above, the interrupted status is called “Awaiting design”.

  2. Create transitions from the interrupted status back to your main workflow. In the diagram above, the “Restart task” and “Back to in progress” transitions direct issues from our “Awaiting design” interrupted status back into the main workflow (TO DO → IN PROGRESS → DONE).

  3. Add a Check that an issue has been through a status rule to allow the transition that puts the issue back where it came from. For example, if issues were interrupted while they were “In progress”:

    1. In the For transition dropdown, select “Back to in progress” transition.

    2. In the Check that the issue has been through dropdown, select the “In progress” status.

  4. Add a Check that an issue has been through a status rule to prevent the issue moving backward in your workflow. For example, if issues were interrupted while they were “In progress”, you can prevent them from moving back to “To do”:

    1. In the For transition dropdown, select “Restart task” transition.

    2. In the Check that the issue has been through dropdown, select the “In progress” status.

    3. Select the Reverse this rule option.

Now, issues that are interrupted from your main flow and set to “Awaiting design” can only move the following ways:

  • Issues that move from “To do” to “Awaiting design” can only move back to “To do”.

  • Issues that move from “In progress” to “Awaiting design” can only move back to “In progress”.

Restrict who can move an issue

This rule helps ensure only the right people can move an issue at a particular point in your team’s process. You can reduce missed steps in your workflow and make sure your team’s work goes through all the people required.

You can restrict who can move an issue to:

  • The issue’s assignee.

  • The issue’s reporter.

  • A user of your choice.

  • People in a specific role.

  • People in a specific group.
  • People with specific permissions.

Example

Multi-discipline teams usually have different people working on a task at different stages in their process. For example, a small feature team may have these steps in their process:

To do → In design → In development → In review → Done

The disciplines in the team may be mapped to roles:

  • Designer.

  • Software engineer.

  • Quality assurance.

Learn more about managing project roles.

Using the rule, they can add these restrictions to make sure the right roles move their issues:

  • For issues moving from In design, restrict who can move the issue to the role Designer.

  • For issues moving from In development, restrict who can move the issue to the role Software engineer.

  • For issues moving from In review, restrict who can move the issue to the role Quality assurance.

Validate that people have a specific permission

This rule looks at what permissions someone has before they’re allowed to use a specific transition. This check helps your team ensure only the right people can move an issue at the right time. Use this rule to secure your workflow based on people’s Jira permissions.

Example

A team with a basic workflow might have these statuses in their workflow:

StartTo do → In progress → Done

You can use this rule to validate people have a specific permission by:

  • Only allowing people with the Create issues permission to move an issue from StartTo do. This ensures that only the right people can create work for your team.

  • Only allowing people with the Assign issues permission to move an issue from To doIn progress. This ensures that whoever starts working on an issue can assign it to someone.

  • Only allowing people with the Close issues permission to move an issue from In progressDone. This ensures that people aren’t able to resolve an issue without being allowed to.

Copy the value of one field to another

Just like the Update an issue field rule, this one also helps ensure your work is updated in the right places at the right time by reducing data entry errors. The key difference is that this rule updates a field based on another field.

You can either copy the value of a field from:

  • within the issue itself, which copies a field from an issue to another field on the same issue.

  • the parent issue, which copies from the issue’s parent to itself. This option only works if the issue is the child of another issue e.g. copying an issue from an epic (parent) to a story (child), or from a story (parent) to a subtask (child).

When we’ll skip this rule

The information you configure this rule with may not apply to all issue types that share the workflow. So we’ll skip this rule when:

  • it’s on an issue that doesn’t have both your selected fields (in Copy from this field and To this field).

  • it’s configured to copy from the parent issue and the issue doesn’t have a parent.

Don’t worry, this rule being skipped doesn’t mean you’ve done something wrong, or that there’ll be a bug. You’ll be able to go on with your work. It just means there won’t be any fields copied or updated.

How fields are copied

There are three ways a field is copied to another:

  • Append: The field’s value is added to the destination field’s value.

  • Prepend: The field’s value is added to the start of the destination field’s value.

  • Replace: The field’s value replaces the destination field’s value.

Here’s a list of compatible field types and how they’re copied:

Field type

Can be copied to

Is copied by

Text

Text

Summary

Description

Append

Date

Date

Replace

Labels

Labels

Append

Number

Number

Replace

Checkboxes

Checkboxes

Replace

Single select

Single select of the same type e.g. group picker → group picker.

Replace

Multi select


Multi select of the same type. e.g. version picker → version picker.

Replace

User picker (single user)

User picker (single user)

Replace

User picker (multiple users)

Append

User picker (multiple users)

User picker (multiple users)

Replace

Assignee

Assignee

Reporter

User picker (single user)

User picker (multiple users)

Replace

Attachments

Attachments

Append

Update an issue field

This rule helps ensure that issues capture the right information at the right time. You can reduce data entry errors and increase consistency.

Jira can update certain fields for you automatically when you move issues between columns or change their status:

  1. Use the For transition dropdown to tell Jira the column or status that updates a certain field. 
  2. Choose which field you want to update automatically.

You can update any text, number, label, date, or time fields you’ve added to your project, including custom fields. Learn more about custom fields.

A few nuances:

  • When you update a text field using a rule, Jira adds the desired text to existing text in the field. It won’t replace any existing text in the field.

  • When you update a time or date field, Jira replaces anything in the field with the date and/or timestamp of when the card was moved on the board. You can’t specify a static time or date.

Example

Multi-discipline teams usually hand off tasks at different stages in their process. For example, a small feature team may have these columns on their board:

To do → In design → In development → In review → Done

For traceability and reporting, teams might add custom date fields to their issue types to track hand-off dates:

  • Picked up by design
  • Handed to development
  • Handed to QA champion

They can create simple rules that update these hand-off date fields to the current date of when someone moves the issue to a certain column or status:

  • For issues moving to In design, update the Picked up by design field to the current date/time.
  • For issues moving to In development, update the Handed to development field to the current date/time.
  • For issues moving to In review, update the Handed to QA champion field to current date/time.

Unknown custom field type

When updating a custom field of a type unknown to the workflow editor, make sure you enter a value that matches the custom field's type. Otherwise, the rule might not work.

You can use these:

  • %%CURRENT_USER%%, which will be replaced with the user who transitioned the issue.
  • %%CURRENT_DATETIME%%, which be replaced with the date and time of the transition.
  • For Select List (cascading) fields, you can either use the value or the id of the option to be selected.

Custom date and time formats

If you’ve set up a custom date and time format and want to configure this rule to update a date and time field, you must enter your desired in the correct format. If this is the case, you’ll see a text field with instructions on how to fill it instead of a date picker field.

For example, you might see a text field that says to enter a date in the “dd/MMMM/yyyy h:mm a” format. One date you could enter would be “15/July/1968 9:30 PM”. To learn more about these formats, check out Java SimpleDateFormat.

To change your date and time formats, you can configure the look and feel of Jira. Learn more about configuring the look and feel of Jira.