KANBAN
KANBAN
The KANBAN plugin is the central hub for kanban boards: at/kanban it aggregates the boards of all active plugins in one
Unified Kanban Board and provides the shared column management for
kanban categories (admin area).
The board is source-based (layers): each source comes from aKanbanSourceProvider implementation of the respective plugin and displays
its cards:
- Tickets (plugin
TICKET) — columns = ticket statuses, cards = active
tickets (subtitle: assignee, colour: priority) - Contracts (plugin
VERTRAG) — columns = kanban categories, cards =
contracts with a category (subtitle: tenant, fallback title "Contract
#uuid")
Further plugins can contribute their own kanban boards via the sameKanbanSourceProvider interface (details: section "Implementing your own
KanbanSourceProvider").
> The board does not need its own database table — cards come directly
> from the source plugins. Requirements: the KANBAN plugin plus at least one
> plugin with a kanban source (e.g. TICKET or VERTRAG). The previous
> category management for contracts remains available under
> Admin → Kanban (/settings/admin/kanban).
- Open the kanban board (
/kanban) - Show/hide sources (layers)
- Move cards between columns via drag and drop
- Click a card → detail page of the source plugin
- Manage kanban categories (Admin → Kanban)
1) Open the kanban board
- Open Kanban in the menu (
/kanban). Permission:kanban.board.view. - Active sources appear as tabs (e.g. "Tickets", "Contracts"); the first
active source is selected by default. - Use the layer bar ("Sources") to show/hide sources — the setting is
stored per user (prefkanban.layer.<PLUGINKEY>, e.g.kanban.layer.TICKET/kanban.layer.VERTRAG). Default is on. - The active tab is reflected in the URL (
/kanban?tab=VERTRAG) — links are
shareable. The contract list also points to/kanban?tab=VERTRAGvia its kanban tab.
> If no active source exists, an empty state is shown with a link to the
> kanban setup (/settings/admin/kanban). If all sources are hidden via the
> layer toggles, an info banner is displayed.
2) Moving cards (drag and drop)
- Drag a card with mouse or touch into another column.
- The move is delegated to the matching source via
POST /kanban/move
(parameterspluginKey,cardRef,zielSpalte). Permission:kanban.board.edit. - Tickets: move = status change — like the single status change
(POST /tickets/{id}/status), including audit entry and mail note.
Additionally requires theticket.tickets.editpermission; an unknown
target status is rejected. - Contracts: move = category assignment via the shared
VertragKanbanService— same semantics as the legacy endpointPOST /dokumente/vertraege/kanban/move(change log entry
"KANBAN_MOVED", mail event). - If a move fails (permissions, target does not exist, …), the UI shows a
toast ("Move failed") and reloads the page so that UI and data stay in
sync. - Done columns: Dropping a card into a column with the "Done" badge shows
a confirmation dialog before the move is persisted (M27.2-12). Cancelling
reloads the board (server state is authoritative).
3) Clicking a card
- Every card is a click target and opens the detail page of the source plugin
(e.g./tickets/{uuid},/dokumente/vertraege/{uuid}). - On the detail page the "Back" button (M27.2-13) returns to the board via a
referrer check when the visit came from inside the app (e.g. from the board,
including tab and filter query); without a referrer (or when opened from
outside) the source plugin's list view applies.
4) Managing kanban categories (Admin → Kanban)
- Open Admin → Kanban (
/settings/admin/kanban). - You see the list of configured columns ("categories") in their current
order. The card count per column is reported by each kanban source via
the column SPI (issue #792); inactive or failing sources show a
placeholder instead of a number. - Create: enter a name, save
(POST /settings/admin/kanban). - Rename: "Rename" → enter name → save
(POST /settings/admin/kanban/{id}/rename). - Reorder: up/down arrows
(POST /settings/admin/kanban/{id}/upor/down). - Special functions (per category):
- "Inquiries" column: new contracts from the HOMEPAGE inquiry form
land here automatically
(POST /settings/admin/kanban/{id}/toggle-anfragen). - "Completed" column: contracts in this column are handled separately
in lists/statistics
(POST /settings/admin/kanban/{id}/toggle-abgeschlossen).
> It only makes sense to have one "Inquiries" and one
> "Completed" column at a time.
- "Inquiries" column: new contracts from the HOMEPAGE inquiry form
- Delete:
POST /settings/admin/kanban/{id}/delete— only deletable
when no active source counts cards in the column (card counts are reported
by each source via the column SPI, issue #792); cards in other columns
remain untouched. While an active source cannot deliver its counts,
deletion stays blocked (visible notice instead of a silent 0).
Plugins register their cards via the plugin SPIapp.allesda.core.kanbanboard.KanbanSourceProvider (app-core). TheKanbanSourceRegistry (also app-core, @Component) collects allKanbanSourceProvider beans automatically — new sources appear in the
board without any core changes. Tenant filtering (only active plugins) is
done by the registry, not by the provider.
Interface: method by method
| Method | Purpose |
|---|---|
String pluginKey() |
Plugin key according to tenant.getEnabledPluginKeys() (e.g. "ERP"). The registry filters on this — only providers of active plugins supply a layer. |
String labelKey() |
i18n key for the tab/layer label (e.g. "erp.kanban.layer"). If the key is missing (or empty), the UI falls back to the plugin key. |
KanbanBoardDto board(TenantInfo tenant, String username) |
Returns the plugin's board: KanbanBoardDto(pluginKey, labelKey, columns) with KanbanColumnDto(key, name, order, cards) and KanbanCardDto(ref, title, subtitle, colorHex, detailUrl, order). ref is the plugin-internal identifier of the card; subtitle, colorHex and detailUrl are optional (null allowed). Which cards are visible is decided by the source itself (no data leaks across plugins). null is allowed (empty board). |
void move(String cardRef, String zielSpalte, TenantInfo tenant, String username) |
Moves a card to another column — delegates to the plugin's own logic (status change, category assignment, …). Perform your own permission check (e.g. ticket.tickets.edit) and throw on errors (e.g. IllegalArgumentException with an i18n key). |
> Issue #687 – Column and card metadata: KanbanColumnDto optionally
> carries the flags newItems (column where new items land, e.g. the
> form's target) and done (finished/terminal column); KanbanCardDto
> optionally carries fields (extra info rows, e.g. tenant/priority),
> startDate/endDate (ISO dates for client-side time filtering) and
> searchText (precomputed search text). The previous 4- and
> 6-argument constructors remain available via compatibility overloads.
Example snippet (plugin "ERP")
@Component
public class ErpKanbanSource implements KanbanSourceProvider {
private final ErpService erpService;
public ErpKanbanSource(ErpService erpService) {
this.erpService = erpService;
}
@Override
public String pluginKey() {
return "ERP";
}
@Override
public String labelKey() {
return "erp.kanban.layer";
}
@Override
public KanbanBoardDto board(TenantInfo tenant, String username) {
List<KanbanColumnDto> columns = new ArrayList<>();
for (ErpStatus status : erpService.statuses()) {
List<KanbanCardDto> cards = erpService.activeOrders(status).stream()
.map(a -> new KanbanCardDto(
a.getUuid().toString(), // cardRef
a.getTitle(),
a.getEmployee(), // subtitle
null, // colorHex (UI fallback)
"/erp/orders/" + a.getUuid(), // detailUrl
0))
.collect(Collectors.toList());
columns.add(new KanbanColumnDto(status.getKey(), status.getLabel(),
status.getSortOrder(), cards));
}
return new KanbanBoardDto(pluginKey(), labelKey(), columns);
}
@Override
public void move(String cardRef, String zielSpalte, TenantInfo tenant, String username) {
if (!permissionService.hasPermission(username, "erp.orders.edit")) {
throw new IllegalArgumentException("erp.kanban.no_permission");
}
erpService.changeStatus(UUID.fromString(cardRef), zielSpalte);
}
}
> Error isolation: the KanbanSourceRegistry calls each source within its
> own try/catch: if board() throws or returns null, the problem is logged
> and the source is skipped — the boards of the remaining sources are
> still delivered. The same applies to move(): an error in one source does
> not abort the call or make the board unusable. A single broken provider
> will never bring the whole kanban board down.
"I don't see /kanban"
- Is the KANBAN plugin enabled for the tenant? (Otherwise:
/plugin-disabled.) - Is the
kanban.board.viewpermission granted (via ROLLEN)?
"Cards can't be moved"
- Do you have the
kanban.board.editpermission? - Plugin-specific permissions: for TICKET moves additionally
ticket.tickets.edit; for VERTRAG moves the usual contract permissions
(the lock check is bypassed with force, since the board route is reserved
for USER_ADMIN). - If a move fails, the UI shows a toast — check the server log (Logging
plugin) forKanban-Quelle … konnte Karte … nicht verschieben.
"A source is missing from the board"
- Is the source plugin enabled in the tenant? Only active plugins supply
sources. - Is the layer hidden via the layer toggle? Check the user's pref
kanban.layer.<PLUGINKEY>(default is on). - Is the source throwing errors? Server log:
Kanban-Quelle … hat Board nicht liefern können— the registry isolates
and skips failing sources.
"Cards from a source plugin are wrong"
- Visible cards are decided by the source (e.g. TICKET shows only active
tickets, VERTRAG only contracts with a category). Correct the data at the
source (e.g. status in the ticket plugin, category on the contract).
User area:
GET /kanban– Unified Kanban Board (optional?tab=PLUGINKEYfor deep links)POST /kanban/move– move a card (DnD; parameterspluginKey,cardRef,zielSpalte; permissionkanban.board.edit)POST /kanban/toggle-layer– show/hide a source (prefkanban.layer.<KEY>, active providers only)
Admin (/settings/admin/kanban):
GET /settings/admin/kanban– category overviewPOST /settings/admin/kanban– create categoryPOST /settings/admin/kanban/{id}/renamePOST /settings/admin/kanban/{id}/deletePOST /settings/admin/kanban/{id}/upPOST /settings/admin/kanban/{id}/downPOST /settings/admin/kanban/{id}/toggle-anfragenPOST /settings/admin/kanban/{id}/toggle-abgeschlossen
Legacy endpoints of the source plugins:
POST /tickets/{id}/status– ticket status change (TICKET)POST /dokumente/vertraege/kanban/move– move contract to category (VERTRAG)
- All
/kanbanroutes are KANBAN-gated: if the plugin is disabled for
the tenant, they redirect to/plugin-disabled. - The layer toggles are per user (pref
kanban.layer.<KEY>, default
on) and only affect the display — not the source data. - Cards are click targets: the click opens the
detailUrlof the source
plugin (after a drag, the click is suppressed for a short period). - The colour coding of sources is derived deterministically from the plugin
key (hash); a card'scolorHex(e.g. ticket priority) overrides the source
colour at card level. - New sources come from
KanbanSourceProviderbeans of the respective
plugins — KANBAN itself only filters by tenant and user prefs; the
visibility/permission logic stays in the source plugin (error isolation in
the registry). - The inline kanban view in the contract list was removed (M27.2-04): the
kanban tab now points to the central board (/kanban?tab=VERTRAG).