shopdb-flask/docs/proposals/printer-assignment.md

Proposal: assign printers to a machine in ShopDB, let the PC install them

Status: SHIPPED AND RELEASED. Built out 2026-08-18/19; the client script is built too. The feature itself released in v0.11.3, the observation half and seed-from-observed adoption in v0.12.0. Author: planning session 2026-08-18.

One thing this proposal did NOT anticipate, resolved 2026-08-24 in adc7ef4: the computers collector carried a _sync_printer_links that wrote defaultprinter / connectedto rows straight from a PC report, which is the ASSIGNED-vs-OBSERVED split this proposal rests on, broken from the other end. It is retired; defaultprinter and printers are now ignored (not rejected) on the collector payload. See COLLECTOR-INTEGRATION.md.

1. What this is

Today a printer reaches a shop-floor PC because a person walks up to it, opens the printer installer, finds the printer on a floor plan and clicks it. That is fine for someone choosing a printer, and wrong for a bay whose printers are a property of the bay.

This proposal makes the assignment data. The printers belong to the MACHINE, not to the box currently driving it: tick the printers that belong on the machine, mark one default, and the assignment reaches whichever PC controls that machine. The PC converges on its next GE-Enforce cycle - installing what is missing and setting the default - and keeps converging, so a reimaged bay comes back with its printers and a bay that drifts is corrected.

The point of putting the assignment on the machine is that a reimaged PC needs no backup and no restore step. The asset register is the source of truth, and a replacement PC that inherits the controls edge inherits the printers with it.

The map installer stays, for the case it is actually good at: a person at an unmanaged or office PC picking a printer that nobody assigned.

2. Why it is worth doing

• The assignment becomes a record. "Which printers does that bay have" is a question ShopDB can answer, and today it cannot.
• A reimage stops costing a visit. The bay reinstalls its own printers, from the machine's record, with nothing saved off the old PC.
• Swapping the PC keeps the printers. They were never the PC's.
• Drift is corrected, not just detected. A queue deleted by a user comes back.
• It removes the walk-up from the common case. The installer's map remains for the uncommon one.

3. What already exists

Most of the model is in place, which is why this is a small feature rather than a project.

piece	state
PC to printer link	defaultprinter asset relationship, seeded by flask seed reference-data
Propagation mechanism	RelationshipTypePropagation (ADR-001): "type X propagates through connections of type Y"
A working precedent	resolve_asset_position walks partof then controls to give a PC the machine's map position
Default lookup	GET /api/printers/pc-default?machine=NNNN
Host lookup	GET /api/computers/by-hostname/<hostname>
Printer model	Printer.modelnumberid - populated for 44 of 44 printers at the reference site
Driver record	PrinterDriver (name, location as SMB path or URL, optional modelnumberid)
Per-printer install path	Printer.installpath
Batch install	GET /api/printers/install-batch?printerids=1,2,3
Client transport	GE-Enforce manifest entries, Type=PS1, running as SYSTEM every cycle
Silent driver staging	Proven in PrinterInstaller.iss: trust the catalog's signing cert, then pnputil /add-driver

4. The data model

4.1 One new relationship type

usesprinter, directional, source -> printer, meaning "this printer is installed here". It is seeded next to defaultprinter, which already exists and means "which of them is the default". Both are seed data, not a migration, which is how every other relationship type shipped.

4.2 Two propagation rails, consumed at READ time

usesprinter propagates through controls, and so does defaultprinter. Both are rows in relationshiptypepropagations, the same mechanism map positions use. Inventing a second mechanism for this was the alternative, and it was rejected.

The rails are inert at write time on purpose. The create-time fan-out (propagate_relationship) skips directional through-types, and controls is directional, so assigning a printer to a machine does not copy rows onto its PC. The walk happens when something asks, which is what makes the next rule possible.

4.3 Resolution order for a PC

1. The PC's OWN active usesprinter / defaultprinter rows, if it has any.
2. Otherwise, one hop out along its controls edges to the machines it drives, and those machines' rows instead, tagged as inherited.

Own beats inherited, whole set at a time: a PC with its own assignment is overriding the bay, not adding to it. An office PC controls no machine and still works, because step 1 is the normal case for it.

The override is a real trap and the UI has to say so. A tech who "fixes" a bay by editing the PC has shadowed the machine's record, and the machine will keep disagreeing until someone clears the PC's own rows.

4.4 One default, optional, and never dangling

The unique constraint is (source, target, type), which happily accepts two different defaults. So the rule is enforced in the API on write:

• Exactly one defaultprinter per asset. Setting a default replaces the existing one.
• A default is OPTIONAL. A bay with three printers and no default is valid.
• The default must be one of the assigned printers. Unassigning the printer that is currently default clears the default rather than leaving it dangling.

