When you have tens or hundreds of devices, add them from a CSV file instead of one by one. Every import is checked first (“Every import is dry-run first: nothing is written until somebody reviews what would happen.”), then applied, and it can be undone. New devices get their credentials at once, delivered in a file you can download one time.
Imports are made on the Imports page (address /admin/settings/imports, in the Organisation part of the menu). The page is there when the import module is on in your organisation. You need the permission to create devices.
Prepare the file
The file is CSV, saved as UTF-8, separated by commas, semicolons or tabs, with the column names on the first line. Up to 1,000 rows per file. Select Download a template in the import wizard to get a file with every column and one example row.
| Column | Meaning | Rules |
|---|---|---|
name | Device name (unique in this account) | Required. |
label | Label | Optional free text. |
type | Device type | Optional, for example pump-controller. |
profile | Device profile name (empty = the default profile) | The profile must exist. |
serial | Serial | Optional, up to 32 characters from A–Z a–z 0–9 . _ : -. Unique on the platform. |
mac | MAC address | Optional. Kept in the device’s additional info. |
credentialType | Credential type (empty = ACCESS_TOKEN) | ACCESS_TOKEN or MQTT_BASIC. X.509 is never imported. |
mqttUsername | MQTT username (MQTT_BASIC; empty = generated) | Unique on the platform. |
mqttClientId | MQTT client id (MQTT_BASIC, optional) | 1 to 64 characters from A–Z a–z 0–9 . _ : -. |
attr:<key> | A server attribute | Up to 50 attribute columns, values up to 4,096 characters. |
shared:<key> | A shared attribute | As above. |
Example:
name,label,profile,serial,credentialType,attr:maxTemp,shared:cfg.report_interval_s
pump-house-01,Pump house north,Water pumps,SN-000123,ACCESS_TOKEN,80,300
pump-house-02,Pump house south,Water pumps,SN-000124,MQTT_BASIC,75,300Warning
Never put a secret in the file. A column named like a secret (token, password, secret, key, credential, claim code) is refused, and so is a cell that looks like an access token. Hermetry creates the credentials itself.
Import
- Open Imports and select New import.
- File: under What to import, pick IoT devices, choose the CSV file, and keep The first line holds the column names on. The wizard shows how many rows it found.
- Columns: check that each field has the right column of your file (“Columns with matching names are already filled in.”). Columns starting with
attr:orshared:are taken as they are. Choose When a record already exists:
| Strategy | Effect |
|---|---|
| Only add new records; report the existing ones | A name that exists is an error. |
| Only update existing records | Only existing names are changed; the rest are skipped. |
| Add new records and update existing ones | Both. |
| Add new records and skip the existing ones | Existing names are skipped. |
- Select Check the file. Every row is checked; nothing is written yet. The Check step shows Rows in the file, Ready to import, Will be skipped and Have a problem, with Rows with a problem (Row, Field, Problem).
- Fix the file and Pick another file, or select Import n rows and confirm. Rows with a problem are left out.
What the check refuses
| Problem | Meaning |
|---|---|
| The name appears more than once in this file. | Each name once per file. Serials and MQTT usernames too. |
| No device profile is called “…”. | Create the profile first, or leave the column empty for the default profile. |
| A device called “…” already exists. | Choose “skip duplicates” to import only new rows, or “update” to change existing devices. |
| An import does not change the serial of an existing device. | Serials are fixed. |
| The profile “…” does not allow … | The profile does not allow the credential type. Pick another profile or credential type. |
| A device with this serial is already registered. | A licensed unit is added by claiming it, not by import. |
| This MQTT username is already in use. | Usernames are unique on the platform. |
Your plan’s device limit is checked for the whole file before anything is written: a file that does not fit is refused whole, with the numbers.
What an update changes
An update changes the label, type, profile, MAC address and the attributes, and remembers the old values for undo. It never changes a serial or a credential (“The credential of an existing device is not changed by an import; renew it from the device page.”). Uploading the same file again is safe: nothing is created twice and no credential is made again; the wizard warns that the exact file was imported before.
Download the credentials
After an import that added devices, the Result step offers One more step: Download the new devices’ credentials. “The access tokens and MQTT passwords of the devices this import added, in one file you can download once, within 15 minutes of the import. Keep it safe: it is not shown again.”
- Only the person who ran the import can download it.
- After the download, or after 15 minutes, it is gone (“Done. This cannot be repeated.”).
- A device whose file was lost gets new credentials on its own page with Rotate secret.
Undo
The Result step and the imports list offer Undo this import: “Records it added are removed and records it changed are put back as they were.” For devices:
- a created device is removed only while it has never connected,
- an updated device is put back from the values it had before the import.
Rows that cannot be put back are counted (“n rows could not be put back.”).