Board
The Board page of a project: the running sprint's work in a column per status, dragged along its lifecycle and into its place in the order, with the limits each column keeps, swimlanes by epic, person or kind, and the quick filters.
By the end of this page you will know what the board shows and for which scope, how a drag moves a card along its lifecycle and into its place in the order, what a column's limit does and why a drop is sometimes refused, how the swimlanes and the quick filters narrow the view, and what an agent reads when it asks for the board.
The board is the backlog seen as columns: one column per work item status, from Backlog on the left to Done and Cancelled on the right, with a card for each item. It has no record of its own. A card is a work item, a column is a status, the order of the cards in a column is the order of the backlog, and the columns the project hides and the limits it sets come from the project settings. Dragging a card to another column is the same move the backlog's Move to makes, with the same lifecycle, the same versions and the same event; dragging it up or down changes its place in the project's order, which the backlog shows too. The board is the team's: a client guest never opens it.
Before you begin
| To | You need |
|---|---|
| Open the board | work-item:view-any; a viewer, an analyst, a tester and a release manager read it |
| Drag a card to another column | work-item:transition; the project manager, the developers and the testers by default |
| Drag a card to a new place | work-item:rank; the project manager and the developers by default |
| Take a card | work-item:assign |
| Hide a column or set a limit | project:update, under the project's settings |
A running sprint gives the board its default scope. Without one, the board shows every open item of the project.
Open the board
Board in the project's sidebar, between Backlog and Sprints, opens the page. The columns run left to right in the order of the lifecycle: Backlog, Ready, In progress, In review, In QA, Done and Cancelled, minus the columns the project hides. Each column's header shows its name, how many items it holds and, when the project has set one, its limit as held / limit, with the story points in the column beside them.
When the scope is a sprint, a card above the columns names it with its status, its dates and the days left, the points done against the points planned, how many cards the quick filters leave of the scope, and a button that opens the sprint on the Sprints page. For the other scopes a line says what the board is showing.
A project with nothing on the board reads Nothing on the board yet with a word on why: the sprint holds no items, every open item is planned into a sprint, or the backlog is empty. The buttons there open the backlog and the sprints.
Pick what the board shows
The first control above the columns is the scope:
- Running sprint is the default: the items of the sprint that is active, in every column. When no sprint runs, the board falls back to all open work.
- A sprint by name from the list of sprints that are planned, with the team or running, so a planned sprint can be looked over before it starts.
- All open work: every open item of the project, and the items finished or dropped in the last two weeks, so a done card does not vanish the moment it is dropped in its column. Teams that run without sprints live here.
- Unplanned work: the items in no sprint, open or lately finished, which is what sprint planning draws from.
A link that names a sprint the project no longer has falls back to the running sprint.
The second control chooses the swimlanes. With none, the board is one row of columns. By epic lays a row out per epic, named by its reference and title, with the items under no epic last; by person lays one out per assignee by name, with the unassigned items last; by kind lays one out per work item kind in the order of the lifecycle's kinds. The column headers stay on top; each lane repeats the columns under its own heading, and a card dragged in another lane's column changes its status, never its epic, its person or its kind.
The quick filters narrow the cards without changing the tallies in the headers: a search over the reference and the title, a kind, Mine for the cards assigned to you and Unassigned for the cards nobody holds. Clear Filters drops them all. When the filters leave no card, the board says so under the columns and offers the same button; the headers keep counting every item of the scope, because a limit counts the column, not your view of it.
The scope, the swimlanes and the filters live in the page's address, so a link to the board carries them.
Drag a card
Pick a card up and drop it in a column. While it is in the air, the column under the pointer lights up, the card it would land above shows a ring, and the card you hold is drawn as a dashed ghost in its old place. Dropping it does two things at once:
- Moves the item when the column differs from its own status, exactly as Move to on the backlog does. The lifecycle decides what is allowed from where the item stands; a move into Done resolves it as done, a move into Cancelled records it as won't do, the first move into progress stamps when work started, and every move writes a version with the reason moved. A drop the lifecycle refuses leaves the card where it was and says why in a toast, as does a drop into a full column.
- Places the item above the card it landed on, or below the last card when it landed at the bottom. The place is the item's position in the project's order, the one the backlog's default sort reads, so a card dragged to the top of Ready is also the first ready item on the backlog. Positions are kept with room between them, so one drag writes one row; when the room runs out the project's order is renumbered in the same move. Placing an item writes no version, because its position is not part of its record.
A card dropped in its own column only changes place; the toast then reads keeps its column at its new place in the order. A card dropped in an empty column only changes status. The board draws itself again from what the server kept, so a drop that was refused never leaves a card where it cannot be.
Touch and keyboard
The drag is the browser's own, which touch screens do not offer, so the card's menu does the same work: Move to lists the columns the lifecycle allows and the board shows, and Open in Backlog opens the item's flyout, where the order can be changed by hand once the backlog offers it. The drag never touches a card the viewer may neither move nor place.
Move and take a card from its menu
The dots on a card open its menu:
- Open in Backlog opens the item's flyout on the backlog, with its fields, criteria, links, comments, files and versions.
- Move to offers the columns the lifecycle allows from where the item stands, among the columns the board shows; a column the project hides is not offered here, though the backlog's Move to still reaches it.
- Assign to Me hands the card to you, when it is not yours already;
work_item.assignedgoes out and the person who held it before is named in it.
The card itself shows the reference with the kind's colour, the title (a link to the backlog), the epic when the lane does not already say it, the priority, the story points, the sprint when the scope is not a sprint, and the assignee's initials or Unassigned.
Keep a column under its limit
A work-in-progress limit caps an open column. The project's settings carry one per status under Board limits and hidden columns, and the header shows it as held / limit, turning red when the column holds as many as the limit allows. From that moment every move into the column is refused, from a drag, from the menu, from the backlog, from an agent and from the API alike, with a message that names the column, what it holds and the limit; the count is the project's, across every sprint, because the limit is about the team's load rather than one sprint's. Finish or move something out, and the column takes cards again. The closed columns, Done and Cancelled, take no limit.
Hidden columns take a status off the board entirely. Items in a hidden status stay in the backlog and in the counts the backlog shows; they are simply not drawn here, and a card's Move to does not offer a hidden column. Hide Cancelled to keep the dropped work out of sight, or In review when the team does not review code in the tracker.
All the fields
The board has no form of its own; its controls and the parts of a card are these.
What happens next
- A drag into another column, or Move to, runs the same move as the backlog: the item's
status, resolution and stamps change, a version is written with the reason moved, and
work_item.transitionedgoes out with the status before and after. - A drag to a new place writes the item's position and
work_item.rankedgoes out with it; a drop that leaves the position as it was emits nothing, and the items renumbered around it when the order ran out of room emit nothing of their own. - Assign to Me writes the assignee and
work_item.assignedgoes out with the person before and after; the backlog's My Work and an agent'slist_my_workread the hand-over at once. - The running sprint's points done and planned, on this page and on the Sprints page, follow the moves into and out of Done.
Heimdall on this page
The board has no assist of its own; the cards are the backlog's items, and the assists on their fields live in the backlog's editor. Heimdall's panel reads the board the way an agent does, so ask it what is in progress for the running sprint, which columns are full, what nobody holds, or what has sat in review longest; its answer names the cards and opens them.
From the API and MCP
Work items API
Move an item along its lifecycle, hand it over, and rank it before or after another item or at the end of the project's order.
get_board_snapshot
An agent reads the columns the project keeps, their limits and tallies, and the cards in each, for the running sprint or any scope.
move_work_item and assign_work_item
The same moves and hand-overs an agent makes, under the same lifecycle and the same column limits.
work_item.* events
Transitioned, ranked and assigned, with the rest of the family.
Permissions
| Action | Permission |
|---|---|
| Open the board | work-item:view-any; never a client guest |
| Drag a card to another column | work-item:transition |
| Drag a card to a new place | work-item:rank; without it a drag still moves the card between columns |
| Take a card | work-item:assign |
| Read the board as an agent | work-item:view-any, as staff |
| Rank an item over the API | work-item:rank |
| Hide a column or set a limit | project:update |
Frequently asked
My drop was refused. Why? Two reasons, and the toast names which. The lifecycle does not allow the move from where the item stands, as from Ready straight into Done; or the column is full, which its red held / limit shows. Move the card through the steps the lifecycle allows, or make room in the column.
Where did my done card go? A sprint scope keeps its done cards for the life of the sprint. All open work and Unplanned work keep a finished or dropped card for two weeks after it was finished, then let it go; the backlog keeps it for good.
Does dragging on the board change the backlog? Yes, in both directions. A card's column is the item's status, which the backlog shows; a card's place is the item's position, which the backlog's default sort follows. A sort by another column on the backlog is a view, and does not change the order.
Does the limit count only the sprint I am looking at? No. The limit counts every item of the project in that status, whatever sprint it is in or none, because it caps what the team has in hand. The header shows the same count in every scope.
Why did the positions of other cards change after one drag?
Positions are whole numbers kept with room between them. When two neighbours have no room left,
the project's order is written again with the room restored, the item in its new place and
nothing else in a different order. The other items' positions change, their records do not, and
only the dragged item's work_item.ranked goes out.
Related
- Backlog: the items on the cards, their fields, their flyout and the same moves in a list.
- Sprints: the scope the board follows by default, and the points it shows.
- Project settings: the hidden columns and the limits.
- Epics: the swimlanes by epic.
- Revisions and versions: the version every move writes.
How is this guide?
Last updated on
Building
Where the team turns the planning record into working software: the sprints it plans and commits to, the board it works them on, with the time tracking, the definitions of ready and done and the Git links joining as they land.
Sprints
Plan a sprint with its dates, goal and capacity, pull its scope from the backlog, put it to the team for the commitment that starts it, follow it while it runs, close it with its velocity and carry the unfinished work on.