Importing & Exporting Tags

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

Exporting Tags

How to Export

There are two ways to export tag configurations:

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

The export downloads a file named tags.csv containing one row per tag.

What's Included

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

CSV Columns

The export includes these columns:

Core fields:

Advanced fields:

History compression overrides:

Protocol-specific fields:

opcua_timestamp_source is 0 for Collector Time (the default) and 1 for Source Timestamp.

Expression tags use the expression column. Internally this protocol is named "Calculation" in the database.

Audit fields (read-only):

Importing Tags

How to Import

1. Navigate to the Tags 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 tags require a name.

How the import determines what to do with each row:

Example: Creating New Tags

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

id,name,device,enabled,usage,range_min,range_max,units,decimal_places,opcua_namespace,opcua_identifier,opcua_identifier_type,opcua_datatype
,Supply Air Temp,1,True,0,0,100,°C,2,2,ns=2;s=AHU1/SAT,1,7
,Return Air Temp,1,True,0,0,100,°C,2,2,ns=2;s=AHU1/RAT,1,7
,Damper Position,1,True,1,0,100,%,1,2,ns=2;s=AHU1/Damper,1,7

Example: Updating Existing Tags

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

id,name,range_min,range_max,units
42,Supply Air Temp,-20,50,°C
43,Return Air Temp,-20,50,°C

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:

• Counts: how many tags will be created, updated, or rejected, and how many of the file's columns change at all
• Row details: select any row to open a panel showing each changed field, with its current value above the new one
• Filtering: search the rows, or narrow the grid to one action — rejected rows sort to the top and are marked
• All columns: the grid shows only the columns your file changes. Switch it to show every column when you want the full picture

Validation Rules

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

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

Foreign key fields (device, parent, device_set) expect integer IDs.

After Import

Once you confirm the import:

• Tags are created or updated in a single transaction. If anything fails, all changes are rolled back
• An audit event is recorded (e.g. "Imported 15 tags") with your username
• The tag table automatically refreshes to show the updated list
• Imported tags start collecting data on the next scan cycle if they are enabled and their device is running

Tips

• Bulk-create tags for a new device: export one configured tag from that device, duplicate the row in your spreadsheet for each new tag, change the names and addresses, clear the id column, and import.
• Move tags between Koios instances: export from one instance, adjust device IDs to match the target instance's devices, clear the id and slug columns, 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.