CSV fleet importing

Format and mapping

Upload UTF-8 CSV with unique nonempty headers. Quoted commas, escaped quotes, CRLF, a UTF-8 BOM and Unicode are supported. Maximum: 4 MiB, 10,000 rows, 32 columns and 8,192 characters per cell.

Map columns to name (required), external_id, serial_number, description, metadata, lifecycle, group or tags. Metadata is a JSON object of at most 4 KiB; put location/type/customer attributes there. Group names must already exist in this workspace. Tags are comma-separated; quote the CSV cell when it contains commas. Schema source/slot is chosen for the whole import. Credentials cannot be mapped or imported.

name,external_id,serial_number,group,tags,metadata
Factory Sensor 001,unit-001,SN001,Factory A,"production,outdoor","{""location"":""north""}"
Factory Sensor 002,unit-002,SN002,Factory A,testing,{}

Validation and duplicates

The browser previews mapped rows; the server validates again. Invalid values stop preview creation with a row number. Correct them before confirming. The persisted preview includes counts of existing identities and the maximum new-device count.

Reject duplicates reports identity collisions as failed job items; Skip leaves existing records untouched; Update approved metadata changes description and metadata only. It does not replace credentials, names, protocol identity or schemas. External-ID and serial collisions that refer to different existing records are rejected. Row ordering is deterministic, so later duplicates are handled by the selected policy.

Device names are display labels and are not unique identities. Include stable external IDs or serial numbers for repeatable manufacturing/import runs. Request IDs make repeated submission of the same preview idempotent.

Results and recovery

Inspect created, updated, skipped and failed items in Bulk jobs. Reports never contain secrets; spreadsheet formula prefixes are escaped. No uploaded raw CSV file is stored. Normalized row data remains in the job until cleanup.

Retry eligible failures creates a new preview. It never reruns completed items automatically. A plan or permission change during execution can fail remaining items safely. Resolve the cause, review the affected rows and confirm another attempt.