docs: wiki update for API docs, printer installer, geenforce cutover, timezone
Execute WIKI-UPDATE-PLAN.md (14 items): - NEW docs/PRINTER-INSTALLER.md: install-list / pc-default / install-batch contract + public installer map page. - NEW-shape docs/API-REFERENCE.md: index + pointer to the live generated docs (/api/docs Redoc, openapi.json, llms.txt, MCP), replacing a stale full dump. - geenforce cutover + GE-ENFORCE-DISPLAY/CLIENT/DEPLOY: server-first display dispatcher (display-role by FQDN, display-type.txt fallback), dashboarddefaults FQDN keying, legacy kiosk autostart self-heal (Wow6432Node), per-PC-type cutover status. - PLUGINS: printers/slides rows + plugin-permissions note (slides.manage). - IMPORT-API: dashboarddefaults FQDN-first keying. - CONFIG: word-wise search, site_timezone setting. - PILOT-DEPLOY: servers-to-network reclassify step. IMPORT-ADOPTION: fixup note. - CLAUDE.md: test count 1077->1159, HTTPS-cutover state. CHANGELOG: timezone + kiosk-autostart fixes, site_timezone setting.
This commit is contained in:
cproudlock
104
docs/PRINTER-INSTALLER.md
Normal file
104
docs/PRINTER-INSTALLER.md
Normal file
@@ -0,0 +1,104 @@
|
||||
# Printer installer map and install endpoints
|
||||
|
||||
How the shop-floor fleet installs network printers from shopdb-flask, replacing
|
||||
the classic ASP `apiprinters.asp` / `apipcdefaultprinter.asp` / `installprinter.asp`
|
||||
contract. Shopfloor 2.0 PCs cannot run unsigned `.bat` maps, so a signed
|
||||
installer EXE (and the public web map page) drives installs from three endpoints
|
||||
in the printers plugin.
|
||||
|
||||
- Server code: `plugins/printers/api/asset_routes.py`
|
||||
(`printer_install_list`, `pc_default_printer`, `printer_install_batch`)
|
||||
- Consumed as a fleet manifest entry: the `common` scope's `printer map`
|
||||
entry (see `GE-ENFORCE-DISPLAY.md`).
|
||||
|
||||
All three endpoints are `@jwt_required(optional=True)`: an anonymous fleet
|
||||
client works, and a logged-in browser (the public map page) works too.
|
||||
|
||||
---
|
||||
|
||||
## 1. The public map page
|
||||
|
||||
`PrinterInstallerMap` is a public (no-login) frontend page: the floor map with
|
||||
printer hotspots positioned at each printer's `mapx` / `mapy`. The user clicks
|
||||
the printers they want, and the page requests an install batch. The PC's default
|
||||
printer is preselected via `pc-default`.
|
||||
|
||||
---
|
||||
|
||||
## 2. `GET /api/printers/install-list`
|
||||
|
||||
Flat, unpaginated list of active NETWORK printers. A printer counts as network
|
||||
only if it has a hostname or a non-USB IP; USB-only printers are excluded.
|
||||
|
||||
Fields per row:
|
||||
|
||||
| Field | Notes |
|
||||
|---|---|
|
||||
| `printerid` | Printer id (the token `install-batch` takes). |
|
||||
| `name` | Asset name, else asset number. |
|
||||
| `machinenumber` | The asset number. |
|
||||
| `windowsname` | Standardized Windows printer name. |
|
||||
| `sharename` | Share / CSF name. |
|
||||
| `hostname` | Print-queue host. |
|
||||
| `ipaddress` | Primary IP (falls back to any communication row). |
|
||||
| `vendorname` | Direct vendor, else the model's vendor. |
|
||||
| `modelnumber` | Model name. |
|
||||
| `installpath` | Installer path for this printer (see install-batch). |
|
||||
| `iscsf` | CSF flag. |
|
||||
| `locationname` | Location name, if the asset has one. |
|
||||
| `mapx` / `mapy` | Floor-map hotspot position. |
|
||||
|
||||
`?format=text` returns a pipe-delimited line per printer, one printer per line,
|
||||
with a fixed field order so the Inno / Pascal installer does a `split()` instead
|
||||
of parsing JSON:
|
||||
|
||||
```
|
||||
printerid|windowsname|vendorname|modelnumber|hostname|ipaddress|mapx|mapy
|
||||
```
|
||||
|
||||
Any pipe or newline inside a value is neutralized to a space so the field count
|
||||
stays fixed. The web map uses the default JSON.
|
||||
|
||||
---
|
||||
|
||||
## 3. `GET /api/printers/pc-default?machine=NNNN`
|
||||
|
||||
The PC's default printer, by machine (asset) number persisted at PXE enrollment.
|
||||
Parity with classic `apipcdefaultprinter.asp`: the installer preselects a PC's
|
||||
default-printer hotspot on the site-map wizard. The link is resolved through the
|
||||
`defaultprinter` asset relationship (PC asset -> printer asset), so it stays
|
||||
inside the contract surface (no cross-plugin model import).
|
||||
|
||||
Returns `{printerid, windowsname}`, or `{}` when the machine is unknown or has no
|
||||
active default printer set.
|
||||
|
||||
`?format=text` returns one pipe-delimited line (`printerid|windowsname`), or an
|
||||
EMPTY body when there is no default (so the installer's split yields nothing).
|
||||
|
||||
---
|
||||
|
||||
## 4. `GET /api/printers/install-batch?printerids=1,2,3`
|
||||
|
||||
Returns a self-deleting Windows `.bat` that installs the selected printers,
|
||||
grouped the same way classic `installprinter.asp` grouped them:
|
||||
|
||||
- HP / Xerox: one universal `PrinterInstaller.exe /PRINTER="a,b,c"` call.
|
||||
- Printers with a `.exe` `installpath`: a PowerShell `Invoke-WebRequest` download
|
||||
(using the caller's Windows credentials, against the site base URL + the
|
||||
IIS-served `/installers` folder) followed by running it `/SILENT`.
|
||||
- No `installpath`, or a non-`.exe` payload (e.g. a `.zip`): listed as a manual
|
||||
install rather than run blindly.
|
||||
|
||||
`printerids` is required, comma-separated; non-numeric tokens are ignored. An
|
||||
empty / missing list is a validation error.
|
||||
|
||||
The install name preference is `windowsname`, else `sharename`, else the asset
|
||||
name / number.
|
||||
|
||||
---
|
||||
|
||||
## 5. Fleet wiring
|
||||
|
||||
The `common` scope's `printer map` manifest entry (see `GE-ENFORCE-DISPLAY.md`)
|
||||
lays down the signed installer that consumes these endpoints. The web map page
|
||||
covers the same install flow for a human at a browser.
|
||||
Reference in New Issue
Block a user