534f179ee6
main was 16 days and 259 commits behind the line the product is actually built on, at contract 0.30.0 against 0.35.0, with no per-PC credential code at all. It was neither current nor curated - just stale. This brings it forward and, at the same time, makes it mean something: main is what a receiving site installs, and nothing else. WHAT IT CARRIES. Twelve plugins - backups, computers, endpoints, guides, knowledgebase, machines, network, notifications, printers, slides, tools, warranty - plus applications, which is manifest-less core and always ships. The only manifest dependency inside that set is endpoints on computers, and both are in it, so the closure is self-contained. WHAT IT DOES NOT. employees, geenforce, measuringtools, printedparts and usb stay on the site line. So do the Windows installer tree, the VM rehearsal helpers, the agent tooling config, one site's data loader, the internal audit and findings records, and the planner spreadsheet. 1,135 tracked files against 1,438. A REMOVAL THAT BREAKS THE APP IS NOT A REMOVAL, and two nearly shipped: deploy/site-profile-universal.json still named all seventeen plugins. It is the file docs/DEPLOY.md tells a site to provision from, so a fresh install would have failed at `flask plugin apply-profile` with PluginError - the first thing a receiving site does, broken by the branch meant to serve them. It now names the twelve that exist, and its comment says the two must agree. agent/ was never refreshed. Whoever populated this branch copied shopdb/, plugins/, frontend/ and tests/ from the site line and left the agent tree at its September state: 22 C# and PowerShell sources missing, including AgentCredentials, EnrollmentService, AgentHttpFactory and the fleet-alert client, plus one file the site line had deleted still present. The old tree is internally consistent, so it compiles, and nothing in CI builds it - every gate was green over a server that speaks enrollment and per-PC credentials to a bundled agent source that cannot. Resynced whole. DECISIONS THIS ENCODES, rather than defers: - The plugin-authoring lab builds printedparts, whose manifest depends on employees, so it could not stay. The lab remains on the site line and main ships no build-along tutorial. That is a real loss for an adopting developer and is recorded here rather than discovered later. - Recognition, Training and Recertification notifications are no longer seeded. Each splits one notification into a card per employee and renders a photo, which needs a plugin this branch does not bundle. Seeding them would offer an author a type that cannot resolve anybody. A site that installs employees gets them from that plugin's own seed. - Windows/IIS is documented as the legacy path throughout, and the README leads with Docker, because that is what a receiving site gets. The API description is regenerated for THIS branch - 347 paths and 483 operations, down from 415 and 573 - so the published contract describes what is here rather than what the site line serves. docs/CONFIG.md lost the two measuring-tool label keys the code no longer declares, which two lanes had decided opposite ways. Suite: 3124 passed, 6 skipped. Naming and style gates pass. The docs gates run rather than skip, and every index line count is derived from the file it names.
140 lines
5.1 KiB
Markdown
140 lines
5.1 KiB
Markdown
<!-- docmeta
|
|
purpose: howto
|
|
audience: adopter, operator
|
|
status: current
|
|
summary: Load a new site's starting data from generated CSV templates, with no developer and no source database.
|
|
loadwith:
|
|
-->
|
|
|
|
# Loading a site's data from spreadsheets
|
|
|
|
**Four import pages.** Spreadsheet and no developer: this page. The HTTP wire
|
|
contract: [IMPORT-API](IMPORT-API.md). How to shape a per-site loader around
|
|
it: [IMPORT-ADOPTION](IMPORT-ADOPTION.md). Source is the classic-ASP shopdb:
|
|
[IMPORT-LEGACY-ASP](IMPORT-LEGACY-ASP.md) on top of the contract.
|
|
|
|
---
|
|
|
|
## The short version
|
|
|
|
```bash
|
|
cd C:\shopdb-flask # or your install directory
|
|
venv\Scripts\flask csv templates --out csv-templates
|
|
```
|
|
|
|
Fill in the templates. Then:
|
|
|
|
```bash
|
|
venv\Scripts\flask csv import --dir csv-templates
|
|
```
|
|
|
|
That **checks only** and changes nothing. It tells you what it would create and
|
|
what is wrong. When you are happy:
|
|
|
|
```bash
|
|
venv\Scripts\flask csv import --dir csv-templates --commit
|
|
```
|
|
|
|
---
|
|
|
|
## Write names, not numbers
|
|
|
|
This is the part that makes the difference. Every column that points at another
|
|
table accepts the **name** of the thing:
|
|
|
|
```
|
|
assetnumber,name,assettypeid,statusid,locationid
|
|
CMM-01,Zeiss Contura,Machine,Active,Gage Lab
|
|
MILL-07,Haas VF-2,Machine,Active,Bay 3
|
|
```
|
|
|
|
`assettypeid` gets `Machine`. `locationid` gets `Gage Lab`. You never
|
|
have to import a file, read back the numbers it generated, and paste them into
|
|
the next one.
|
|
|
|
The column keeps its database name so it matches the rest of the system, but
|
|
the value is whatever you actually know. Numeric ids still work if you have
|
|
them - useful when re-importing something this system exported.
|
|
|
|
Names resolve **across files in the same run**, so `assets.csv` can reference a
|
|
location that only exists because `locations.csv` was loaded moments earlier.
|
|
|
|
## Nothing is half-imported
|
|
|
|
Every row is checked before anything is written. If one row is wrong, nothing is
|
|
written at all - you fix the file and run it again. A mistake on line 400 never
|
|
leaves 399 rows loaded.
|
|
|
|
## Running it twice is safe
|
|
|
|
Each file is matched on a natural key - `assetnumber` for assets, `locationname`
|
|
for locations, and so on. Re-importing an edited file **updates** those rows
|
|
rather than creating second copies. Correcting a spreadsheet and re-running is
|
|
the expected workflow, not a mistake.
|
|
|
|
## What the errors look like
|
|
|
|
```
|
|
assets: 0 new, 0 updated, 1 problem(s)
|
|
line 4, column 'locationid': nothing in locations is named 'Bay 9'
|
|
- add it to locations.csv, or import that file first
|
|
```
|
|
|
|
Line, column, value, and what to do. Not a foreign key constraint violation.
|
|
|
|
---
|
|
|
|
## What you can import
|
|
|
|
Fourteen tables. `flask csv templates` writes one file per table and `--dir`
|
|
imports them in dependency order, which is the order the generated folder lists
|
|
them in: assetstatuses, assettypes, locationtypes, modeltypes, computertypes,
|
|
machinetypes, businessunits, locations, vendors, models, operatingsystems,
|
|
assets, computers, machines. The authoritative list, with each table's natural
|
|
key, is `IMPORTABLE` in `shopdb/core/services/csvimport.py`.
|
|
|
|
You only need the files you have; skip any you do not care about. Use `--file`
|
|
with `--table` for a single file out of order.
|
|
|
|
**User accounts are deliberately not importable.** Passwords do not belong in a
|
|
spreadsheet, in either direction. Create the first administrator through the
|
|
first-run page and the rest in the application.
|
|
|
|
## The templates are generated, not maintained
|
|
|
|
`flask csv templates` builds them from the live database schema each time, so
|
|
every column offered exists, every required one is marked, and every foreign key
|
|
says which file it refers to. Do not hand-maintain a template set: the one that
|
|
was tried had invented columns on seven of eleven tables and named a table that
|
|
does not exist, while looking entirely plausible. A test fails the build if the
|
|
generated set ever drifts from the schema.
|
|
|
|
## Editing the files
|
|
|
|
- **UTF-8**, no BOM. Excel: "CSV UTF-8 (Comma delimited)".
|
|
- Lines starting with `#` are ignored, so the notes at the top of each template
|
|
can stay where they are.
|
|
- **The example rows are not comments. Delete them.** Each template carries a
|
|
worked example set as LIVE rows, so that a freshly downloaded folder imports
|
|
cleanly as a demo. Import it with your own data still in it and you get
|
|
`PC-001`, `CNC-014`, `Dell` and `Bay 3` in your database. The template says so
|
|
in its own header.
|
|
- Booleans are `1` or `0`.
|
|
- Dates are `YYYY-MM-DD` (`2026-08-04`). `YYYY-MM-DD HH:MM:SS` also works, as do
|
|
`DD/MM/YYYY` and `MM/DD/YYYY`.
|
|
- Leave a cell **empty** for "no value". Not `NULL`, not `N/A`.
|
|
- Quote anything containing a comma: `"Bay 3, North"`.
|
|
|
|
## If it will not run
|
|
|
|
**"the 'assets' table does not exist in this database"** - the schema has not
|
|
been created. Run `flask db upgrade` first, and check `DATABASE_URL` points at
|
|
the site you meant.
|
|
|
|
**"unknown column(s): ..."** - a column that does not exist, usually from an
|
|
older template. Regenerate with `flask csv templates`; the message lists what
|
|
the table does accept.
|
|
|
|
**"required column(s) missing: ..."** - a column that must be present has been
|
|
deleted from the header. Regenerate and copy your data across.
|