YouTrack Cloud 2024.1 Help

Board Behavior

The Board behavior settings define how issues are added to the board. There are different sets of options for boards with sprints and boards without sprints. This page explains how each option affects the behavior of your board.

Options for Boards with Sprints

With sprints enabled, an additional dimension is added to your board. You have a series of sprints that can be assigned a duration in time. Each issue is assigned not only to the board, but also to a specific sprint. The board only displays issues that are assigned to the selected sprint. Switching between sprints displays a different set of issues.

The board behavior options that are available for boards with sprints determine how issues are added to each sprint.

Sprint options

Manually Assign Issues

This is the default option for new boards. To add an issue to the board, you must explicitly assign it to a sprint. You can either apply a command (Board <board name> <sprint name>), drag an existing issue from the backlog to the sprint, or add an issue directly on the board.

This option gives you the most control over which issues are assigned to each sprint.

The two remaining options let you add issues to sprints automatically under certain conditions, however, you can still add issues manually to any sprint no matter which option you choose.

Automatically Add New Issues to Sprint

With this option enabled, new issues are added to the selected sprint automatically. Issues are added automatically when:

  • The issue is assigned to a project that is managed on the board.

  • The value that is set in the custom field that identifies columns matches a column that is visible on the board.

Every time you schedule a new sprint, the option to update this setting is visible in the New Sprint dialog.

Teams that follow the Scrum development framework usually commit to the issues that they want to finish at the beginning of each sprint. Adding issues to the sprint automatically can add work that is outside the scope of the current sprint and defeats the purpose of sprint planning.

Many teams use this option to assign issues to an unscheduled sprint that is used for planning. All the issues that are created in the projects are then visible on the board without having to check the backlog. These teams review issues that have been added to the unscheduled sprint and assign them to scheduled sprints for implementation.

For boards that add issues automatically, issues that are linked as subtasks to cards on the board are added to the swimlane for uncategorized cards. To remove subtasks from this swimlane, enable the Ignore subtasks of existing cards option. For more information, see Ignore Subtasks of Existing Cards.

This option lets teams that synchronize their fix versions with sprints continue to use older boards without changing their working process. You can also use this option to link sprints to custom fields that store any enumerated type, including fields that store a build, state, version, ownedField, or enum.

For boards that add issues automatically, issues that are linked as subtasks to cards on the board are added to the swimlane for uncategorized cards. To remove subtasks from this swimlane, enable the Ignore subtasks of existing cards option. For more information, see Ignore Subtasks of Existing Cards.

With this option enabled, the board mimics the behavior of boards in YouTrack versions earlier than 7.0, where sprints were linked to fix versions. The sprint name is linked to the set of values in the selected custom field.

When you enable this option, YouTrack performs the following operations:

  • A new sprint is created for every value in the set for the selected custom field. If the linked field stores a version type, the following settings are applied to each sprint:

    • Sprints are assigned a schedule that coincides with each value's Start date and Release date.

    • Sprints for values that only have a Release date are scheduled to start two weeks earlier than the release date. YouTrack also updates the corresponding custom field values with the calculated start dates.

    • Sprints for values that only have a Start date are created without a release date.

    • Sprints for values that have neither a Start date nor a Release date are created as unscheduled.

    • Sprints are not created for linked values that are marked as Released or Archived.

  • If the custom field can be empty, an unscheduled sprint is created for the empty value. If you have multiple projects that do not use the same empty value for the linked field, an unscheduled sprint is created for each empty value.

  • Existing sprints that do not match a value in the linked sets of values are archived.

Once this option is enabled, actions that you perform on the board affect the value of the linked custom field, and vice versa. Users who update issues on the board don't require any special permissions. To add, rename, or remove sprints, the owner of the board must have permission to edit the set of values (Update Project) in all the projects that use this custom field.

Here's what happens to the value in the linked custom field when you update sprints on the board:

Action

Result

Add issue to sprint

The value in the linked custom field is set to the sprint name. This applies to issues that are added as cards or swimlanes.