4.5 One column on printerdrivers

drivername - the driver's exact name as the INF declares it, e.g. HP Universal Printing PCL 6. Add-PrinterDriver matches on that string, not on name, which is ours to choose, and a mismatch is the usual failure. Deriving it by parsing the INF on hundreds of bays is fragile; a human confirming it once in ShopDB is not.

It is a plugin-chain migration (printers0003drivername), nullable, guarded so a re-run is a no-op. printerdrivers was created by a core migration but its DDL moved to the printers chain at the ADR-008 cutover.

The installmethod column (pnputil or dpinst) proposed earlier is NOT being built. See section 8: if production confirms no Brother printers, everything is pnputil and the column has no second value to hold.

5. What has to be built

5.1 A resolution helper in core

The read-time walk of section 4.3, beside resolve_asset_position and exported on the shopdb.api contract surface (an additive minor bump). It has to live in core because RelationshipTypePropagation is not on the contract surface, and a plugin may not reach past it (ADR-002).

The through-type comes from the seeded rails, not from a hardcoded 'controls', so a site that adds a rail gets the behaviour without a code change.

5.2 Two endpoints

GET /api/printers/for-host/<hostname>

The desired printer set for one PC, resolved per section 4.3, each entry with what a client needs to install it: queue name, host or IP, port, driver name, driver location, and which one is default.

Resolved by hostname, not machine number: the collector already upserts PCs by hostname, and an office PC has no machine number. Matched case-insensitively - COMPUTERNAME is uppercase and MySQL forgives that where SQLite does not.

An unknown host, a site without the computers plugin, or nothing assigned all return an empty set. That is the client's designed no-op and it must stay indistinguishable from "assigned nothing".

PUT /api/printers/assignments/for-asset/<asset_id>

The whole assignment for one asset - machine or PC - in one call: {printerassetids: [...], defaultprinterassetid: N|null}. It reconciles rather than inserting: rows that went away are soft-deleted, rows that come back REACTIVATE the soft-deleted row (the unique constraint spans inactive rows, so a blind insert is an integrity error on assign, unassign, re-assign), new rows are created, and the single default is replaced.

The rules in 4.4 hold here or nowhere. Row-at-a-time writes through the generic relationships path leave two-default windows and know nothing of the subset rule.

Removing an assignment NEVER uninstalls anything. Server-side the row simply goes: no cascade, no side effects, nothing queued for the client to undo.

Per-PC assignments must NOT go in the manifest. Manifests are keyed by scope and PC type and sync broadly; putting per-PC rows there would leak every bay's configuration to every bay and grow without limit. One manifest entry runs one script that asks the API what THIS host gets - the mirror image of Report-AssetToShopDB.ps1.

5.3 UI on the PC form

A printer multi-select plus a default dropdown whose options are only the currently selected printers, clearing itself when its printer is deselected. Saved through the reconcile endpoint against the PC's asset.

The computers plugin does not depend on the printers plugin and must not start: the section hides itself when the printers API is not there.

The machine-side picker is out of scope for now, which means the machine's assignment is editable only through the generic relationships card. That is the side the design says is primary, so it is the obvious next piece of UI.

5.4 One client script, in two contexts

Set-ShopdbPrinters.ps1, shipped in plugins/printers/client/ beside the contract it consumes, and run as a manifest entry with DetectionMethod=Always.

As SYSTEM, every cycle:

1. GET /api/printers/for-host/$env:COMPUTERNAME
2. For each assigned printer with no queue: trust the driver catalog's cert, pnputil /add-driver, create the port, create the queue
3. Write the desired default to HKLM:\SOFTWARE\GE\ShopDB DefaultPrinter
4. Ensure the per-user task exists

In the user's context, at logon and on a repeat:

5. Read that value, compare with the current default, set it if it differs, and clear "Let Windows manage my default printer" - otherwise Windows silently overrides the choice the next time someone prints elsewhere

The default printer is per-user state, which is the only reason this needs two contexts. Everything else is machine state and belongs to the cycle.

Converge, do not reinstall: when the state matches, the script does nothing. Nothing here needs the manifest to know when a printer changes, because the desired state is fetched, not declared.

6. Desired state and observed state are not the same thing

Everything above is DESIRED state: what SHOULD be installed on a PC. Nothing in this feature knows what IS installed on it. The client reads the desired state, converges toward it, and reports nothing back.

Reporting the observed state is the obvious next feature and is deliberately not this one. If the collector sent the installed queues per host - name, port, driver, which is default - then comparing that against the resolved assignment gives drift detection for free: "this bay is missing the label printer", "this PC has three queues nobody assigned", "the default is not the assigned one".

Keeping them apart is a rule, not a preference:

