Zum Inhalt springen

Views ​

Eine View ist eine gespeicherte Liste von Work Items: ein Filter und eine Art, das Gefundene zu zeigen. Views gehören dem ganzen Team und gelten projektübergreifend; das Projekt ist ein Filter wie jeder andere. Jede Person sieht in einer View nur Items aus Projekten, die sie sehen darf; dieselbe View kann Mara also mehr Items zeigen als Ida.

Jede Item-Liste in werkbuch funktioniert gleich, gespeichert oder nicht: Meine Items, die Liste eines Projekts und jede View haben die Filterleiste, das Menü Anzeige und die vier Layouts. Filtern, Sortieren, Gruppieren und Blättern macht der Server; der Browser zeigt nur, was zurückkommt.

Views und eingebaute Listen ​

Vier Listen sind eingebaut und lassen sich nicht löschen:

ListeAdresseEnthältBeginnt mit
Meine Items: Zugewiesen/my-itemsOffene Items, die dir zugewiesen sindNach Kategorie gruppiert, nach Priorität sortiert
Meine Items: Erstellt/createdItems, die du angelegt hastNach Kategorie gruppiert, neueste zuerst
Meine Items: Beobachtet/subscribedItems, die du beobachtestNach Kategorie gruppiert, zuletzt geänderte zuerst
Projekt/projects/WEBDie Items des ProjektsNach Status gruppiert, manuelle Reihenfolge

Eine eingebaute Liste ist eine View, die nie gespeichert wird. Du kannst sie filtern und ihre Anzeige ändern; als ungespeicherte Änderung zählt nur ein anderer Filter. Als neue View speichern … (in der Leiste der ungespeicherten Änderungen oder am Ende von Anzeige) macht aus dem, was du siehst, eine View und behält, wofür die Liste steht, als Bedingung: „Projekt ist Website“, „Assignee ist ich“, „Ersteller ist ich“ oder „Beobachtet ist ja“.

Gespeicherte Views stehen unter Views (/views) und unter /views/<id>. Ein Stern legt eine View in die Seitenleiste, in deiner eigenen Reihenfolge; wird eine View gelöscht, verschwindet sie aus allen Seitenleisten.

Die Übersicht der Views des Teams, je mit Layout und Ersteller

Rechte ​

AktionWer
Eine View lesenJedes aktive Konto
Eine View anlegen, als neue View speichern, duplizierenOrg-Admins und Org-Member
Eine View ändern oder löschenWer sie angelegt hat, und Org-Admins

Eine View hat einen Namen (bis 60 Zeichen), ein Icon (eins aus der Liste im Dialog oder genau ein Emoji), einen Filter und eine Anzeige. Speichern ersetzt die ganze View; speichern zwei Personen dieselbe View gleichzeitig, gewinnt die zweite ganz. Wer eine View nicht ändern darf, kann trotzdem mit Als neue View speichern … oder Duplizieren eine Kopie anlegen.

Ein Filter darf ein Projekt, eine Person oder ein Item nennen, das der Leser nicht sieht. werkbuch behält die Bedingung, wie sie ist, und zeigt sie als „Verborgenes Projekt“, „Unbekannte Person“ und so weiter; sie trifft nur, was der Leser sieht.

Layouts ​

1 bis 4 wechseln zwischen den Layouts; der Schalter steht auch im Kopf jeder Liste. Das Layout gehört zur Anzeige und zu einer gespeicherten View.

Liste ​

Items in Gruppen, die sich einklappen lassen, die Felder der Anzeige als Chips hinter dem Titel, Kind-Items eingerückt unter ihrem Epic. Jede Gruppe zeigt die Zahl ihrer Items vom Server und lädt ihre Items seitenweise beim Scrollen; eingeklappte oder weit entfernte Gruppen laden nichts.

Meine Items als Liste, nach Kategorie gruppiert, weil die Items in zwei Workflows liegen

Board ​

