Antylogic
DemoApp login

399 operational guides

Docs sections
DocsKDS and TPV
Device

Process KDS Output Jobs

Open the Harbor Soho KDS board on an active local terminal so Antylogic can process eligible KDS output jobs in the background. There is no separate Process button: the board loads active-service `job_kind == kds` jobs, the local runtime claims each compatible job, runs the KDS adapter, and saves the result as completed or failed.

In this article

Use this guide when a kitchen supervisor, TPV operator, or location manager needs to understand how KDS output jobs are processed while the KDS board is open for Harbor Soho.

The action is automatic and terminal-scoped. The route may include `?terminalId=${TPV_TERMINAL_ID}` to filter jobs, but the terminal written to the job comes from the active terminal resolved by the app.

Before you start

  • Harbor Demo Group and Harbor Soho are selected.
  • KDS is enabled for Harbor Soho in TPV settings.
  • A service session is active for the location, such as Soho lunch service.
  • The current operator has `kds:use` or `kds:manage`; `kds:view` can open the board but does not run automatic processing.
  • A current TPV terminal is resolved by the app.
  • At least one active KDS output device exists and the job `output_device_id` points to it.
  • At least one active-service `tpv_output_job` exists with `job_kind == kds` and status `pending` or `claimed`.
  • When the KDS route includes `terminalId`, the job already has `terminal_id` or `claimed_by_terminal_id` matching that selected terminal.

Instructions

  1. 1.

    Open The KDS Board

    Open `antylogic://${ORG_ID}/${LOCATION_ID}/kds?terminalId=${TPV_TERMINAL_ID}`. The KDS board is the surface that mounts the background runtime; the operator does not start processing from a visible command.

  2. 2.

    Confirm Operation Rights

    Use an operator who can operate KDS, not only view it. Automatic processing starts only when an active terminal exists and the operator has `kds:use` or `kds:manage`.

  3. 3.

    Load Eligible Jobs

    The board polls output jobs for the active service session, loads active KDS output devices, keeps only `job_kind == kds` jobs, and applies terminal matching when the route is terminal-scoped.

  4. 4.

    Select The Next Job

    The local runtime ignores jobs already completed, cancelled or failed, avoids processing the same job twice at the same time, and chooses the next job whose output device matches the `kds_local` adapter.

  5. 5.

    Claim Pending Jobs

    If the job is pending, the runtime first updates it to claimed with `terminal_id`, `claimed_by_terminal_id`, and runtime claim metadata. Jobs already claimed skip this preliminary update.

  6. 6.

    Complete Or Fail The Job

    The `kds_local` adapter runs locally for the KDS device. On success, the runtime saves the job as completed with KDS metadata; if the adapter throws, it saves the job as failed with the error message.

  7. 7.

    Review The Result

    Open the TPV floor route and use More POS actions to open the Print and KDS queue. The queue is the review surface for the persisted KDS job state, not the primary processing action.

Validations and limits

  • The KDS page requires selected organisation and location context, KDS permission, and `tpv_settings.enable_kds`.
  • The output-job query is enabled only when KDS access is valid and `activeSession.id` exists.
  • `kds:view` can load the board but does not enable `useTPVTerminalRuntime`.
  • The page calls `GET /tpv-output-jobs` with `service_session_id`; KDS job-kind and terminal matching are applied in the page before the runtime receives jobs.
  • The runtime requires `activeTerminalId` and an update callback before mutating output jobs.
  • The runtime excludes `completed`, `cancelled` and `failed` jobs and does not retry failed jobs automatically.
  • The backend validates location, permissions, `terminal_id`, status and JSON payload before saving `PUT /tpv-output-jobs/{jobId}`.
  • KDS-only operators can list or update only `job_kind == kds` output jobs.
  • The local KDS adapter records logical completion in `tpv_output_job`; it does not prove that a physical display rendered or acknowledged the order.

Expected result

Eligible active-service KDS output jobs are claimed by the active terminal and saved as completed with KDS runtime metadata or failed with an error. The saved state can then be reviewed from the TPV Print and KDS queue.

Related articles