Tecto docs
tectoapp.io

Karten

Eine Karte ist eine Seite. Kein seitenähnliches Objekt, kein Ticket mit Beschreibungsfeld. Sie ist dieselbe Art Dokument, aus der die ganze Plattform besteht, nur auf einem Board.

Alles, was daraus folgt, gibt es umsonst, weil nichts davon für Karten noch einmal gebaut wurde:

  • ein Textkörper, in den man mit dem vollen Editor schreibt;
  • Kommentare und Erwähnungen;
  • Versionsverlauf und Papierkorb;
  • Aktivität: wer die Karte angelegt, umbenannt, ein Feld geändert (mit altem und neuem Wert) oder in eine andere Spalte verschoben hat, unter dem Knopf Aktivität oben in der Karte. Ein Punkt auf diesem Knopf und ein Punkt vor dem Titel der Karte auf dem Board heißen: Jemand anderes hat die Karte geändert oder kommentiert, seit Sie ihre Aktivität zuletzt geöffnet haben. Eigene Änderungen setzen ihn nie, das Öffnen der Aktivität entfernt ihn;
  • Volltextsuche;
  • Workspace-Felder: dasselbe Feld, einmal fürs ganze Unternehmen definiert, statt eines eigenen Felds je Board. Ein Feld steht an einer Karte, sobald es einen Wert hat oder über + hinzugefügt wird. Angeboten wird ein Feld für den ganzen Workspace (Einstellungen → Felder), für eine Sammlung (ihre Einstellungen) oder für ein Board (Ansicht → Felder dieses Boards am Board); mit Immer anzeigen dort zeigt jede Karte, die es erreicht, das Feld, auch leer. Die offene Karte gruppiert ihre Felder danach, wo sie angeboten werden: Vom Workspace, Von der Sammlung, Vom Board „…“. Was eine Karte auf dem Board selbst zeigt, wählt man unter Ansicht → Auf dem Board sichtbar;
  • Ereignisse und Webhooks.

Der Titel einer Karte ist der Titel ihrer Seite. Der Textkörper einer Karte ist der Textkörper ihrer Seite. Eine Karte als Markdown zu lesen heißt, die Seite als Markdown zu lesen:

curl "$BASE/api/v1/workspaces/$WS/pages/$CARD?format=markdown" \
  -H "Authorization: Bearer $TOKEN"

Einen kartenförmigen Endpunkt dafür gibt es nicht, und es braucht ihn nicht.

Kartennummern

Jede Karte hat eine Nummer, in der geöffneten Karte als #42 über dem Titel. Die Nummern zählen je Workspace in der Reihenfolge hoch, in der Karten entstehen, und eine Karte behält ihre Nummer für immer: Verschieben, ein zweites Board oder Wiederherstellen aus dem Papierkorb ändern sie nicht, und keine andere Karte bekommt sie je.

  • Ein Klick auf die Nummer kopiert den Link zur Karte.
  • Ansicht auf einem Board hat den Schalter Kartennummer, der die Nummern auf allen seinen Karten zeigt. Er gilt für das Board, für alle.
  • Die Adresse einer geöffneten Karte beginnt mit der Nummer, …/c/42-onboarding-mail-neu-schreiben-<id>. Ein kurzes …/c/42 öffnet dieselbe Karte.
  • Eine Suche nach #42 oder 42 zeigt Karte 42 zuerst.

Über die API trägt eine Karte im gruppierten Lesen number, eine Seite, die eine Karte ist, cardNumber, und GET /api/v1/workspaces/{workspaceId}/cards/42 antwortet mit der pageId der Karte.

Eine Karte, mehrere Boards

Eine Karte kann auf mehr als einem Board liegen, und es ist dieselbe Karte: keine Kopie, kein Link, kein Spiegel, der abgeglichen wird. Ändern Sie ihren Text auf einem Board, sagt die Karte auf dem anderen bereits dasselbe, weil es sie nur einmal gibt.

Nicht geteilt wird, wo sie liegt. Jedes Board hält für diese Karte seine eigene Spalte, Lane und Position. Dieselbe Arbeit kann auf dem Teamboard „In Prüfung" sein und auf dem Roadmap-Board „Dieses Quartal", ohne dass eine Platzierung die andere stört.

Die geöffnete Karte zeigt jedes Board, auf dem sie liegt, als eigene Zeile Status, darunter die Lane, wenn das Board Lanes hat. Jede Zeile bietet die üblichen Aktionen: Ein Klick auf den Board-Namen öffnet die Karte dort, Spalte und Lane lassen sich ändern, die Karte lässt sich nur auf diesem Board archivieren oder von diesem Board entfernen. Zu Board hinzufügen … unter den Zeilen legt die Karte zusätzlich auf ein weiteres Board, aus jeder Sammlung, die Sie bearbeiten dürfen: erst das Board wählen, dann Spalte und Lane.