Jede Gruppe ist eine Spalte, leere eingeschlossen. Eine Karte ziehen oder shift+left und shift+right ändert das gruppierte Feld:

  • Status: nur entlang der Übergänge des Workflows. Ein Zug, den der Workflow nicht erlaubt, bleibt in seiner Spalte, und ein Toast sagt warum; in einen geschlossenen Status fragt werkbuch nach der Resolution.
  • Kategorie: Das Item bekommt den ersten Status dieser Kategorie in seinem eigenen Workflow, in den es wechseln darf; gibt es keinen, sagt es der Toast.
  • Priorität und Assignee: der neue Wert; eine Person, die nicht Mitglied des Projekts ist, kann das Item nicht übernehmen.
  • Typ, Projekt, Eltern-Item: Karten bleiben in ihrer Spalte. Label: Ein nach Label gruppiertes Board ist nicht ziehbar, weil ein Item in der Spalte jedes seiner Labels steht.

Die Reihenfolge in einer Spalte folgt der Sortierung der Anzeige. Mit der Sortierung Manuell verschieben alt+up und alt+down oder Ziehen innerhalb der Spalte eine Karte zwischen ihre Nachbarn; mit jeder anderen Sortierung sagt werkbuch, dass die Reihenfolge der Sortierung folgt. Ist zwischen zwei Nachbarn kein Platz mehr, verteilt werkbuch zuerst die Ordnung des Projekts der Karte neu (die Reihenfolge bleibt, die Ränge werden wieder kurz, siehe Items von Hand ordnen) und verschiebt die Karte dann; Züge anderer Karten des Projekts warten darauf. Die Karte bleibt, wo sie war, und ein Toast sagt warum: Es ist kein Platz mehr da, wenn die beiden Nachbarn zu einem anderen Projekt gehören. Die Ordnung hat sich geändert, wenn inzwischen andere Karten zwischen den beiden Nachbarn stehen (in einer Liste mehrerer Projekte nach der Neuverteilung oder nach einer anderen Änderung der Spalte); dann verschiebst du die Karte von der neuen Ordnung aus noch einmal. Die neue Ordnung ist noch nicht geladen, wenn sie länger als fünf Sekunden lädt. Einen Zug, den der Server ablehnt, nimmt werkbuch zurück, und die Zahlen der Spalten stimmen wieder. + im Kopf einer Spalte legt ein Item an, das zur Spalte passt.

Das Board eines Projekts, die Work Items in einer Spalte je Status

Tabelle ​

Eine Zeile je Item, eine Spalte je Feld der Anzeige, Properties eingeschlossen. Der Kopf und die erste Spalte (Key und Titel) bleiben beim Scrollen stehen. Zellen lassen sich direkt ändern: enter öffnet den Editor einer Zelle, escape schließt ihn. Zellen von Properties, die der Typ des Items nicht hat, zeigen „—“. Projekt, angelegt und geändert lassen sich hier nicht ändern.

Eine View als Tabelle, mit den Properties Kunde und Aufwand als Spalten

Timeline ​

Die Timeline zeigt die Epics der Liste (Items eines Typs mit Häkchen „Epic“), nach Projekt gruppiert und nach Start-Date geordnet, egal was Gruppierung und Sortierung der Anzeige sagen. Ein Balken reicht vom Start- bis zum Due-Date und ist nach dem Anteil geschlossener Kind-Items gefüllt. Einen Balken ziehen verschiebt ihn, seine Enden ziehen ändert ein Datum. Epics ohne Daten stehen in der Seitenliste Ohne Datum; zieh sie auf die Achse oder nimm Ab heute einplanen (zwei Wochen ab heute). Der Zoom (Woche, Monat, Quartal) steht als ?zoom=week bzw. ?zoom=quarter in der Adresse; Heute scrollt zu heute.

Die Roadmap als Timeline: drei Epics mit ihrem Fortschritt und der Marker für heute

Gruppierung ​