Remove issue from sprint

The value is removed from the linked custom field in the issue.

  • If the linked custom field can be empty, the issue is assigned to the unscheduled sprint that is associated with the empty value.

  • If the linked custom field cannot be empty, you can change the value that is stored in the linked custom field to assign the issue to another sprint.

Add sprint to board

The sprint name is added to the set of values in the linked custom field for all projects that use this custom field.

Add unresolved issues from current sprint to new sprint

Existing values in the linked field are overwritten with the name of the new sprint, even when the linked field is configured to store multiple values.

Rename sprint

The corresponding value in the linked custom field is also renamed.

Change sprint schedule

If the linked field is of version type, the Start date and Release date attributes of the version value are updated according to the new schedule.

If the Sync sprint dates with release versions option is disabled, the version value remains unchanged.

Archive sprint

The corresponding value in the linked custom field is also marked as archived. This action is only applied when the linked custom field stores a version type.

Delete sprint from board

The sprint is deleted. The value that corresponds to the name of the deleted sprint is removed from the set of values in the linked custom field.

Here's what happens to sprints on any agile board that is linked to the custom field when you update values in the linked custom field:

Action

Result

Update the value in an issue

The issue is automatically added to the corresponding sprint on any board that is linked to this custom field. If the corresponding sprint does not exist on the board, a sprint with a name that matches the new value in the custom field is created.

Remove a value from an issue

The issue is removed from the corresponding sprint.

Add value to the set

A sprint with corresponding name is created in all agile boards that are linked to this custom field. Issues are assigned this value when they are added to the new sprint.

Edit a value in the set

The corresponding sprints in all agile boards that are linked to this custom field are renamed. The value is updated in all issues that are assigned to the corresponding sprint, assigning them to the renamed sprint. This behavior varies slightly when you manage multiple projects on the board:

  • If you edit the value in one of the projects, a sprint that corresponds with the new value is created in addition to the sprint that corresponds to the previous value.

  • If you later edit the value in all the other projects to match, the sprint that corresponds with previous value is archived.

Mark a value as archived

The corresponding sprints in all agile boards that are linked to this custom field are archived.

Delete a value from the set

The corresponding sprint is deleted from the agile board.

If the custom field can contain an empty value, the following changes are applied to all issues that are assigned the deleted value:

  • The deleted value is cleared from the custom field.

  • All the issues that were assigned the deleted value are assigned to the unscheduled sprint that is associated with the empty value.

If the custom field cannot be empty, you are asked to replace the deleted value with an existing value in the set. In this case:

  • The value is replaced in all issues that are assigned the deleted value.

  • The issues are moved to the sprint that corresponds with the replacement value.

If you switch to another board behavior option at a later date, the issues on the board are updated to match the behavior of the modified board:

  • The link between sprints and the custom field is removed.

  • All issues that are currently assigned to sprints on the board are linked explicitly to the sprint no matter what value is set in the custom field.

Options for Boards without Sprints

For boards with sprints disabled, what you see is what you get. All the issues that are assigned to the board are visible without switching sprints.

The board behavior options that are available for boards without sprints determine how issues are added to the board.

Board behavior no sprints

Manually Assign Issues

To add an issue to the board, you must explicitly assign it to the board. You can either apply a command (add Board <board name>), drag an existing issue from the backlog to the sprint, or add an issue directly on the board.

This option gives you the most control over which issues are managed on your board. If you choose the option to filter cards to match a query instead, you can still add issues manually to the board.

Automatically Add New Issues

With this option enabled, new issues are added to the kanban board automatically. Issues are added automatically when:

  • The issue is assigned to a project that is managed on the board.

  • The value that is set in the custom field that identifies columns matches a column that is visible on the board.

With this option enabled, all the issues that are created in the projects are visible on the board without having to check the backlog.

For boards that add issues automatically, issues that are linked as subtasks to cards on the board are added to the swimlane for uncategorized cards. To remove subtasks from this swimlane, enable the Ignore subtasks of existing cards option. For more information, see Ignore Subtasks of Existing Cards.