Das ist der Mechanismus hinter dem Versprechen: Eine Karte gehört zur Arbeit, und Boards sind Sichten auf die Arbeit.

Eine Karte platzieren

Eine Karte kommt auf zwei Wegen auf ein Board:

Eine neue anlegen. Mit Titel, Spalte, wahlweise Lane:

curl -X POST "$BASE/api/v1/workspaces/$WS/boards/$BOARD/cards" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Onboarding-Mail neu schreiben", "columnId": "…", "laneId": "…" }'

Eine bestehende Seite anhängen. Schicken Sie pageId statt title. So kommt eine Karte auf ein zweites Board, und so wird aus einer gewöhnlichen Seite eine Karte.

Anhängen braucht edit auf dem Board und edit auf der Seite, denn Sie ändern die Zugehörigkeiten der Seite, und das ist eine Änderung an der Seite.

Die Position geben Sie über einen Nachbarn an: beforeId oder afterId. Lassen Sie beides weg, kommt die Karte ans Ende der Spalte. Das sorgt zugleich dafür, dass die erste Karte in einer leeren Spalte ohne Sonderfall funktioniert.

Eine Karte verschieben

POST /api/v1/workspaces/{workspaceId}/boards/{boardId}/cards/{pageId}/move

Ein transaktionaler Aufruf mit Zielspalte, Lane und einem Nachbarn. Er ändert nur die Platzierung auf diesem Board.

Kollidierende Positionen werden geheilt, nicht gestapelt: Zwei Clients, die im selben Moment eine Karte an dieselbe Stelle legen, enden mit zwei verschiedenen Positionen, nicht mit zwei Karten, die dieselbe beanspruchen.

Verschieben braucht edit auf dem Board. Siehe Rechte. Das ist Absicht, und genau das erlaubt einer Projektleitung, ein Board zu führen, dessen Inhalte sie nicht durchweg lesen darf.

Eine Karte archivieren

Öffnen Sie auf dem Board das ⋯-Menü einer Karte und wählen Sie Archivieren. Die Karte verschwindet vom Board und aus den Zahlen der Spalten, bleibt aber auf dem Board, in ihrer Spalte und Lane. Das ⋯-Menü einer Spalte hat Alle Karten dieser Spalte archivieren, zum Beispiel für „Erledigt“ am Ende eines Sprints. Eine geöffnete Karte hat Archivieren auch in ihrem eigenen ⋯-Menü; nach dem Archivieren schließt sie sich.

Das Tastenkürzel ist ⌘⇧E (Strg+Umschalt+E unter Windows und Linux): In einer geöffneten Karte archiviert es diese Karte, auf dem Board die Karte, auf der die Tastatur steht, sonst die Karte unter dem Mauszeiger. Beide Menüs zeigen es neben Archivieren.

Liegt die Karte auch auf anderen Boards, fragt Tecto nach: Nur auf diesem Board oder Auf allen Boards. Boards, die Sie nicht bearbeiten dürfen, behalten die Karte unverändert.

Solange ein Board archivierte Karten hat, steht im Kopf Archivierte anzeigen (N ausgeblendet). Eingeschaltet erscheinen die archivierten Karten blasser in ihren Spalten, und ihr ⋯-Menü hat Aus dem Archiv holen. Das holt die Karte nur auf diesem Board zurück. Der Schalter wird je Board auf diesem Gerät gespeichert.

Archivieren und Zurückholen lassen sich rückgängig machen: Die Meldung danach hat Rückgängig, und ⌘Z (Strg+Z) tut dasselbe. Eine auf allen Boards archivierte Karte kommt auf jedem Board zurück, auf dem sie liegt.

Über die API:

POST /api/v1/workspaces/{workspaceId}/boards/{boardId}/archive
{"pageIds": ["{pageId}"]}          auf diesem Board archivieren
{"columnId": "{columnId}"}         alle Karten einer Spalte
{"pageIds": [...], "allBoards": true}
{"pageIds": [...], "archived": false}   zurückholen, nur dieses Board

dryRun: true ändert nichts und meldet, wie viele andere Boards betroffen sind. Die Kartenabfrage lässt archivierte Karten weg und zählt sie in archivedCount; ?archived=include oder ?archived=only liefert sie mit.

Eine Karte vom Board nehmen

DELETE /api/v1/workspaces/{workspaceId}/boards/{boardId}/cards/{pageId}

Die Karte verlässt das Board. Die Seite bleibt: Sie ist weiterhin im Workspace, weiterhin auffindbar, weiterhin auf jedem anderen Board, auf dem sie liegt.