GruppierungGruppen, in dieser ReihenfolgeLeere Gruppen
StatusDie Reihenfolge des WorkflowsAlle Status des Workflows
KategorieBacklog, Unstarted, Started, Completed, CanceledAlle fünf
AssigneePersonen vor Bots, nach Name; „Nicht zugewiesen“ zuletzt„Nicht zugewiesen“ immer
PrioritätUrgent, High, Medium, Low, NoneAlle fünf
TypDie Reihenfolge des KatalogsDie aktivierten Typen des einen Projekts, das der Filter nennt, sonst keine
LabelNach Name; „Ohne Label“ zuletzt„Ohne Label“ immer
ProjektNach NameDas eine Projekt, das der Filter nennt
Eltern-ItemNach Key; „Ohne Eltern-Item“ zuletzt„Ohne Eltern-Item“ immer
KeineEine Gruppe—

Nach Status gruppieren geht nur, solange alle gefundenen Items einen Workflow teilen; sonst gruppiert werkbuch nach Kategorie und sagt es über der Liste. Ein Item mit zwei Labels steht in beiden Label-Gruppen und zählt in der Gesamtzahl einmal.

Sortierung ​

SortierungÜber die API (sort.field)Reihenfolge (aufsteigend)
ManuellrankDie Reihenfolge, die du Items durch Ziehen gibst (Rang)
PrioritätpriorityUrgent zuerst
Due-Date, Start-Datedue_date, start_dateFrüheste zuerst
Angelegt, geändertcreated_at, updated_atÄlteste zuerst
KeykeyKennung des Projekts, dann die Nummer (A2-1 vor A10-1, WEB-9 vor WEB-10)
Kategoriestate_categoryBacklog zuerst
Eine Property (Zahl, Datum, Text oder Adresse)property:<key>Kleinste, früheste oder alphabetisch zuerst (Item 9 vor Item 10)

Items ohne Wert stehen in beiden Richtungen am Ende; gleiche Werte behalten die manuelle Reihenfolge. Texte und Kennungen werden ohne Rücksicht auf Groß- und Kleinschreibung und Akzente verglichen, Zahlen darin als Zahlen: Item 9 steht vor Item 10, Version 1.2 vor Version 1.10. Führende Nullen zählen nicht (Item 007 und Item 7 sind gleich), und nur die Ziffern 0 bis 9 sind Zahlen.

Filter ​

Ein Filter ist eine Liste von Bedingungen, die alle gelten müssen. Jede Bedingung hat ein Feld, einen Operator und bei den meisten Operatoren einen Wert. In der Oberfläche fügt f oder Filter eine Bedingung hinzu, und / sucht im Titel; über die API ist ein Filter überall JSON in derselben Form:

json
{
  "version": 1,
  "conditions": [
    { "field": "assignee", "op": "is", "value": "me" },
    { "field": "state_category", "op": "in", "value": ["unstarted", "started"] },
    { "field": "due_date", "op": "before", "value": { "relative": "+7d" } },
    { "field": "property:customer", "op": "is", "value": "01m6dd2rc7syc8r8s7q2my2j51" }
  ]
}

Ein Filter hat bis zu 50 Bedingungen, eine Liste bis zu 100 Werte, ein Text bis zu 255 Zeichen. Ein unbekanntes Feld, ein Operator, den das Feld nicht kennt, oder ein Wert falscher Form wird abgelehnt (422 an filter.conditions.<n>.field, .op bzw. .value), nie still übergangen.

Felder ​

FeldArtHinweise
project, type, state, created_byIDULID; created_by auch me
assignee, parentID, darf leer seinULID; assignee auch me
state_categoryAuswahlbacklog, unstarted, started, completed, canceled
priorityAuswahlurgent, high, medium, low, none
labelListeULIDs von Labels
start_date, due_dateTagdue_date auch overdue
created_at, updated_at, closed_atZeitpunktVerglichen wird der Tag; closed_at darf leer sein
has_children, blocked, blocking, archived, epic, subscribedJa/Neinepic: ein Typ mit Häkchen „Epic“; subscribed: du beobachtest das Item
titleTextNur contains
property:<key>Nach FeldtypSiehe unten

Operatoren ​

