Saltar al contenido principal

Desktop: identifying a machine

How to answer "which computer is this?" from device records, and what the answer does and does not let you see.

Feature 054-desktop-runtime-shell — FR-018a, FR-021, FR-022, FR-023, FR-023c.

The identifier​

Every desktop installation generates one installation identifier the first time it runs, and keeps it for the life of that installation. It is stored in the operating system's credential store, or in an encrypted file where there is none. Nothing generates it at install or build time, so a shop that images one machine and clones it onto twelve tills gets twelve identifiers rather than one device fighting itself.

It appears on kds_device.installation_id, and on the status window under Installation, which is the fastest way to get it from a merchant on the phone.

One machine, one record per business​

A desktop installation has at most one device record per business, whatever it is doing. A machine used as a till and as a print agent is one row with both roles, not two rows.

A station claim is not a device record. An installation serving three stations is one device holding three claims. If you are looking at something that appears to be three devices for one machine, it is either three OS user accounts (below) or a bug — it is not what claims look like.

Correlating one machine across businesses​

A merchant can sign the POS window in to any business their account belongs to, whether or not the machine is paired to it. When they do, that business gets its own device record, carrying the till role and sharing the installation identifier.

So to find every record for one physical machine:

SELECT business_id, location_id, device_name, roles, is_active, created_at
FROM kds_device
WHERE installation_id = $1
ORDER BY created_at;

Run this as support tooling, against the database. No API returns it. Every device-facing and merchant-facing endpoint is scoped to one business, and none of them accepts an installation identifier as a lookup key. That is deliberate: two businesses sharing a machine is common — a shopkeeper who runs two companies from one counter — and neither of them may learn anything about the other's row, including that it exists.

If you need to tell a merchant about a record, tell them about their own.

Two accounts on one computer are two machines​

The installation identity is scoped to the operating-system user profile, because both the credential store and the application's data directory are per-user. Two Windows accounts on one physical computer are therefore two installations, two identifiers, two device records, and two queues.

This surprises operators, so say it before they ask: two rows naming the same computer are usually two accounts, not a duplicate to clean up. Deactivating one because it looks redundant will stop whatever that account was printing.

Confirmed on Windows during spike S5: an administrator account and a standard account on one machine produced different identifiers.

A shop that wants exactly one print agent per machine must run it under one account. Two accounts each running the agent are two devices competing for the same stations. Arbitration handles that correctly — one of them wins each station — but the result is not what anybody expects from one computer.

A machine-scoped identity, which is what an agent running as a service before login would need, is deliberately out of scope for this version.

A reinstall​

An installation that loses its identifier — a wiped profile, a fresh Windows install, a new user account — registers as a new device. The previous record stays, active and visible.

That is on purpose, and it is the state most likely to look like a bug:

  • Reusing the old record would attach a new machine's claims to an old machine's history.
  • Deleting it would erase the evidence of what that machine did, which is usually the thing being investigated.

So the old row is left for an operator to retire deliberately. Expect to see two rows with the same device_name and different installation_id after a reinstall, and retire the older one once you have confirmed it is not still printing.

What the device name is for​

device_name is the machine's own name — WIN-POS-04, not "a desktop". It exists so that a claim conflict, a support ticket, or a row in this table names something a person can walk up to. If you see a record named "FlowPOS Desktop", the machine did not report a name, and the merchant will not be able to tell you which one it is.