Typen und Properties
Typen, Properties, Labels, Relationstypen und Resolutions sind die Kataloge der Organisation. Org-Admins pflegen sie unter Einstellungen in der Gruppe Kataloge; alle anderen können sie dort lesen, und Projekte wählen aus ihnen. Namen sind in jedem Katalog eindeutig, ohne Rücksicht auf Groß- und Kleinschreibung und auf Akzente („Über“ und „uber“ sind derselbe Name). Die Labels von Properties sind keine Namen: Zwei Properties dürfen eins teilen, ihre Schlüssel sind eindeutig.
Typen
Jedes Work Item hat einen Typ, etwa Task oder Bug. werkbuch liefert drei mit: Task, Bug (mit der optionalen Property „Aufwand (h)“) und Epic. Weitere legst du unter Einstellungen → Typen an.
Ein Typ hat:
- einen Namen (bis 60 Zeichen) und eine Beschreibung,
- ein Icon aus einer festen Liste von 20 (
square-check,bug,zap,layers,file-text,rocketund weitere), - eine Farbe, einen von sechs Tönen: Himmel, Ocker, Moos, Pflaume, Sand und Schiefer,
- das Häkchen Epic: Items eines Epic-Typs erscheinen in der Timeline und können Kind-Items haben,
- seine Properties, jede Pflicht oder nicht, in der Reihenfolge, die du ihnen gibst.
Archivieren statt löschen
Ein archivierter Typ nimmt keine neuen Items an. Projekte, die ihn aktiviert haben, behalten ihn, aber kein Projekt kann ihn neu aktivieren, und er kann nicht Standardtyp werden. Wiederherstellen holt ihn zurück.
Ein Typ, der Standardtyp eines Projekts ist, lässt sich weder archivieren noch löschen; wähle in diesen Projekten zuerst einen anderen Standardtyp. Das gilt auch für archivierte Projekte und für ein Projekt, das gerade gelöscht wird, bis es endgültig weg ist. Die Oberfläche und die API (409, reason: default_type, die Kennungen in projects) nennen sie. Löschen nimmt einen Typ aus jedem Projekt, das ihn aktiviert hatte. Ein Typ, den noch Items tragen, wird archiviert statt gelöscht (die API antwortet {"outcome": "archived"}): Die Items behalten ihn, nur neue Items bekommen ihn nicht mehr. Der Epic-Haken richtet sich nach den Items: Er lässt sich nur wegnehmen, solange kein Item des Typs Kind-Items hat, und nur setzen, solange keins ein Eltern-Item hat (422 an is_epic; archivierte Items zählen).
Die Typen eines Projekts
Jedes Projekt aktiviert die Typen, die es nutzt, und wählt einen davon als Standardtyp für neue Items. Projekt-Admins tun das unter Projekteinstellungen → Typen. Mindestens ein aktiver Typ bleibt aktiviert, und der Standardtyp ist aktiviert und aktiv.
Ein neues Projekt bekommt alle aktiven Typen, der erste ist der Standard, außer du wählst im Dialog anders; dort wird der oberste angehakte Typ der Standard.
Properties
Eine Property ist ein Feld, das Typen ihren Items über die Kernfelder hinaus geben, die jedes Item hat. Properties gehören der Organisation und werden unter Einstellungen → Typen den Typen zugeordnet. Eine Property hat ein Label (bis 60 Zeichen), einen Hilfetext (bis 500), einen Schlüssel, einen Feldtyp und optional einen Standardwert.
Wo eine Property steht
Anzeige im Dialog einer Property entscheidet, wo sie an einem Item steht, für jeden Typ, der sie hat: In der Seitenleiste bei Status, Assignee und den anderen Feldern, oder Unter der Beschreibung über die ganze Breite unter Weitere Angaben, vor den Kind-Items und Relationen. Eine neue Rich-Text-Property beginnt unter der Beschreibung, jede andere in der Seitenleiste. Unter der Beschreibung sieht, wer das Item nicht ändern darf, eine Property nur mit Wert (ein Ja/Nein auf Nein gilt als keiner). Über REST heißt das Feld placement (sidebar oder body); fehlt es, nimmt es den Platz, den eine neue Property seines Feldtyps bekommt.
Schlüssel
Der Schlüssel nennt die Property in der API, in MCP und in Filtern (property:<key>). Er ist snake_case: Kleinbuchstaben, Ziffern und _, vorn ein Buchstabe, höchstens 40 Zeichen. Er ist eindeutig und lässt sich nicht ändern, sobald die Property gespeichert ist. Er darf nicht der Name eines Kernfelds sein: id, key, project, type, title, description, state, state_category, resolution, assignee, priority, label, labels, start_date, due_date, parent, created_by, created_at, updated_at, started_at, closed_at, archived, archived_at und rank sind vergeben.
Feldtypen
Auch der Feldtyp ist fest. Erlaubt ist nur der Wechsel von Einfach- auf Mehrfachauswahl (bei Dropdowns und der Personenauswahl), nie zurück, denn Items verlören sonst alle Werte bis auf einen.
| Feldtyp | Wert | Einstellungen | Standardwert |
|---|---|---|---|
Text (text) | Eine Zeile, bis 255 Zeichen. | – | Ein Text; leer heißt keiner. |
Zahl (number) | Eine Dezimalzahl. | 0 bis 4 Nachkommastellen. | Eine Zahl, auf die Nachkommastellen gerundet. |
Dropdown (dropdown) | Eine oder mehrere Optionen aus einer Liste. | Mehrfachauswahl; die Optionen. | Eine nicht archivierte Option, bei Mehrfachauswahl mehrere. |
Ja oder nein (boolean) | Ein Schalter. | – | Ja oder nein; nein liest sich wie ein leeres Ja-oder-nein-Feld. |
Datum (date) | Ein Datum ohne Uhrzeit. | – | Ein Datum (2026-10-31). |
Personenauswahl (member) | Personen oder Bots mit Zugriff auf das Projekt. | Mehrfachauswahl. | Keiner. |
Rich Text (rich_text) | Formatierter Text im selben Editor wie die Beschreibung. | – | Keiner. |
URL (url) | Eine Adresse mit http oder https. | – | Eine Adresse mit http oder https. |
Optionen
Ein Dropdown hat mindestens eine aktive Option. Eine Option hat ein Label (bis 60 Zeichen), einen Ton (in der API das Feld color) und einen Platz in der Reihenfolge; ein Dropdown hat höchstens 100. Eine Option, die du nicht mehr anbieten willst, lässt sich archivieren: Für neue Werte steht sie nicht mehr zur Wahl, und du kannst sie wiederherstellen. Eine gespeicherte Option lässt sich auch entfernen (in der Oberfläche mit dem Kreuz daneben, über die API, indem sie in einem PUT fehlt): Sie wird gelöscht, es sei denn, Items tragen sie: Dann wird sie stattdessen archiviert, und die Oberfläche sagt es nach dem Speichern.
Pflichtwerte und Standardwerte
Eine Property, die ein Typ als Pflicht hat, braucht einen Wert, wenn ein Item dieses Typs entsteht und wenn ein Item zu diesem Typ wechselt; ein gesetzter Wert lässt sich nicht wieder leeren (422 an values.<key>). Wird eine Property erst später Pflicht, bleiben die Items ohne Wert gültig: Alles andere an ihnen lässt sich weiter ändern, und das Item zeigt am Feld „Pflichtfeld, noch leer. Bitte ergänzen.“ Bei einem Ja/Nein-Feld zählt aus (false) als Wert.
Der Standardwert füllt ein neues Item, wenn die Anfrage die Property gar nicht nennt; ein mitgeschicktes null lässt sie leer. Ein Standardwert, der auf eine inzwischen archivierte Option zeigt, entfällt.
Labels
Labels markieren Items über alle Projekte hinweg, etwa „UX“ oder „Formulare“. Ein Label hat einen Namen (bis 60 Zeichen) und einen Ton (in der API das Feld color). Ein Standard-Label gibt es nicht.
Relationstypen
Ein Relationstyp benennt die Verbindung zwischen zwei Items. Er hat einen Namen und für jede Richtung eine Beschriftung, etwa „blockiert“ und „wird blockiert von“, oder er ist symmetrisch und heißt in beide Richtungen gleich, etwa „verwandt mit“.
Über die API hat ein symmetrischer Relationstyp inward_label: null; ein leerer Text wird abgelehnt.
werkbuch liefert drei mit: blockiert (andersherum „wird blockiert von“), Duplikat und verwandt (symmetrisch). Sie lassen sich umbenennen, aber nicht löschen. Nur „blockiert“ löst etwas aus: Solange der Blocker offen ist, zeigt das blockierte Item einen Hinweis (siehe Work Items). Eigene Relationstypen sind reine Beschriftung.
Resolutions
Eine Resolution sagt, wie ein geschlossenes Item ausgegangen ist. Ein Item, das in einen Status der Kategorie Completed oder Canceled wechselt, bekommt eine: die, die du wählst, sonst den Standard der Kategorie. werkbuch liefert Done (Standard für Completed), Won't do (Standard für Canceled), Duplicate und Cannot reproduce mit, in dieser Reihenfolge.
Jede der beiden Kategorien hat immer genau einen Standard. Wird eine Resolution Standard einer Kategorie, verliert die bisherige die Marke; um den Standard zu wechseln, machst du eine andere Resolution zum Standard. Ein Standard lässt sich weder archivieren noch löschen. Eine archivierte Resolution steht nicht mehr zur Wahl. Löschst du eine Resolution, die Items tragen, wird sie stattdessen archiviert; die Items behalten sie.
REST
Lesen darf jedes Konto die Kataloge; anlegen, ändern und löschen nur Org-Admins. Listen kommen in Seiten von bis zu 100 (per_page, cursor), wie jede Liste der API.
| Katalog | Auflisten und anlegen | Lesen, ändern und löschen |
|---|---|---|
| Typen | /api/v1/work-item-types | /api/v1/work-item-types/{id} |
| Properties | /api/v1/properties | /api/v1/properties/{id} |
| Labels | /api/v1/labels | /api/v1/labels/{id} |
| Relationstypen | /api/v1/relation-types | /api/v1/relation-types/{id} |
| Resolutions | /api/v1/resolutions | /api/v1/resolutions/{id} |
POST legt an (201), PUT ersetzt den ganzen Eintrag: Jedes Feld ist Pflicht außer denen, die leer sein dürfen (Beschreibungen, Hilfetexte, der Standardwert, inward_label, default_for, archived_at), und ein fehlendes ist ein 422 an diesem Feld. Zum Archivieren schickst du einen beliebigen Text in archived_at (die Zeit setzt werkbuch selbst); null stellt wieder her. Ein Feld, das einen Eintrag über seine ID nennt (property_id, enabled_type_ids, default_type_id), nimmt dessen ULID genau so, wie werkbuch sie ausgibt, in beliebiger Schreibweise; alles andere ist ein 422 an diesem Feld. Die Typen eines Projekts ändert PATCH /api/v1/projects/{project} mit den Feldern enabled_type_ids und default_type_id.
Eine Dropdown-Property mit zwei Optionen, die erste als Standard. Wie die Status eines Workflows tragen neue Optionen IDs, die du wählst (nicht mit new: am Anfang), und werkbuch antwortet mit ULIDs:
curl -X POST https://werkbuch.example.com/api/v1/properties \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"label": "Kanal",
"key": "channel",
"field_type": "dropdown",
"help": "Wo der Beitrag erscheint.",
"settings": { "multiple": false },
"options": [
{ "id": "web", "label": "Website", "color": "sky" },
{ "id": "news", "label": "Newsletter", "color": "moss" }
],
"default_value": "web"
}'{
"data": {
"id": "01m68z9k8p6q45xg9r0vx5mc93",
"key": "channel",
"label": "Kanal",
"field_type": "dropdown",
"help": "Wo der Beitrag erscheint.",
"default_value": "01m68z9k8p6q45xg9r0vx5mc94",
"settings": { "multiple": false },
"options": [
{ "id": "01m68z9k8p6q45xg9r0vx5mc94", "label": "Website", "color": "sky", "position": 0, "archived_at": null },
{ "id": "01m68z9k8qhx241w3mz1fagh3q", "label": "Newsletter", "color": "moss", "position": 1, "archived_at": null }
]
}
}Ein Typ, der sie verlangt:
curl -X POST https://werkbuch.example.com/api/v1/work-item-types \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"name": "Artikel",
"icon": "file-text",
"tone": "plum",
"description": "Ein Beitrag für die Website oder den Newsletter.",
"is_epic": false,
"properties": [{ "property_id": "01m68z9k8p6q45xg9r0vx5mc93", "required": true }]
}'settings ist {"decimals": 0…4} bei einer Zahl, {"multiple": true|false} bei einem Dropdown oder einer Personenauswahl und sonst leer. Löschen eines Typs oder einer Resolution antwortet 200 mit {"outcome": "deleted"}, oder mit {"outcome": "archived"}, wenn Items sie tragen. Löschen einer Property oder eines Labels antwortet {"affected_items": 2}, bei einem Relationstyp {"affected_relations": 2}: die Items, die einen Wert oder das Label verloren haben, und die Relationen, die mit dem Typ gegangen sind, gezählt, bevor sie gingen. Die History eines Items behält, was seine Werte waren.