Docs

KANBAN

Documentation

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 a
KanbanSourceProvider 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 same
KanbanSourceProvider 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

  1. Open Kanban in the menu (/kanban). Permission: kanban.board.view.
  2. Active sources appear as tabs (e.g. "Tickets", "Contracts"); the first
    active source is selected by default.
  3. Use the layer bar ("Sources") to show/hide sources — the setting is
    stored per user (pref kanban.layer.<PLUGINKEY>, e.g.
    kanban.layer.TICKET / kanban.layer.VERTRAG). Default is on.
  4. The active tab is reflected in the URL (/kanban?tab=VERTRAG) — links are
    shareable. The contract list also points to
    /kanban?tab=VERTRAG via 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
    (parameters pluginKey, 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 the ticket.tickets.edit permission; an unknown
    target status is rejected.
  • Contracts: move = category assignment via the shared
    VertragKanbanService — same semantics as the legacy endpoint
    POST /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)

  1. Open Admin → Kanban (/settings/admin/kanban).
  2. 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.
  3. Create: enter a name, save
    (POST /settings/admin/kanban).
  4. Rename: "Rename" → enter name → save
    (POST /settings/admin/kanban/{id}/rename).
  5. Reorder: up/down arrows
    (POST /settings/admin/kanban/{id}/up or /down).
  6. 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.
  7. 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 SPI
app.allesda.core.kanbanboard.KanbanSourceProvider (app-core). The
KanbanSourceRegistry (also app-core, @Component) collects all
KanbanSourceProvider 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.view permission granted (via ROLLEN)?

"Cards can't be moved"

  • Do you have the kanban.board.edit permission?
  • 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) for Kanban-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=PLUGINKEY for deep links)
  • POST /kanban/move – move a card (DnD; parameters pluginKey, cardRef, zielSpalte; permission kanban.board.edit)
  • POST /kanban/toggle-layer – show/hide a source (pref kanban.layer.<KEY>, active providers only)

Admin (/settings/admin/kanban):

  • GET /settings/admin/kanban – category overview
  • POST /settings/admin/kanban – create category
  • POST /settings/admin/kanban/{id}/rename
  • POST /settings/admin/kanban/{id}/delete
  • POST /settings/admin/kanban/{id}/up
  • POST /settings/admin/kanban/{id}/down
  • POST /settings/admin/kanban/{id}/toggle-anfragen
  • POST /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 /kanban routes 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 detailUrl of 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's colorHex (e.g. ticket priority) overrides the source
    colour at card level.
  • New sources come from KanbanSourceProvider beans 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).