ArtOperatoren
IDis, is_not, in, not_in; is_empty, is_not_empty, wo das Feld leer sein darf
Auswahlis, is_not, in, not_in
Listeis, is_not, in, not_in, contains, is_empty, is_not_empty
Tagis, before, after, between, is_empty, is_not_empty; overdue nur bei due_date
Zeitpunktis, before, after, between; is_empty, is_not_empty nur bei closed_at
Ja/Neinis
Textcontains; Text- und Adress-Properties auch is, is_empty, is_not_empty
Zahlis, gt, lt, between, is_empty, is_not_empty
Rich Textcontains, is_empty, is_not_empty

is und is_not nehmen einen Wert oder eine Liste, in und not_in eine Liste. Bei einem Listenfeld wie den Labels heißen is, in und contains „hat eines davon“, is_not und not_in „hat keines davon“. Ein fehlender Wert ist nie gleich, darum treffen is_not und not_in auch Items ohne Wert. before und after schließen den Tag selbst aus, between nimmt zwei Werte und schließt beide ein. overdue nimmt keinen Wert: Das Due-Date liegt vor heute, und das Item steht nicht in einem Status der Kategorie Completed oder Canceled.

Werte ​

WertBedeutung
"me"Die Person, die die Liste liest. Nur bei assignee, created_by und Personen-Properties.
"2026-11-02"Ein Tag.
"today", "this_week", "this_month"Heute, die laufende Woche, der laufende Monat.
{ "relative": "+7d" }Tage oder Wochen ab heute: -3d, +2w, bis zu fünf Ziffern.
true, falseFür Ja/Nein-Felder.
Eine ZahlFür Zahl-Properties, im Betrag unter 10²⁰.
Ein TextFür contains und is bei Texten, 1 bis 255 Zeichen.

Die dynamischen Werte gelten nur, wo das Feld sie nimmt: "today" in einer Titelsuche ist das Wort „today“. Bei einem Zeitraum wie this_week heißt is „darin“, before „vor seinem ersten Tag“ und after „nach seinem letzten Tag“.

Daten und Zeitzone ​

„Heute“, Wochen und Monate zählen in der Zeitzone der Organisation, und Wochen beginnen an dem Wochentag, den sie einstellt. Bei angelegt, geändert und geschlossen vergleicht werkbuch den Tag, auf den der Zeitpunkt in dieser Zeitzone fällt: Ein Item, das um 00:30 Uhr in Berlin angelegt wurde, gilt als an diesem Tag angelegt, auch beim Wechsel zwischen Sommer- und Winterzeit.

Properties ​

Die Operatoren einer Property folgen ihrem Feldtyp:

FeldtypArtOperatoren
Dropdown, Person (ein Wert)IDis, is_not, in, not_in, is_empty, is_not_empty
Dropdown, Person (mehrere Werte)Listeis, is_not, in, not_in, contains, is_empty, is_not_empty
DatumTagis, before, after, between, is_empty, is_not_empty
Ja/NeinJa/Neinis
ZahlZahlis, gt, lt, between, is_empty, is_not_empty
Text, AdresseTextcontains, is, is_empty, is_not_empty
Rich TextRich Textcontains, is_empty, is_not_empty

Eine Bedingung auf eine Property (property:<key>) trifft nur Items, deren Typ die Property hat, auch mit is_empty, is_not, not_in und is false. Eine Ja/Nein-Property, die nie gesetzt wurde, liest sich als „nein“. Texte werden ohne Rücksicht auf Groß- und Kleinschreibung und Akzente verglichen („uber“ findet „Über“); Rich Text wird in seinem Klartext gesucht. Wird eine Property gelöscht, behält eine gespeicherte View ihre Bedingung; sie trifft dann nichts und zeigt sich als „Unbekanntes Feld“, bis du sie entfernst.

Archivierte Items ​

Archivierte Items bleiben aus jeder Liste draußen, außer eine Bedingung auf archived fragt nach ihnen oder die Anfrage setzt include_archived. Items eines archivierten Projekts erscheinen nur, wo eine project-Bedingung mit is oder in das Projekt nennt: Die Liste eines archivierten Projekts zeigt seine offenen Items, schreibgeschützt.

Zustand in der Adresse ​

