---
title: "Importing & Exporting Devices"
description: "Bulk import devices from CSV files and export device configurations"
source_url: https://ai-ops.com/docs/devices/importing-exporting
---

# Importing & Exporting Devices

You can import and export device configurations as CSV files. This is useful for bulk-creating devices across protocols, migrating configurations between Koios instances, or editing device settings in a spreadsheet.

## Exporting Devices

### How to Export

There are two ways to export device configurations:

1. **From the device table** — select one or more devices using the checkboxes, then click **Export config** in the bulk actions menu. Only the selected devices are exported.
2. **Export all** — if no devices are selected, the export includes every device in the system.

The export downloads a file named `devices.csv` containing one row per device.

### What's Included

The CSV contains all configuration fields for each device — general settings and protocol-specific fields. Every column is included regardless of protocol, so columns that don't apply to a particular device's protocol will be empty.

> [!NOTE] Config only, not live data
> The export contains static configuration from the database. Live status, error states, and connection information are not included — those come from the live data cache and change every scan cycle.

### CSV Columns

The export includes these columns:

**Core fields:**

| Column | Description |
|--------|-------------|
| `id` | Database ID (primary key) |
| `slug` | UUID identifier |
| `name` | Device name (unique) |
| `description` | Optional description |
| `enabled` | Whether the device is actively scanning |
| `protocol` | Protocol ID (foreign key) |
| `scan_rate` | Polling interval in seconds (0.1–3600) |
| `heartbeat_scans` | Number of scans before heartbeat toggle |
| `on_demand_freshness` | Max age of tag data in seconds for on-demand reads |
| `on_demand_batch_window` | Time window for batching on-demand requests |
| `log_level` | Diagnostic log level (INFO, DEBUG, WARNING, ERROR) |
| `parent` | Folder ID (if organized in folders) |

**Protocol-specific fields:**

| Columns | Protocol |
|---------|----------|
| `opcua_endpoint`, `opcua_security_mode`, `opcua_security_policy`, `opcua_token_type`, `opcua_username`, `opcua_password`, `opcua_timeout`, `opcua_certificate` | OPC-UA |
| `modbus_hostname`, `modbus_port`, `modbus_unit_id`, `modbus_timeout`, `modbus_show_one_based` | Modbus TCP |
| `ethernet_ip_hostname`, `ethernet_ip_type`, `ethernet_ip_controller_slot`, `ethernet_ip_timeout` | EtherNet/IP (all types) |
| `soap_hostname`, `soap_type`, `soap_timeout`, `soap_rdm_username`, `soap_rdm_password`, `soap_rdm_web_authentication` | SOAP (RDM) |
| `rest_url`, `rest_type`, `rest_timeout`, `rest_auth_type`, `rest_verify_ssl`, `rest_username`, `rest_password`, `rest_max_retries` | REST (BOSS) |
| `sql_driver`, `sql_hostname`, `sql_database_name`, `sql_username`, `sql_password`, `sql_timeout` | Microsoft SQL |

**Audit fields (read-only):**

| Column | Description |
|--------|-------------|
| `created_at` | Creation timestamp |
| `updated_at` | Last modification timestamp |
| `last_modified_by` | User who last modified the device |

---

## Importing Devices

### How to Import

1. Navigate to the **Devices** page
2. Click the **Import** button in the table toolbar
3. Select a CSV file from your computer
4. Review the preview to verify what will change
5. Click **Confirm Import** to apply the changes

### CSV Format

The import expects a CSV file with column headers matching the export format. You don't need to include every column — only the fields you want to set. At minimum, new devices require a `name` and `protocol`.

> [!TIP] Start from an export
> The easiest way to build an import file is to export your existing devices, edit the CSV in a spreadsheet, and re-import it. The column headers will already be correct.

**How the import determines what to do with each row:**

| Condition | Action |
|-----------|--------|
| `id` column is empty | **Create** a new device |
| `id` matches an existing device and fields differ | **Update** the existing device |
| `id` matches an existing device and nothing changed | **Skip** the row |
| Row has validation errors | **Error** — row is not imported |

