# 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.