Alles, was du in einer Liste änderst, steht in ihrer Adresse, soweit es von der gespeicherten View oder der eingebauten Liste abweicht: filter (die Bedingungen als JSON), layout, group, sort (due_date:desc), fields (durch Kommas getrennt), sub (0 blendet Kind-Items aus) und in der Timeline zoom. Ein Link zeigt jemand anderem dieselbe Liste, und Neuladen behält sie. Verwerfen kehrt zum gespeicherten Stand zurück.

Tastatur ​

? zeigt alle Kürzel, die gerade gelten.

Listen ​

TastenAktion
j, k oder down, upNächstes bzw. voriges Item
shift+j, shift+k oder shift+down, shift+upAuswahl erweitern
xItem auswählen
shift+xBereich bis zum Item auswählen
mod+aAlle auswählen (lädt vorher alle Seiten)
escapeAuswahl aufheben
enterItem öffnen
spaceVorschau zeigen oder schließen
fBedingung hinzufügen
/Nach Titel filtern
1, 2, 3, 4Liste, Board, Tabelle, Timeline

Die Item-Kürzel (s Status, a zuweisen, i mir zuweisen, p Priorität, l Labels, t Typ, d Due-Date, shift+d Start-Date, shift+p Eltern-Item, mod+backspace archivieren bzw. löschen) wirken auf die Auswahl, sonst auf das Item unter dem Cursor. Sind mehrere Items ausgewählt, ändert eine Leiste über der Liste Status, Assignee, Priorität und Labels aller auf einmal und archiviert sie, wenn alle geschlossen sind. Eine Aktion gilt für eine Auswahl nur, wenn sie für jedes ausgewählte Item erlaubt ist: Sind einige archiviert oder gehören zu einem Projekt, das du nur liest (oder beim Archivieren noch offen), lässt die Leiste die Aktion weg, die Palette ebenso, und ihr Kürzel sagt warum, ohne etwas zu ändern. mod+backspace archiviert eine Auswahl nur, wenn alle Items geschlossen sind, und löscht sie nur, wenn keins geschlossen ist (offene und archivierte gleichermaßen); würde es einige archivieren und andere löschen, passiert nichts, und ein Hinweis sagt warum. Was der Server bei einem Item trotzdem ablehnt, etwa einen Übergang, den sein Workflow verbietet, nennt ein einziger Toast. e bearbeitet den Titel nur in der Vorschau und auf der Item-Seite.

Gruppenköpfe sind keine Tab-Stopps: left auf einem Item geht zum Kopf seiner Gruppe; auf einem Kopf klappt left ein, right klappt auf oder geht zum ersten Item, down und up gehen zum nächsten bzw. vorigen Kopf.

Board ​

TastenAktion
left, rightSpalte links bzw. rechts
j, k oder down, upNächste bzw. vorige Karte in der Spalte
shift+left, shift+rightKarte in die nächste Spalte verschieben, in die sie darf
alt+up, alt+downKarte nach oben bzw. unten verschieben (nur Sortierung „Manuell“)
escape beim ZiehenZiehen abbrechen

Die Befehlspalette (mod+k) bietet dieselben Züge an, solange sie möglich sind.

Tabelle ​

Die Tabelle ist ein Grid mit einem Tab-Stopp:

TastenAktion
left, rightVorige bzw. nächste Spalte
up, downVorige bzw. nächste Zeile; mit shift erweitern sie die Auswahl
home, endErste bzw. letzte Spalte; mit mod die erste bzw. letzte Zeile
enterEditor der Zelle öffnen (in der ersten Spalte: das Item)
escapeEditor schließen

j, k, x und space wirken wie in der Liste, ebenso die Tasten der Gruppenköpfe.

Timeline ​

TastenAktion
shift+left, shift+rightEpic um eine Einheit des Zooms (Tag, Woche, Monat) früher bzw. später; shift+right plant ein Epic ohne Datum ab heute ein
alt+left, alt+rightEpic kürzer bzw. länger machen (sein Due-Date)