Eine Weigerung sollten Sie kennen: Ist dieses Board das letzte Zuhause der Seite, scheitert der Aufruf mit 409 und dem Code needs-new-home. Die letzte Zugehörigkeit zu entfernen ließe eine Seite zurück, auf die nichts zeigt, die nur über die Suche erreichbar und damit praktisch verloren wäre. Legen Sie sie erst auf ein anderes Board, oder werfen Sie die Seite selbst weg, falls Sie das meinten.

Sagen Sie gleich, wohin sie soll, und es gibt nichts zu umgehen:

DELETE …/boards/{boardId}/cards/{pageId}?newHomeBoardId={anderesBoardId}

Das andere Board muss eines sein, auf dem die Karte bereits liegt, in derselben Sammlung. Die Karte zieht dorthin um und verlässt dieses Board in einem Schritt. Genau das macht die Schaltfläche „auf ein anderes Board verschieben". Nehmen Sie diesen Weg, statt die Seite zwischendurch irgendwo zu parken: Eine Karte, die kurz außerhalb jedes Boards zu Hause ist, ist kurz keine Karte, und was den Workspace liest, bekommt das mit.

Karten ohne Spalte

Eine Karte kann auf einem Board liegen und keine Spalte haben. Das passiert, wenn eine Zeile über die allgemeine Zeilen-API in die Datenbank hinter dem Board kommt, denn die weiß nichts von Spalten.

Solche Karten kommen in der gruppierten Abfrage in einer eigenen Gruppe zurück. Sie sind kein Fehlerzustand, sondern der Zustand „das hier gibt es, und niemand hat gesagt, wo". Verschieben Sie sie wie jede andere Karte.

Spalten sind keine Felder

Eine Spalte ist keine Auswahloption, und eine Lane auch nicht. Beide leben am Board, in dessen eigener Konfiguration, und die Platzierung einer Karte wird je Board gespeichert statt als Wert an der Seite.

Genau diese Unterscheidung erlaubt es, dass dieselbe Karte auf zwei Boards in verschiedenen Spalten liegt: Ein Feldwert wäre eine Eigenschaft der Seite und könnte immer nur einen Wert haben. Sie sorgt außerdem dafür, dass die Stationen eines Boards nie als Spalte in einer Datenbankansicht auftauchen und nie mit einem Status-Feld kollidieren, das jemand für den Workspace definiert hat.

Die geöffnete Karte zeigt ihre Platzierung trotzdem bei den Feldern: je Board eine Zeile Status, deren Menü die Karte in eine andere Spalte dieses Boards verschiebt, und auf einem Board mit Lanes darunter eine Zeile Lane, deren Menü die Karte in eine andere Lane (oder in die Zeile ohne Lane) verschiebt und die Spalte beibehält. Beides ändert nur dieses eine Board.

Eine andere Karte oder eine Seite anheften

Im Karten-Text /karte tippen und eine Karte wählen: Sie erscheint als kleiner Block mit Symbol, Titel, Board, Spalte und den Kartenfeldern, die einen Wert haben. Ein Klick öffnet die Karte über ihrem eigenen Board.

Eine Seite außerhalb der Boards heften Sie an, indem Sie ihre Adresse in den Karten-Text einfügen: Aus dem Link wird ein Block mit Symbol und Titel der Seite, und ein Klick öffnet die Seite dort, wo sie liegt. Wie beim Projekt (unten) ist nur die Verknüpfung gespeichert, die Worte werden beim Zeichnen geholt, und eine Seite, die Sie nicht sehen dürfen, zeigt „Diese Karte ist nicht verfügbar.“ Umgekehrt geht es auch: Die Adresse einer Karte, in eine solche Seite eingefügt, zeigt dort die Karte mit Board und Spalte.

Das Projekt benennen, zu dem eine Karte gehört

Der Karten-Text nimmt einen Projekt-Block: /projekt tippen und dann entweder Link oder Id eines bestehenden Projekts einfügen oder einen Namen tippen, dann wird eins angelegt.

Der Block zeigt den Namen des Projekts und verlinkt darauf. Gespeichert ist an der Karte nur die Verknüpfung; der Name wird geholt, wenn der Block gezeichnet wird. Eine Karte, deren Projekt Sie nicht sehen dürfen (oder dessen Produkt in diesem Workspace nicht aktiv ist), zeigt darum einen Link ohne Namen. Kaputt ist daran nichts; eine Kollegin sieht ihn möglicherweise sehr wohl.

Zwei Dinge ist das bewusst nicht:

  • keine Suche. Von hier aus lassen sich die vorhandenen Projekte nicht durchblättern; Sie fügen die Adresse eines offenen ein oder legen eins an. Der Block ist eine Verbindung zwischen zwei Orten, kein Fenster in den anderen.
  • keine Kopie. Die Aufgaben des Projekts stehen nicht auf der Karte und sind von ihr aus nicht bearbeitbar. Das kann kommen; heute benennt der Block die Arbeit und bringt Sie hin.