• Observed data never writes usesprinter rows. A register that learns from what it finds mirrors the drift instead of correcting it, and the fault becomes the desired state.
• Observed data belongs on the computer record, timestamped, like the rest of the collector payload. It is an observation with an age, not a decision.
• An empty answer from the API means "nothing assigned", not "nothing installed", which is exactly why section 5.2 refuses to make removal uninstall anything.
• The two can disagree indefinitely and that is a report to read, not an error to resolve automatically.

7. Decisions to take before writing the client

1. Never remove a queue by default. A transient API failure would otherwise strip printers fleet-wide. Deletion is an explicit opt-in, per PC.
2. Enforced or set-once for the default? Re-applying every cycle overrides a user who chose their own default - correct for a locked bay, irritating on an office PC. Set-once is Active Setup or RunOnce. Make it a per-PC-type flag rather than one global answer.
3. Failure is silent and safe: unreachable API means change nothing, log, exit 0 - the convention Report-AssetToShopDB.ps1 already follows.

Open on the server side, and each one changes the response contract:

4. How a universal driver resolves. PrinterDriver links to a printer by exact modelnumberid, and the target state is roughly four rows dominated by HP UPD and Xerox GPD, which match no single model. Either the driver row gains a vendor, or a modelnumberid IS NULL row matches on the printer's resolved vendor name. Until this is settled, for-host returns no driver for 41 of 44 printers.
5. What port means when it is null. RAW 9100 is the obvious default; whose job it is to apply it - server or script - has to be written down once.
6. Who may read for-host. pc-default and install-list are anonymous; the collector and the GE-Enforce fetch use scoped service tokens. This one discloses per-PC configuration keyed by hostname.
7. Two inherited defaults. A PC can legitimately control both bays of a dual-bay machine, or several machines. The union of assigned printers is easy; the default needs a deterministic rule, or none when it is ambiguous.
8. Legacy defaultprinter rows have no usesprinter row, because they predate the type. Either an active default implies assignment on read (zero-touch, preferred) or a one-time backfill writes the missing rows. Otherwise existing defaults vanish from for-host while still showing in pc-default.
9. Deletions through the generic relationships card bypass the reconcile endpoint and can strand an active default pointing at an unassigned printer. Either the resolver drops dangling defaults or the core delete path learns the rule.

8. What the fleet data says, and the one prerequisite

The reference site's 44 printers are HP 26, Xerox 15, Zebra 1, HID 1, Epson 1.

• HP and Xerox are 41 of 44, and both have true universal drivers (HP UPD, Xerox Global Print Driver). One driver record each serves every queue of that make.
• There are no Brother printers at all, yet the installer carries 208 files of per-model Brother MFC-J inkjet drivers. Those are host-based GDI devices with no Printer-class INF, which is the only reason a second staging method (DPInst) exists. If production confirms no Brother, that payload and that code path can both go - and with them the installmethod column.
• Zebra, HID and Epson are one printer each, and the HP DesignJet plotter is a fourth special case - a PostScript device the UPD does not cover.

Prerequisite: populate printerdrivers. It currently holds ONE row, and it points at a per-model folder (HP LaserJet Pro M607 Driver) rather than the universal driver - the opposite of how a UPD should be used. The table needs roughly four rows: HP UPD, Xerox GPD, one per oddity, and DesignJet when its payload is restored. Each needs drivername copied verbatim from its INF. Nothing in this proposal works until a printer can resolve to a driver.

9. Deployment constraint that shapes the design

The SFLD share is mounted only during GE-Enforce's cycle. Any work touching a share path must run as a manifest entry inside that cycle, never as its own scheduled task. The failure is silent - the task reports 0 processed, 0 installed, 0 failed - and it has cost a session before.

This is why driver staging belongs in the cycle even though the per-user default does not, and why "the assignment script schedules a task that installs drivers" is the wrong shape.

10. Upgrading an existing site

Three steps, and the third is the one that gets forgotten:

1. flask db upgrade - no core migration in this feature, but a deploy runs it.
2. flask plugin upgrade-all - applies drivername. Skipping it is the classic 1054 unknown-column error.
3. flask seed reference-data - REQUIRED. Without it the usesprinter type and both propagation rails do not exist, and for-host resolves nothing, quietly, because empty is also the healthy answer.

Pair the upgrade with a smoke check against a known bay. A site with reversed legacy controls rows (machine -> PC) should run flask relationships fix-controls-direction first, or inheritance resolves for none of those PCs.

11. What this does not change

• The printer installer keeps working, for walk-up and self-service.
• Nothing about how printers are modelled, mapped or reported.
• The collector contract. Section 6 would change it; this feature does not.
• Sites not running GE-Enforce: the same endpoint suits an Intune remediation or a DSC Script resource, since it is a plain HTTP GET and a PowerShell script.