Tecto docs
tectoapp.io

Boards, columns and lanes

A board lives in a collection. Collections are how boards are grouped ("Product", "Client work", "Internal"), and a board sits at a collection's root, never underneath another board.

A board is three things at once, and it is worth separating them:

  1. A grid: its columns and lanes.
  2. A document: a body you can write in, above the grid.
  3. A set of cards: these are pages, and are their own page.

The board's own icon sits beside its title at the top of the board. Click it to pick an emoji or an icon, or to upload an image; without one the board shows a faint board mark there.

The grid

Columns are the stages: To do, Doing, Done. Each has a label and, if you want one, an icon. A column has no colour, and that is deliberate: it would be a second mark beside the icon, and the weaker of the two, because a colour has to be learned per board and a glyph does not.

Lanes are the horizontal split: by team, by workstream, by client. A lane has a label and, like a column, an optional icon, set with the same picker on its heading. A lane has no colour either.

Names are unique per board: two columns cannot share a name, nor can two lanes, and a lane cannot take the name of the row of cards in no lane. Case and spaces at the ends do not count, so "Team A" and "team a" are the same name. A column and a lane may share one.

Both are just lists on the board. Reordering columns is reordering the list. Either can be folded away, and so can the implicit row of cards in no lane; that state sits on the board, so a column folds for everyone who opens it.

That row of cards in no lane can also be given a name of its own on a board, say "General", from the ⋯ menu beside its heading (noLaneLabel in the API). Leave the name empty and it is called "No lane" again. It stays the row without a lane: it cannot be moved or deleted, and its cards have no lane.

A lane is deleted from the ⋯ menu beside its heading: Delete lane…. The question before it says how many cards the lane holds. They are kept: each stays in its column and moves to the row of cards in no lane. In the API that is removedLanes with {"moveTo": null} for the deleted lane.

curl -X PATCH "$BASE/api/v1/workspaces/$WS/boards/$BOARD" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "columns": [
      { "id": "…uuid…", "label": "To do"  },
      { "id": "…uuid…", "label": "Doing"  },
      { "id": "…uuid…", "label": "Done" }
    ]
  }'

Three properties of that call are load-bearing:

  • The list is replaced whole, not merged. Send every column you want to keep. There is no "add one column" call, because two clients each adding one column to a partial list is how a board silently loses a stage.
  • You mint the ids. A column's id is yours and board-local, which is what lets you rename "Doing" to "In progress" without touching a single card: the cards point at the id, not at the label.
  • Deleting a column does not move its cards. They keep the id they had, and the grouped read reports them under it. Nothing is lost, and nothing is silently reassigned to a stage you did not choose. But a board in that state has cards you cannot see in the grid until you re-add the column or move them.

A new board starts with no columns and no lanes. The server has no opinion about what your first three columns should be called; whatever creates the board decides.

The board's body

A board carries a document of its own, above the grid. It is the same editor a page has. It is for the thing a column heading cannot say: what this board is for, how it is run, what "Done" means here.

Cards can be embedded into that body, so a paragraph can point at the card it is about and the card stays a card.

Comments on the board's body are not built. Comments on cards are.

Reading a board

A board is read in one request, grouped:

GET /api/v1/workspaces/{workspaceId}/boards/{boardId}/cards

The response is groups of (column × lane), each with a window of cards, a cursor of its own and a total count. That shape is the point: a board with ten thousand cards has to draw the top of every column without reading every card, and paginating a board as one flat list cannot do that. windowSize sets how many cards per group.

filters narrows the read to matching cards: a JSON array of conditions {"fieldId", "op", "value"}, the same as a database view's filters (eq, ne, contains, is_empty, is_not_empty, and gt, gte, lt, lte for a number or a date, where a date compares whole days), at most 20. On a checkbox, eq false (and ne true) also matches a card whose box was never touched. match=any lets a card through when one condition holds; the default all needs every one. The filter applies before the windows, so each group's cards, cursor and total count only matching cards. A cursor does not remember the filter: send the same filters with it. A field id the workspace does not have is refused with validation_failed.

Two things a reader should expect:

  • An empty board has no groups, not one empty group per column. Groups come from cards.
  • There is a group with no column: the cards that have never been placed. A row added to the board's backing database through the generic row API arrives there. Without it those cards would exist and be unreachable.

Board reads are viewer-dependent. A card whose page you may not read is left out entirely rather than shown as a stub, so counts and cursors differ per person. That is the same rule the rest of the platform follows: "you cannot see it" and "it is not there" look alike on purpose.

Templates

A template is a board's shape: its columns, its lanes, its fields and which fields the cards show. It holds no cards and no automations.

Choosing one. The dialog for a new board offers an empty board and the templates, ours first. The board is made with the template's columns, lanes and fields in one step, and remembers which template and version it came from.

Two kinds. The templates that come with the product are the same in every workspace and cannot be changed. Use "Duplicate" to get a copy you can edit. A workspace's own templates are made by its admins and the owner with "Save as template" on a board, which takes the board's current shape, and can be renamed, replaced from a board and deleted by them. Everyone else in the workspace can choose them. A field type a template cannot carry (formulas, relations) and the column status are left out when you save, and the dialog says which. Settings has a "Board templates" section that lists them all; there the admins and the owner duplicate a template (the copy is called " (copy)"), rename it, change its description, update it from a board (its version rises) and delete it. Boards made from a deleted template keep what they have.