Filter Cards to Match a Query

With this option enabled, new issues are added to the board automatically. Issues that match the search query are added automatically when:

  • The issue is assigned to a project that is managed on the board.

  • The value that is set in the custom field that identifies columns matches a column that is visible on the board.

In order for this feature to work properly, you need to include the default value for new issues in all the projects that are referenced in the board settings in the set of values that identify columns on the board.

If you enable this option and leave the search query field empty, all the issues in the selected projects are added to the board. Each issue is placed as a card in the column that matches the value for the field that identifies the columns.

If you add issues from the backlog to the board manually, these issues are updated so that they start matching the search query. If there are several conditions joined by an OR operator in the search query, the issue will match the first condition. If the first condition in the search query can't be matched, for example, if it's an excluding one with the - symbol, the issue will match the next condition.

When you switch from a board that uses a filter back to the option to manually assign issues, all the issues that are currently visible on the board are linked explicitly to the board.

For boards that add issues automatically, issues that are linked as subtasks to cards on the board are added to the swimlane for uncategorized cards. To remove subtasks from this swimlane, enable the Ignore subtasks of existing cards option. For more information, see Ignore Subtasks of Existing Cards.

Search Queries

When specific board behavior options are enabled, you can use a query to filter the cards on the board. This setting is only available when one of the following options are enabled:

Sprints

Board behavior

Enabled

Link sprints to custom field

Disabled

Filter cards to match a query

When used, the query filters the issues that are shown as cards and swimlanes.

  • When you set a query for an existing board, issues that don't match the query are not removed from the board. You simply don't see them.

  • After the query is applied to the board, any issue that you add to the board — whether manually or with a command — is updated to match the attributes in the search parameters.

  • You can use the filter control at the top of the board to further limit the issues that are returned by the query.

When you use a query to filter cards on the board, you can use a sort attribute to sort the cards automatically. For more information, see Sort Cards on an Agile Board.

Relative Queries

A query that uses relative parameters can produce strange or unexpected behavior on the board. Values for parameters like Today, Yesterday, last week, and this week are recalculated every time you open or refresh the board. The value that is displayed in the auto-completion popup is not stored in the query — only the text-based variable.

board behavior relative value in query

This means that a query like created: {this month} shows issues that were created during the current month. As soon as the calendar changes to the next month (in this case, from November to December), any issue that was created the month prior disappears when the board is refreshed.

If you use relative parameters in a query, you may experience strange behavior with:

  • Live update — cards that match the filter criteria when the board is opened can disappear when the issue no longer matches the criteria after an update is applied.

  • Workflow support — workflows that react to sprint changes can apply unexpected changes.

  • Adding issue to a sprint from the backlog — issues in the backlog that do not match the parameters in the query cannot be added to the sprint.

You can use a board with a relative query as an alternative view to the Issues list, but we don't recommend that you use this type of board to update issues.

Personal Queries

The value for search queries that include the keyword me is also recalculated every time the board is opened or refreshed. You can use this parameter to create one board that gives each user a view of their own issues. For example, a search query like #unresolved for: me shows only unresolved issues for the currently logged-in user. Each member of the project team can open the board and see only the issues that are assigned to them.

Ignore Subtasks of Existing Cards

For boards that add issues automatically, issues that are linked as subtasks to cards on the board are added to the swimlane for uncategorized cards. This is because the subtasks meet the criteria for being displayed on the board, but don't contain the attribute that defines an existing swimlane.

Given that subtasks are displayed on cards in XL view, showing subtasks on the board can create unnecessary visual clutter.

To remove subtasks from the swimlane for uncategorized cards, enable the Ignore subtasks of existing cards option. This option is only active when the selected board behavior option adds cards to the board automatically. This includes the following combinations of settings:

Sprints

Board behavior

Enabled

Automatically add new issues to selected sprint

Link sprints to values for selected custom field

Disabled

Filter cards to match a query

Last modified: 08 March 2024