Züge werden nach einer kurzen Pause gespeichert; escape beim Ziehen setzt den Balken zurück. Die Befehlspalette (mod+k) bietet dieselben Züge an, solange sie möglich sind.

REST ​

Lesen braucht ein Token mit read. Die drei Anfragen unten, die mit POST lesen (query, groups, counts), sind ebenfalls Lesezugriffe: Ein Token mit nur read darf sie schicken. Views anlegen, ändern und löschen braucht write. Meldungen kommen in der Sprache des Kontos. Tokens, Fehler, Seiten und Grenzen erklärt die Seite REST-API; die Liste der Views nimmt filter[created_by], filter[name] und sort wie jede Liste dort.

AnfrageAntwort
GET /api/v1/work-itemsEine Seite Items: view, filter[…] (Kurzform), sort, show_sub_items (1 oder 0, standardmäßig wie die View, sonst 1), include_archived, lean, cursor, per_page
POST /api/v1/work-items/queryEine Seite Items für einen Filter im Body
POST /api/v1/work-items/groupsDie Gruppen einer Gruppierung mit ihren Zahlen
POST /api/v1/work-items/countsZahlen für bis zu 50 benannte Filter
GET, POST /api/v1/viewsDie Views, nach Name; 201 mit einer neuen
GET, PUT, DELETE /api/v1/views/{id}Eine View; PUT ersetzt sie ganz; 204
POST /api/v1/favorites/toggle{"kind": "view", "id": "…"} setzt den Stern einer View oder nimmt ihn weg

Eine View lesen ​

?view=<id> liefert die Items einer View: ihren Filter, ihre Sortierung und ob sie Kind-Items zeigt. filter[…] engt weiter ein (alle Bedingungen gelten), sort ersetzt ihre Sortierung: der API-Name aus Sortierung, mit - davor absteigend (sort=-due_date).

bash
curl -g -H "Authorization: Bearer <Token>" \
  "https://werkbuch.example.com/api/v1/work-items?view=01m6dd2re3zvh9g281chdw9hmv&filter[state_category]=unstarted,started&sort=-due_date&lean=1"

Die Kurzform nimmt diese Schlüssel; mehrere Werte stehen durch Kommas getrennt und heißen „einer davon“:

SchlüsselWert
projectKennung, frühere Kennung oder ULID; unbekannt oder verborgen ist 404
parentKey oder ULID eines Items; unbekannt oder verborgen ist 404
qEin Key (WEB-47) findet dieses Item, jeder andere Text sucht im Titel
assignee, created_byULIDs oder me; none allein für „niemand“
type, state, labelULIDs
state_categorybacklog, unstarted, started, completed, canceled
priorityurgent, high, medium, low, none
archivedtrue oder false

sort nimmt ein Feld (due_date), ein Feld mit - für absteigend (-due_date) oder eine Property (property:effort). lean=1 lässt description, description_json und values_markdown weg und macht lange Listen viel kleiner. Jeder andere Schlüssel in filter[…] ist ein 422.

Mit einem Filter abfragen ​

POST /api/v1/work-items/query nimmt einen Filter im Body. Neben filter nimmt es view_id, shorthand (die Kurzform als Objekt), q, sort ({"field", "direction"}), show_sub_items, group_by und group (eine Gruppe einer Gruppierung, etwa eine Spalte eines Boards), include_archived, lean, cursor und per_page. Jeder andere Schlüssel ist ein 422.

bash
curl -X POST https://werkbuch.example.com/api/v1/work-items/query \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "version": 1, "conditions": [
      { "field": "assignee", "op": "is", "value": "me" },
      { "field": "due_date", "op": "before", "value": { "relative": "+7d" } },
      { "field": "state_category", "op": "in", "value": ["unstarted", "started"] }
    ] },
    "sort": { "field": "due_date", "direction": "asc" },
    "lean": true,
    "per_page": 50
  }'

Die Antwort ist eine Seite wie in jeder Liste, mit den Items in data. Einen Filter, der nicht passt, lehnt werkbuch mit allen Problemen auf einmal ab:

