Kanban Board

The KanbanBoard shows a table's records as cards in lanes side by side, one lane for each value of a column: an opportunity's rating, a task's status reason, the account a record belongs to. Each lane is read on its own through a view, a page at a time, with the same query and security as a grid, and shows its count and totals in its header. In an Editable board a card moves to another lane by dragging it, from the keyboard or through its Move to menu, and the move is saved at once; with a rank column, cards are put in order by hand as well. It is drawn in your Fluent UI theme.

Lanes

LaneColumn (React: laneColumn) names the column of the view's table the lanes come from. A choice gives a lane for each of its options, a status reason one for each reason, a Yes/No column one for each of its two values, a lookup one for each record it names, and a date the lanes of when it falls, as Date lanes below describes. Any other column shows a message in place of the board. The lanes follow Dataverse's order and leave out hidden options, and an option's color shows as a dot beside its lane's name. A column a record may leave empty adds a last lane, (No value), for the cards without one.

Lanes (React: lanes) chooses which lanes are shown, and in what order, by key: an option's value, 1 and 0 for Yes and No, a record's id, or an empty key for the lane without a value. A lookup's lanes are the records the view's cards name, read in one grouped query; name them in LookupLanes (React: lookupLanes) instead to fix them and their order, a lane with no cards included.

A lane with no cards is shown, so a card can be dropped in it. Set ShowEmptyLanes (React: showEmptyLanes) to false to hide it once its count is known. Users can collapse a lane to a narrow strip of its name and count with the button in its header, and hide lanes from the toolbar's Filter menu, which lists them under Show.

Date lanes

A date column gives lanes of when its date falls, counted in days of the user's own time zone, with the week starting on their language's first day, and worked out again each time the board reads its lanes. With none named, they are Overdue, Today, Tomorrow, This week — from the day after tomorrow to the week's end, so empty near the end of a week — Next week, Later and No date.

DateLanes (React: dateLanes) names the lanes instead, in date order. A preset sets a lane up from the current date: Yesterday, Today and Tomorrow; LastWeek, ThisWeek and NextWeek; LastMonth, ThisMonth and NextMonth; the calendar's quarters and years, such as ThisCalendarQuarter and NextCalendarYear, and the fiscal ones, such as ThisFiscalQuarter and LastFiscalYear, which follow the organization's fiscal year as Dataverse keeps it; Overdue, before today; Earlier and Later, which take whatever falls before and after the lanes around them; and NoDate. A lane of your own holds exact days, or days counted from today's periods, under a title of its own: Between, Before and Starting (React: between, before and starting). A preset takes a title of its own too. Try it on the Close dates demo.

Each card lands in one lane, as a lane starts no earlier than where the one before it ends: listed after ThisWeek, ThisMonth holds the rest of the month, and a lane the ones before it already cover shows empty and takes no card. A date no lane holds — between two lanes of exact days — puts its card on none, so start with Earlier and end with Later to keep every card.

A card moved to another date lane is given that lane's first day, keeping its time of day — a lane behind today too, which gives it a past date — and moved to No date, it loses its date. A lane without a first day, such as Overdue, a first Earlier or an empty lane, takes no card. Set DateLaneDrop (React: dateLaneDrop) to None and the lanes take no card from one another: they only show when cards fall.

DateLaneOrder (React: dateLaneOrder) orders a date lane's cards. Rank, the default, orders them by the rank column, as every other lane: a card moved within its lane changes its rank alone. Date orders them by the date instead, with no rank column: a card dropped below another takes that card's day, keeping its own time, and one dropped at the top takes the lane's first day; cards of the same day stay in the order of their times. Try it on the Due dates demo.

Counts and totals

Each lane's header shows how many cards it holds — 5000+ past 5,000 — and the totals named in LaneAggregates (React: laneAggregates): the sum, average, least or most of a number, money or date column, or a count of any column, over every card of the lane, not only those loaded. LaneAggregateFormats (React: laneAggregateFormats) gives each column's figures a format, such as C0 or N1. These are the totals the board starts with: the Totals button lets users choose their own of the columns the cards show, and a saved view keeps them. Counts and totals are read again after every move the board saves.

Lane limits

LaneLimits (React: laneLimits) gives lanes, by key, the most cards they should hold. A limited lane's header shows its count against its limit, as 7 / 5, marked once the count passes it. The count is of all the lane's cards, whatever the user searches for or filters by. A limit only warns unless EnforceLaneLimits (React: enforceLaneLimits) is set: then a full lane takes no card from another, isn't offered under Move to, and has no Add button. It is the board's rule, not the server's: keep a limit for every way a record is saved with an interceptor.

Cards

