Karten

Eine Karte ist eine Seite. Kein seitenähnliches Objekt, kein Ticket mit Beschreibungsfeld — dieselbe Art Dokument, aus der die ganze Plattform besteht, nur eben 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;
• Volltextsuche;
• Workspace-Felder — dasselbe Feld, einmal fürs ganze Unternehmen definiert, statt eines eigenen Felds je Board;
• 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.

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.

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 — 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 — was zugleich dafür sorgt, 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 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 — nur über die Suche erreichbar und damit praktisch verloren. 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 — 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.

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.

Was fehlt

• Kartenbilder — kein Bild auf der Vorderseite einer Karte.
• Filtern und Sortieren — ein Board zeigt jede Karte, die Sie lesen dürfen, in Board-Reihenfolge.
• Ö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 Wiki-Seite in einem Board, keine Karte in einer Wiki-Seite, keine Suche über Produkte hinweg.