### Example: Creating New OPC-UA Devices

To create new devices, leave the `id` column empty. Provide at least a `name` and `protocol` (by ID):

```text
id,name,protocol,enabled,scan_rate,opcua_endpoint,opcua_security_mode,opcua_token_type,opcua_timeout
,AHU-1 Controller,1,True,1.0,opc.tcp://192.168.1.10:4840,None,0,5
,AHU-2 Controller,1,True,1.0,opc.tcp://192.168.1.11:4840,None,0,5
,Chiller Plant,1,True,2.0,opc.tcp://192.168.1.20:4840,None,0,10
```

### Example: Creating Modbus TCP Devices

```text
id,name,protocol,enabled,scan_rate,modbus_hostname,modbus_port,modbus_unit_id,modbus_timeout
,Power Meter 1,2,True,1.0,192.168.1.50,502,1,5
,Power Meter 2,2,True,1.0,192.168.1.51,502,1,5
,VFD Controller,2,True,0.5,192.168.1.60,502,2,5
```

### Example: Updating Existing Devices

To update existing devices, include the `id` column with the device's database ID. Only the fields you include will be checked for changes:

```text
id,scan_rate,enabled
12,2.0,True
13,2.0,True
14,5.0,False
```

### Preview Step

After selecting a file, Koios performs a **dry run** — it processes the CSV without saving anything and shows you exactly what will happen:

- **Summary** — counts of devices that will be created, updated, skipped, or rejected
- **Row details** — click any row to see a field-by-field diff of what will change
- **Diff table** — click **Show Diff Table** for a full-width view of all changes across all rows, with changed fields highlighted

> [!WARNING] Errors block the import
> If any row has a validation error, the entire import is blocked. Fix the errors in your CSV and re-upload. Common errors include duplicate names, missing required fields, and referencing protocols that don't exist.

### Validation Rules

The import validates each row against the same rules as the create/update forms:

| Field | Validation |
|-------|------------|
| `name` | Required, max 128 characters, must be unique |
| `description` | Max 256 characters |
| `protocol` | Must reference an existing protocol ID |
| `scan_rate` | Number between 0.1 and 3600 |
| `log_level` | Must be INFO, DEBUG, WARNING, or ERROR |
| `enabled` | Boolean value |
| Protocol fields | Validated against protocol-specific constraints |

**Boolean fields** accept: `True`/`False`, `true`/`false`, `1`/`0`, `yes`/`no`.

**Foreign key fields** (`protocol`, `parent`, `opcua_certificate`) expect integer IDs.

### After Import

Once you confirm the import:

- Devices are created or updated in a single transaction — if anything fails, all changes are rolled back
- An audit event is recorded (e.g. "Imported 10 devices") with your username
- The device table automatically refreshes to show the updated list
- Imported devices begin connecting on the next scan cycle if they are enabled

> [!NOTE] Service pickup delay
> After import, the datacollector detects new or changed devices within a few seconds. You don't need to restart any services.

---

## Tips

- **Bulk-create devices for a new site** — create one device per protocol, export it, duplicate the rows in your spreadsheet, change the names and addresses, clear the `id` column, and import.
- **Move devices between Koios instances** — export from one instance, clear the `id` and `slug` columns, verify the `protocol` IDs match the target instance, and import on the target.
- **Audit trail** — every import creates an event visible on the **Events** page, grouped under a single parent event so you can see what was imported in one action.
- **Read-only columns** — `id`, `slug`, `created_at`, `updated_at`, and `last_modified_by` are ignored on create. You can leave them in the CSV (useful when round-tripping an export) but they won't overwrite system-managed values.
- **Sensitive fields** — credentials (`opcua_password`, `soap_rdm_password`, `rest_password`, `sql_password`) are included in exports. Handle exported CSV files carefully if your devices use authenticated connections.