A card shows the view's first column as its title and the view's other columns under their titles, as a grid's cards do, leaving out the lane column and the rank column. CardImageColumn (React: cardImageColumn) adds an image column as an avatar beside the title. Each lane loads PageSize (React: pageSize) cards at a time, 20 by default, with Load more at its foot. From Settings, users change the fields the cards show, how a lane's cards are sorted and how many each lane loads.

Draw the cards your own way with CardTemplate (React: cardRenderer). It is handed each card's record and lane; Field, Label and DisplayValue (React: field, label and displayValue) show a column as the default card does, and OpenAsync and MoveToAsync (React: open and moveTo) open the record and move the card, where CanOpen and CanMove say they can. A click on the card still opens its record, and its Move to menu sits beside your content. The columns a template shows must be the view's, so the board reads them with each card.

Where the board's table has a page registered for its records (see Record Pages) and the board has no Form (React: form), a card's title links to it, and opening the card goes there; ShowRecordLinks (React: showRecordLinks) turns that off. Otherwise, clicking a card opens its record in a dialog in the center or, with FormLocation (React: formLocation), in a side panel on the left or the right. The form is KanbanDefaultForm — the view's columns of the board's table and the lane column, each with the editor its type takes — or your own component of editors in Form (React: form). The record is read as a record page reads it, through the same table access and column security, and can be changed only in an Editable board, by a user who may change it.

Moving cards

In an Editable board (React: editable), users move a card to another lane by dragging it, from the keyboard or through the Move to menu on the card. The card moves at once, and the board saves what changed: the lane column — for a status reason, the reason alone, as the server moves the record's state with it — and the card's rank, where the board keeps one. A save that fails puts the card back and says so.

A card moves only where the user may change it: Write on its record, through the portal's table access, and on its lane column, which must be one an update can set and that column security doesn't withhold. Putting cards in order needs Write on the rank column too. A card the user can't move stays where it is, with no Move to menu.

Status reason lanes follow their states, and the changes of state the table allows, which the server registers with AddStateTransitions (see RecordContext). Opportunities, cases, quotes and orders have them by default: a card isn't taken by a lane its record can't reach from its own, and Move to lists only the lanes it can. A change of status an update makes — an opportunity reopened, a case canceled or reactivated, a quote activated, an order submitted — asks the user to confirm it first, and one Dataverse makes with an action of its own opens the close dialog, as Closing records below describes. The cards of a closed status aren't put in another order among themselves. A table without transitions moves freely: a task moved to Completed is completed, and moved back, open again.

Adding cards

Each lane's header in an Editable board has an Add button that opens a new record already in that lane, in the board's form: the page's Form (React: form) or KanbanDefaultForm. It shows only to users who may create the table's records and set its lane column, and never in a lane of closed records, as a record is created open. Once saved, the card appears at the top of its lane. Turn it off with AllowNew (React: allowNew). Handle PrepareNewRecord (React: prepareNewRecord) to give the new record more values before its form opens: it is given the record, the lane's value already in it, and the lane. A toolbar button can add a card too: CanCreate and NewAsync on the KanbanBoardContext (React: canCreate and newCard) say whether a lane takes a new card and open its form — with no lane named, in the first that takes one.

Closing records

On a board by status reason, a card dropped in a lane that Dataverse closes records into with an action of its own — an opportunity's Won or Lost, a case's Resolved, a quote's Won or Closed, an order's Fulfilled or Canceled — opens a dialog for the status reason, the lane's to start with, and what the close records: the actual revenue and close date of a won opportunity; the close date of a lost one, and the competitor it was lost to where the user may pick competitors; the resolution and billable time of a case; the close date of a quote or an order; and a description. Confirmed, the record is closed through Dataverse's own message, such as WinOpportunity or CloseIncident; canceled, the card goes back. Dragged back to an open lane, an opportunity is reopened and a case reactivated once the user confirms. Try it on the Pipeline demo. The same dialog is behind the close buttons on a record's form, such as WinOpportunityButton: see RecordContext.

A close is judged as a change of the record's status: the user must be allowed to change the record and its status columns, and to point at the competitor they name. Dataverse files the close under the record as an activity of its own (opportunityclose, incidentresolution, quoteclose, orderclose), which needs no table access of yours. The portal's application user needs AppendTo on the record's table, Create and Append on activities, and for an opportunity AppendTo on competitors: see Dataverse Connection.

Putting cards in order

Name a RankColumn (React: rankColumn) and users put each lane's cards in order by hand. A lane is sorted by the rank, then by the view's sort, and a card dropped between two others is given a rank between theirs. Usually that rank is all a drop writes. Cards with no rank sort first, and are ranked in turn when a card is dropped among them or just below them; a lane whose ranks have no room left between two cards is ranked afresh, in the order it shows. Those ranks are saved with the move, in one transaction. A lane of more than 5,000 cards can't be put in order by hand, nor can a card be dropped where it would rank one the user may not change. Without a rank column, a lane follows the view's sort, and a card moves only to another lane.

