Board Behavior - Help | YouTrack Standalone

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.

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

Link Sprints to Values for Custom Field

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.

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 operation:

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 the Release date that is assigned to each value. Sprints for values that are not assigned a Release date are scheduled for two weeks starting with the current week.
- 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 of 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 value that is used for the sprint. 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.
Rename sprint	The corresponding value in the linked custom field is also renamed.
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 of 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 of 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 of 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.

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.

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.

If you enable this option and leave the search query field empty, all of 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.

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

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.

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.

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