json
{
  "type": "urn:werkbuch:problem:validation_failed",
  "title": "Validierung fehlgeschlagen",
  "status": 422,
  "detail": "Die Eingabe ist nicht gültig.",
  "reason": "validation_failed",
  "errors": {
    "filter.conditions.0.field": ["Dieses Feld gibt es nicht."],
    "filter.conditions.1.op": ["Dieses Feld kennt diesen Operator nicht."]
  }
}

Gruppen ​

POST /api/v1/work-items/groups nimmt view_id, filter, q, sort, show_sub_items, include_archived und group_by (Pflicht) und antwortet mit der Gruppierung, die gilt, der Zahl aller Items und den Gruppen in ihrer Reihenfolge:

bash
curl -X POST https://werkbuch.example.com/api/v1/work-items/groups \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{"view_id": "01m6dd2re4m3z0aez8e2qzc19p", "group_by": "state"}'
json
{
  "data": {
    "group_by": "category",
    "total": 3,
    "groups": [
      { "key": "backlog", "count": 1 },
      { "key": "unstarted", "count": 0 },
      { "key": "started", "count": 2 },
      { "key": "completed", "count": 0 },
      { "key": "canceled", "count": 0 }
    ]
  }
}

Hier verteilen sich die Items auf mehrere Workflows, also gruppiert der Server nach Kategorie. Die Items einer Gruppe liest query mit demselben group_by wie in der Antwort und "group": "<key>". Gruppen nach Eltern-Item tragen das Item (id, key, title, type_id).

Zahlen ​

POST /api/v1/work-items/counts zählt bis zu 50 benannte Filter auf einmal. Namen sind 1 bis 64 Buchstaben, Ziffern, _, ., : oder -; include_archived gilt für alle.

bash
curl -X POST https://werkbuch.example.com/api/v1/work-items/counts \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "overdue": { "version": 1, "conditions": [{ "field": "due_date", "op": "overdue" }] },
      "mine": { "version": 1, "conditions": [{ "field": "assignee", "op": "is", "value": "me" }] }
    }
  }'
json
{ "data": { "overdue": 10, "mine": 8 } }

Gruppen und Zahlen zählen nur, was das Konto des Tokens sieht. Ein Filter auf ein Projekt, das es nicht sieht, zählt 0, als gäbe es das Projekt nicht.

Seiten und Cursor ​

Eine Seite hat bis zu 100 Items (per_page, Standard 100); meta.total zählt alle, meta.next_cursor führt weiter. Bei GET folgst du links.next: der Link behält die Query (View, Filter, Sortierung, per_page). Bei POST ist links.next null: schick dieselbe Anfrage noch einmal mit meta.next_cursor als cursor; die Sortierung bestimmt die Reihenfolge, Gleichstand entscheiden die manuelle Reihenfolge und die ULID, so kommt jedes Item genau einmal. Ein Cursor gehört zu seiner Sortierung und Gruppe: einer aus einer anderen Liste ist ein 422 an cursor, und ein leerer cursor beginnt auf der ersten Seite.

Views verwalten ​

bash
curl -X POST https://werkbuch.example.com/api/v1/views \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Überfällig bei Nordlicht",
    "icon": "timer",
    "filter": { "version": 1, "conditions": [
      { "field": "property:customer", "op": "is", "value": "01m6dd2rc7syc8r8s7q2my2j51" },
      { "field": "due_date", "op": "overdue" }
    ] },
    "display": {
      "layout": "table",
      "group_by": "assignee",
      "sort": { "field": "due_date", "direction": "asc" },
      "fields": ["key", "title", "state", "assignee", "due_date", "property:customer"],
      "show_sub_items": true
    }
  }'

Alle vier Teile sind Pflicht, auch beim PUT, das die View ganz ersetzt; eine Antwort unverändert zurückgeschickt ändert nichts. display nimmt layout (list, board, table, timeline), group_by (state, category, assignee, priority, type, label, project, parent, none), sort, fields (bis zu 30: key, title, state, assignee, priority, labels, start_date, due_date, project, created_at, updated_at und property:<key>) und show_sub_items.