The rank column is a Decimal column of the board's table whose range allows negative numbers, since a card dropped above the first is ranked below it. Its precision decides how often a lane is ranked afresh: cards start a million apart, and each drop between two halves the room between them, so a column of ten decimal places takes some fifty drops in one place before its lane is ranked again, and one of none about twenty.

Saving moves yourself

Handle SaveChange (React: onCardMove) to save a move your own way, in place of the board: through a service of your own, after asking the user, or not at all. It is given a KanbanCardMove: the card's Record, the lanes it came From and went To, its Index there and its Rank, the Update the board would write, and the OtherUpdates that belong in the same transaction, written after it — other cards' ranks, or, for a card leaving a closed lane, its own rank once its status has reopened it — and, for a card dropped in a lane that closes it, the Close (React: close) the user confirmed, to send after them. Return true to keep the card where it was dropped, or false to put it back. The board reads nothing again after a move it didn't save, so a page can keep a move on the page alone.

Keyboard, touch and screen readers

Every card that can move has a … button with a Move to menu of the lanes it can go to, which works the same from the keyboard, by touch and with a screen reader. A card can also be moved from the keyboard directly: focus it, press Space to pick it up, the arrow keys to carry it to another lane or another place in its own, and Space again to put it down. On a touch screen a card is dragged by its grip, so the lanes still scroll under a finger. Screen readers hear each move — Card moved to Lane — and a move that fails.

Toolbar

The toolbar is laid out as a grid's: the view picker on the left — or the Title (React: title), when there is only one view — and on the right your own controls, Totals, the search box, Filter, Refresh and Settings. Add your controls with ToolbarItems (React: the board's children). A KanbanBoardButton is handed the board when clicked: its table, the view it shows, its lanes in their order, and RefreshAsync (React: refresh) to read every lane again.

Views, search and filters

A board shows the records of a view — one of Dataverse's or one the page defines — and its table is the view's. DefaultViewId (React: defaultViewId) is the view it opens on, and ViewIds (React: viewIds) the others the view picker offers, of the same table. The search box finds cards as a grid's search finds rows: from the start of a search column's value, or anywhere after a leading *. It looks in the columns the cards show, names them in its tooltip, and marks the matches on the cards. Turn it off with AllowSearch (React: allowSearch).

With AllowFiltering (React: allowFiltering), the toolbar's Filter menu offers Edit filters, the dialog a grid's Filter button opens, whose filters take the place of the view's own until the user picks another view. It is off by default, because the user can take away every filter the view has.

With AllowSavedViews (React: allowSavedViews), a signed-in user can save the board as they've arranged it — the view with their filters, the cards' fields and sort, the lanes' totals, the cards each lane loads, and the lanes collapsed or hidden — as a view of their own, and choose their default view and hide the ones they don't use, from the Filter menu. Without a SavedViewsKey (React: savedViewsKey), a board shares its views with the grids, calendars and boards of its table that have none, each keeping its own layout of them. How views are saved, changed and shared is on the Saved Views page.

A page can define views of its own in code with CustomViewDefinitions (React: customViewDefinitions), the grid's view definitions. They are offered in the picker beside ViewIds without being listed there, DefaultViewId can name one, and a board can have these alone. Each is read by its own FetchXML, within the user's table access, and lays the board out as it says: its PageSize is the cards a lane loads, a column's Hidden and DisplayLabel hide or retitle its card field, and its Aggregates are the lanes' totals. Build the list once, in a field: a new list starts the board again.

Keeping its place in the URL

Name a query parameter in PersistedStateQueryParameter (React: persistedStateQueryParameter), and the board keeps the view picked and the lanes collapsed there, so a reload or a shared link opens it as it was left. What it would open on anyway is left out. The search is kept too with IncludeSearchInPersistedState; it is left out by default, since what users search for can be sensitive. Each change replaces the browser's history entry, and both stacks write the same value, so a link made on one opens the same board on the other.

Theming

The board is drawn with Fluent UI's own controls and design tokens, so it follows your theme, light or dark, and your accent color, and a lane's dot takes its option's color from Dataverse. Lanes are 280 pixels wide, side by side, and scroll sideways when they don't fit; on a phone each takes most of the screen and snaps into place. Height (React: height) sets the board's height, toolbar included — 600 pixels by default — and each lane scrolls its cards within it. To restyle it, the board, its lanes and its cards carry classes of their own, among them ppp-kanban, ppp-kanban-lane, ppp-kanban-lane-header and ppp-kanban-card; Class and Style (React: className and style) add your own.