Antylogic
DemoApp login

399 operational guides

Docs sections
DocsKDS operations
Device

How to View the KDS Board

Use the KDS board to monitor the active service at Harbor Soho, with open accounts, table and staff labels, and kitchen items grouped by production state. Viewing requires KDS access; moving items through production states requires `kds:use` or `kds:manage`.

In this article

The KDS board is the live kitchen reading surface for a location. It shows the active service, the open accounts still carrying kitchen work, and the pending items that need attention by production state.

This guide covers the view-only board experience. Opening or closing a service, changing item states, taking payment, or opening the TPV ticket detail are adjacent actions with their own permissions.

Before you start

  • You are signed in with Harbor Demo Group and Harbor Soho selected.
  • KDS is enabled for the location through `tpv_settings.enable_kds`.
  • There is an open `service_sessions` record for the location, such as Soho lunch service.
  • The active service has open tickets with kitchen `ticket_items` that are not `served` or `cancelled`.
  • The user has at least one location permission: `kds:view`, `kds:use` or `kds:manage`.

Instructions

  1. 1.

    Open the KDS screen

    Open the KDS area for the selected location, or use `antylogic://${ORG_ID}/${LOCATION_ID}/kds` in the demo runtime. The page checks the selected organisation, selected location and KDS permissions before loading service data.

  2. 2.

    Check the active service

    Read the service header first. When a service is open, the board can load the account queue for that session. If no service is active, KDS shows the no-service state and does not request ticket details.

  3. 3.

    Use the state filters

    Use the filters to focus on Requested (`draft`), Sent (`sent`), In preparation (`preparing`) and Ready (`ready`) items. The counters come from visible KDS-relevant items in the active service; served and cancelled items are excluded.

  4. 4.

    Review account cards

    Each card represents an open ticket in the active service. The header shows the account number, resolved tables and staff member, then the card lists the matching kitchen items for the selected filters.

  5. 5.

    Inspect kitchen item rows

    Each row shows quantity, the KDS product label, optional seat or guest information, notes, state icon and elapsed timer for live production states. The KDS label uses `kitchen_name` first, then `short_name`, then `name`.

  6. 6.

    Respect access limits

    With only `kds:view`, the board is consultative. Operators can monitor the queue but cannot move items forward or back. Opening a TPV ticket from an account header also requires TPV or ticket permissions.

  7. 7.

    Interpret empty and error states

    No active service means there is no board to show. An active service with no pending kitchen items means the queue is clear. A loading error means one of the board dependencies, such as service, staff, layouts, tickets, output devices or KDS jobs, could not be loaded.

Validations and limits

  • `buildBackendPath` requires both `orgId` and `locationId`; the UI also requires a selected organisation and location before rendering the board.
  • The UI requires one of `kds:view`, `kds:use` or `kds:manage` before loading KDS data.
  • If `tpv_settings.enable_kds` is false, the KDS board is stopped at the disabled state.
  • `GET /service-sessions/active` must return an open service session; a 404 is treated as no active service, not as a board loading failure.
  • Ticket details are requested only for the active service with `include_details=true`; KDS-only users are restricted by the backend to the active service.
  • Closed or void tickets are excluded from the board.
  • An item appears on the board only when it uses the kitchen flow and its production status is not `served` or `cancelled`.
  • The visible production states are `draft`, `sent`, `preparing` and `ready`; the screen flow is `draft` to `sent` to `preparing` to `ready` to `served`.
  • Opening the account header as a TPV ticket link requires `tpv:view`, `tpv:use`, `tpv:manage`, `tickets:view` or `tickets:manage`.

Expected result

The operator has a live, permission-aware view of the Harbor Soho kitchen queue for the active service, without changing tickets, payments, service state or item production status.

Related articles