Beide Hälften müssen in diesem Workspace aktiv sein, damit der Block funktioniert. Beim Anlegen wird deutlich gesagt, wenn nicht.

Rückfragen an einer Karte

Ein Agent, der an einer Karte arbeitet, kann dort eine Rückfrage stellen (ask_on_card, siehe MCP-Server). Die Rückfrage steht oben in der Karte, unter dem Titel: die Frage, falls vorhanden eine Zeile Hintergrund, und ein Knopf je Option. Die empfohlene Option steht vorn und trägt „Empfehlung". Hat der Agent es erlaubt, nimmt ein Feld unter den Knöpfen eine Antwort mit eigenen Worten an.

  • Antworten braucht das Recht, die Karte zu bearbeiten. Ein Knopf oder ein gesendeter Text beantwortet die Rückfrage; der Block zeigt danach „Beantwortet:" mit der Antwort, wer sie gab und wann. Eine Antwort lässt sich nicht ändern; eine neue Entscheidung ist eine neue Rückfrage.
  • Eine Option kann die Karte verschieben. Hat der Agent einer Option eine Spalte gegeben, nennt der Knopf sie („→ Erledigt"), und die Antwort damit legt die Karte dort ab, in ihrer Lane. Das braucht auch das Recht, das Board zu bearbeiten.
  • Auf dem Board trägt eine Karte mit offener Rückfrage das Kennzeichen „Frage offen", bis sie beantwortet oder zurückgezogen ist.
  • Ohne Bearbeitungsrecht sehen Sie die Frage und ihre Optionen, ohne Knöpfe.

Der Agent liest die Antwort über list_card_questions, get_card oder get_my_work. Webhooks können das Ereignis „Rückfragen" abonnieren.

Chat mit dem Agenten einer Karte

Eine Karte hat einen Agenten, wenn eines ihrer Personenfelder einen Bot nennt, zum Beispiel den Bot in „Zuständig". Der erste solche Bot, in der Reihenfolge, in der die Felder angelegt wurden, ist der Agent der Karte. Auf einer solchen Karte öffnet „Chat mit Agent" einen Chat unter den Rückfragen.

  • Schreiben braucht das Recht, die Karte zu bearbeiten. Enter sendet, Umschalt+Enter beginnt eine neue Zeile. Eine Nachricht zeigt „wartet auf den Agenten", bis der Agent antwortet; die Antwort erscheint unter seinem Namen, ohne neu zu laden.
  • Eine Nachricht nach der anderen. Solange Ihre Nachricht wartet, sagt das Eingabefeld das; Sie schreiben wieder, sobald der Agent geantwortet hat.
  • Manche Agenten antworten nur Admins. Gehört der Bot zu einem Agenten, den der Workspace selbst betreibt und verwaltet, braucht Schreiben das Recht, Agenten zu verwalten, denn jede Nachricht kostet das Kontingent dieses Agenten. Der Chat erscheint nur bei einem Agenten, der in einem Chat antwortet und die Karte lesen darf.
  • Keine Antwort innerhalb einer Stunde markiert die Nachricht als „nicht beantwortet" mit „Der Agent hat nicht geantwortet."; schreiben Sie erneut, um es noch einmal zu versuchen.
  • Der Agent antwortet im Zusammenhang der Karte. Er kann auch sagen, dass er nicht antworten konnte; die Nachricht zeigt dann „nicht beantwortet", und der Grund folgt. Schreiben Sie erneut, um es noch einmal zu versuchen.
  • Der Chat bleibt an der Karte. Schließen Sie die Karte und öffnen Sie sie wieder, ist der Chat noch da. Er bleibt auch, wenn der Agent wechselt; eine Karte ohne Agenten zeigt den Chat ohne Eingabefeld.
  • Ohne Bearbeitungsrecht lesen Sie den Chat, ohne Knopf und ohne Eingabefeld.

Ein Agent liest die Nachrichten, die auf ihn warten, über get_my_work und antwortet mit reply_in_card_chat (siehe MCP-Server). Webhooks können das Ereignis „Chat mit dem Agenten" abonnieren.

Was fehlt

  • Kartenbilder: kein Bild auf der Vorderseite einer Karte.
  • Sortieren: Ein Board zeigt seine Karten in Board-Reihenfolge. Filtern nach Feldwerten geht, siehe Boards.
  • Öffentliche Freigabelinks für ein Board. Die Seite einer Karte lässt sich auf dem gewöhnlichen Weg freigeben, das Board nicht.
  • Kommentare am Textkörper des Boards. Kommentare an Karten funktionieren.
  • Produktübergreifendes Einbetten: keine Suche über Produkte hinweg, und eine angeheftete Seite zeigt ihren Titel, nicht ihren Inhalt.