Applying one to a board that exists. "Apply template" first shows what it would add: the columns, lanes, fields, options and shown fields the board lacks. Confirming adds exactly that. Nothing is renamed, moved or deleted, and no field the cards show today is hidden. A column the board has in another spelling ("in-arbeit" for "In Arbeit") counts as present. Applying twice adds nothing the second time. If the board changed after you opened the preview, nothing is applied and you see the preview again.

Fields. A field whose key exists in the workspace with the same type is used, not made again. A key that exists with another type is left alone: the preview names it, everything else is still added, and no second field is made next to it. Fields are offered to the board itself, so other boards stay as they are. Making a field that does not exist yet is an admin's work: when a member applies a template, the columns and lanes are added and the preview names the fields an admin still has to make.

Newer versions. A workspace template that is changed later is not offered to the boards made from it. A newer version of a built-in template is: a board made from it shows that the template has something new, with the same preview, and nothing changes until you confirm.

Permissions

  • Listing and reading a board needs read on its collection.
  • Creating one needs edit on the collection.
  • Changing a board (its title, icon, columns, lanes) needs edit on the board.
  • Deleting one needs full. It goes to the trash, and takes its backing database out of reach with it.

Moving a card is governed by the board, not by the card's page. Someone with edit on the board can drag a card whose page they cannot read, because they are changing where a card sits, not what it says. Opening that card still needs read on the page, and writing in it still needs edit.

That split is what makes a board usable in a team where not everything is readable by everyone.

Undo

Moving a card, removing it from a board, moving a card or a board to the trash and deleting a column or a lane can be taken back. After each one a message at the bottom of the screen offers Undo. ⌘Z (Ctrl+Z on Windows and Linux) undoes the last of these actions, and ⌘⇧Z (Ctrl+Shift+Z) redoes it. While you are typing in a text field or in a card, ⌘Z undoes the text instead.

  • Undo remembers your own last 50 actions in this browser tab. A reload or a switch to another workspace starts empty.
  • The question before a delete still comes; undo is the way back afterwards.
  • A deleted column comes back with its name, icon and place, and with the cards that were loaded in it. A deleted lane comes back the same way, and its loaded cards go back into it in their columns.
  • If someone else changed the card, column, lane or board in the meantime, nothing is put back and the message says so.
  • Field values and text are not part of this undo.

Filtering a board

Filter, beside the board's View button, shows only the cards that match. Pick a field, a comparison and a value; add more conditions and choose whether a card has to meet all of them or any one. Every field of the workspace can be used, of every type.

The comparisons depend on the field's type. Text and URL fields offer is, is not, contains, is empty and is not empty; a checkbox offers is checked and is not checked; a number also offers greater than, at least, less than and at most; a date also offers after, on or after, before and on or before, counted in whole days; every other type offers is, is not, is empty and is not empty. Is not checked includes the cards whose box was never touched. A number is typed into a field that only takes digits.

The matching cards stay in their columns and lanes, and each column counts only the matching cards. Dragging a card works as usual. A card whose value you change so that it no longer matches leaves the filtered board.

The filter is part of the board's address and is not saved. Copy the address to send someone the filtered board; reload the board without it and every card is back. Nobody else sees your filter unless you send them the link. Clear filter ends it.

Automations

A board can create cards by itself, on a schedule. Open the board's ⋯ menu and choose Automations…; anyone who may change the board may manage its rules.

A rule says when (daily, on chosen weekdays, or on a day of the month, at a time in a time zone) and what: a card title, optionally a text, and the column and lane the card goes into. Title and text may use placeholders that are filled in for each run: {date}, {week} (calendar week), {month} and {year}, or in German {datum}, {woche}, {monat} and {jahr}. The form shows the next five runs before you save.

  • Run now creates a card at once, independent of the schedule.
  • Only when the previous card is done skips a run while the card the rule created last is still on the board and not in the last column.
  • Pause stops a rule; Resume schedules it again from now.
  • History lists what each run did: created a card, skipped, paused or failed.

A rule acts as the person who created it. Each scheduled run creates at most one card, and if the service was down at that time, the missed run is made up once. If the rule's column or lane is deleted, the rule pauses itself and says so; it can be resumed once it points at a column that exists. A board holds up to 20 rules. Rules can also be managed by an assistant through the MCP server.

A board is not a database view

If you know typed databases with saved views: a board is not one of those with a kanban layout bolted on. It is its own kind of document, sibling to a page, with its own body and its own configuration. Behind its cards sits a database the board creates and manages for itself, but the grid belongs to the board, not to a view.

What a board cannot do

  • No WIP limits. Nothing counts the cards in a column against a maximum.
  • No sorting. A board is always in board order, the order cards were placed in. There is no "sort by priority". Filters exist, see above.
  • No card templates outside an automation, no card covers, no public share link.
  • No import from another tool.

Every one of those is a decision on record rather than an oversight, and none of them is close.