shopdb-flask/docs/CSV-IMPORT-GUIDE.md

ShopDB CSV Import Guide

Short version: one CSV per table, a header row of exact column names, one record per row. The importer matches on natural keys, so re-importing updates instead of duplicating.

IMPORTANT: assets.csv alone will NOT show up in the lists

An assets.csv row only creates the base asset record. A computer, machine, or measuring tool does NOT appear in its list view (PCs, Machines, Measuring Tools) until its matching subtype row is also imported:

• A computer asset needs a row in computers.csv (assetid = the asset's assetnumber) before it shows under PCs.
• A machine asset needs a row in machines.csv before it shows under Machines.
• A measuring-tool asset is managed by the Measuring Tools plugin, not the native subtype importer, so it will exist as an asset but will not appear in the Measuring Tools list from assets.csv alone.

So always import the subtype file (computers.csv / machines.csv) right after assets.csv. Importing only assets.csv leaves the records invisible in the typed lists even though they are in the database. (The Azure and Thor imports do both steps automatically, which is why Azure/Thor PCs appear immediately.)

Rules for hand-built native CSVs

1. First row is the header. Use the exact column names below, lowercase, no spaces.
2. Include every REQUIRED column. Other columns are optional; drop the ones you do not use.
3. Foreign keys are entered by NAME, not id. Put the human name and the importer resolves it: assettypeid=machine, statusid=In Use, locationid=A1, vendorid=Haas Automation. The referenced record must already exist (import lookup tables first, see order below).
4. Booleans (isactive, etc.) are 1/0 or true/false. Leave blank for the default.
5. Dates are YYYY-MM-DD. Leave blank if unknown.
6. Leave a cell blank to skip it. Do not type NULL or N/A.
7. Save as UTF-8 CSV, comma-separated. ASCII only (no smart quotes, no em-dashes).

Import order (dependencies first)

assetstatuses, assettypes, locationtypes, modeltypes, computertypes, machinetypes, businessunits, locations, vendors, models, operatingsystems, assets, computers, machines.

An asset row must exist before its computers/machines subtype row: the subtype links back with assetid (the asset's assetnumber). Import the subtype file in the same session so the item appears in its list (see the IMPORTANT note above).

Columns (REQUIRED in bold)

• assetstatuses: status, description, color, isactive
• locationtypes: locationtype, description, color, isactive
• modeltypes: modeltype, category, description, icon, isactive
• computertypes: computertype, description, icon, color, isactive
• machinetypes: machinetype, description, icon, color, isactive
• businessunits: businessunit, code, description, parentid, isactive
• locations: locationname, building, floor, room, description, locationtypeid, parentlocationid, isactive
• vendors: vendor, description, website, supportphone, supportemail, notes, isactive
• models: modelnumber, modeltypeid, vendorid, description, notes, isactive
• operatingsystems: osname, osversion, architecture, endoflife, isactive
• assets: assetnumber, assettypeid, name, serialnumber, gaugelabreference, maintenancereference, statusid, locationid, businessunitid, notes, isactive
• computers: assetid, computertypeid, hostname, osid, vendorid, modelnumberid, loggedinuser, isactive
• machines: assetid, machinetypeid, vendorid, modelnumberid, requiresmanualconfig, islocationonly, lastmaintenancedate, nextmaintenancedate, maintenanceintervaldays, controllervendorid, controllermodelid, isactive

Measuring tools are assets: add an assets row with assettypeid=measuring_tool.

Example (assets.csv)

assetnumber,name,serialnumber,assettypeid,statusid,locationid
MILL-01,Haas VF-2 Mill,SN1001,machine,In Use,A1
PC-01,Shopfloor PC 01,SN2001,computer,In Use,B1
MIC-01,Mitutoyo Micrometer,SN3001,measuring_tool,In Use,Gage Lab

Then machines.csv links the machine subtype:

assetid,machinetypeid,vendorid
MILL-01,Mill,Haas Automation

Azure and Thor exports (do NOT edit)

For Azure (Entra device-group) and Thor (PC inventory) files, upload the export AS-IS. The importer auto-detects them by their header and extracts the fields it needs. Do not rename headers, reorder columns, add/remove rows, or reformat cells. Editing the export breaks auto-detection.