Import & export¶
Move data in and out of Danbyte with spreadsheets. Export to CSV or Excel, edit in your spreadsheet tool, and re-upload - Danbyte handles each row on its own, so one bad row never sinks the whole batch. You get a clear summary of what was created, updated, and skipped.
Round-trip is the point
An exported sheet uses exactly the columns Danbyte expects, so you can export, tweak, and import the same file back with no reformatting.
Import / Export - round-trip on every table¶
Every list page has an Import / Export button in its header, after the Add button; every detail page lists the same entries in its header's Export menu. It's the round-trip pair:
- Export → CSV, Excel (.xlsx), or JSON. The file carries each
row's
idplus stable, human-readable keys for its links, tags, and custom fields - so it can be re-imported. Text is always text: a value that starts with=,+,-or@is never run as a spreadsheet formula. Excel files store it as text; CSV files put an apostrophe in front, which the import takes off again. The SLA report CSV does the same. - Import… → upload an edited file. Danbyte first shows a preview (how many rows would be created vs updated, and any errors) before you Apply.
Export only the rows you select: tick rows in any table and the bulk bar
at the bottom gains an Export button that exports just the selection. The
selection travels in the request body, not the link, so a large one - Select
all N on a long list - exports like a few rows, up to 50,000 at a time.
Scripts do the same with POST /api/io/<type>/export/ and a JSON body of
{"fmt": "csv", "ids": [...]}; a GET takes ?ids= for a short list.
Any other field of the type narrows the export to an exact match
(?vrf=<id>).
An export shows you what the API shows you. A field the type's API hides
from you is not a column in your file and can't be used as an export filter:
without view_credits, an SLA agreement or SLA template exports without its
period_fee, credit_tiers and currency, and ?period_fee= is refused;
without view_cost, a support contract exports without cost and currency. A
file exported without those columns imports back leaving them as they are.
Secrets and their store paths aren't filters either.
On a prefix page the Import / Export acts on the IP addresses inside that prefix (the workflow that replaced the old "IPs" dropdown).
Two buttons, two jobs - don't mix them up
Import / Export is the editable round-trip (ids + keys, re-importable). The separate Download button (in the table's column toolbar) is a pretty snapshot of the columns on screen - great to hand to a colleague, but not re-importable. See Exporting tables.
Rows are matched by id first; if the id is blank or gone, by the type's
natural key - everything that makes the object unique: a prefix by cidr +
vrf, an IP by address + vrf, a VLAN by number + site + group, a device by
name + site, a rack by site + name, a location by site + slug. Otherwise a new row
is created, so a keyless row for another site makes a new rack there instead
of moving the one you already have. A key column left out of the file is not
matched on: a rack file with name but no site column updates the one rack of
that name, and is refused as ambiguous when several sites have one. A key column
present but blank matches an empty value (no VRF, no site).
You need add permission to create rows and change to update them, and you can only touch rows inside your own scope - importing a row outside it is a clean per-row error, never a silent escalation.
Import and export refuse a type where its API refuses it. While an
integration (Oxidized, Zabbix, DNS, DHCP, virtualization) or a plugin is
switched off for the tenant, its types are not offered, and an import or
export of one is refused whole with the API's 404, dry run included, before
any row is read. The same goes for the API's other checks on the type, such
as an administrator-only type: what the API refuses for a create or an
update, the import refuses for those rows.
The list of types you may import or export (GET /api/io/types/, behind the
Import / Export button on every table) is cached per user and tenant for
a minute, so a new role or a switched integration can take up to a minute to
change which types are offered. The import and export themselves check access
on every request.
An unchanged export imports back as a no-op. Re-uploading a file you didn't edit changes nothing, for every type.
Links are human-readable
Links are written as the name you'd recognise - a prefix as
10.0.10.0/24, a VLAN as its number, a VRF/site/device by name. So a
spreadsheet is editable by hand. A blank VRF cell means the global table
(you can also type Global, None or -); fill it in to place the row in
a named VRF. An object actually named Global, None or - is exported
by its id, so it reads back as itself.
The id column is opaque - leave it as-is to update a row, or blank to
create one.
A name is looked up where the row sits: an interface on the row's device, a prefix in the row's VRF, a rack, location or VLAN in the row's site. When a name still fits more than one object, the row is refused with an error rather than guessed at - put the object's id in the cell to say which. The export does that for you: a link whose name alone wouldn't read back to the same object is written as its id.
Single objects are exportable too: a detail page (an IP, for example) has the same entries in its Export menu, scoped to just that object.
Exporting prefixes¶
On the Prefixes list, use the export options to download a CSV or Excel (.xlsx) file. Whatever filters you have applied on screen carry into the export, so the downloaded sheet matches what you're looking at.
The prefix and IP sheets below are just the most-used examples; the same round-trip works for every table via its Data menu.
The prefix spreadsheet¶
| Column | Required | Notes |
|---|---|---|
id |
No | Leave empty to create a new prefix. Filled in (from an export) to update that exact row. |
cidr |
Yes | The network, e.g. 10.0.10.0/24 or 2001:db8:1::/64. |
status |
No | active (default), reserved, container, or deprecated. |
site |
No | Site name. It must already exist. |
vlan |
No | A VLAN number, looked up in the prefix's site. It must already exist. |
gateway |
No | A gateway IP address. |
description |
No | Free text. |
tags |
No | Tag names separated by semicolons. Missing tags are created automatically. A name that holds a ; is written in double quotes, e.g. "a;b";core. |
custom_fields |
No | Your custom field values, as a small JSON object, e.g. {"owner":"infra"}. |
Importing prefixes¶
- Prepare a .csv or .xlsx file with the columns above (an export is the easiest starting point).
- Open the prefix import page and upload your file.
- Review the result summary.
For each row, Danbyte:
- Checks the
cidris valid (an invalid one is skipped and reported). - Finds an existing prefix - by
idif present, otherwise bycidrandvrf. - Updates it if found, or creates a new one if not.
- Auto-creates any tag that doesn't exist yet. A site or VLAN must already exist.
If a single row fails - a bad network, malformed custom-field JSON - the rows around it still import, and the summary lists exactly which rows had problems.
Importing IP addresses¶
IP imports belong to a single prefix, so the file is tied to the prefix you export it from - you don't manage the parent on each row.
For each row, Danbyte confirms the address falls inside that prefix, then matches it against existing IPs. If the address already exists, its status, role, description, tags, and custom fields are updated in place - and it's moved into this prefix if it was elsewhere. If it doesn't exist, it's created here.
Tip
Because matching is by address (not by which prefix it's currently in), re-importing a freshly exported sheet always tidies its IPs back under the sheet's prefix.
The Import hub (paste a big file)¶
For a large paste or a one-off load, the Integrations → Import hub imports any type without leaving the page - the same round-trip engine as the per-table button.
- Go to Integrations → Import.
- Pick the object type and the format (CSV or JSON).
- Upload your file, or paste its contents.
- Review the available columns - required ones are marked.
- Click Validate to preview without saving anything.
- Click Import - rows are matched by
id/natural key, so existing rows update and new ones are created.
Results show how many rows were created vs updated, with a per-row table for any errors.
| Detail | Behavior |
|---|---|
| Columns | Match object fields by name; unknown columns are ignored. A file sets only what the type's API can write: columns the API holds read-only (numid, a script's trusted and owner, discovery timestamps) are exported but never imported. Where a secret lives in the secret store (a PSK's or key's store path) is neither exported nor imported. |
| Links to other objects | Resolved by name, slug, or id within your active tenant, among the objects you may view, and within the row's own device, VRF or site. A person or group cell (created_by, owner, assigned_group, …) resolves among the tenant's people when you have no permission on users or groups. An unknown or ambiguous link is a clean per-row error. |
| Saving | Each row is saved the way the API saves it, through the type's own create and update steps, so their checks apply: only a deployment administrator may point a device credential at an external secret path, a code change by someone without trust clears a script's trust, a contact or document is attached only to an object in your tenant you can view. An edit that would move a row out of the sites you may edit is refused. Types the API cannot create or edit (ACME orders, certificate bindings, …) export only. |
| Validation | The same rules as the API: uniqueness within the tenant, the type's own checks (a VLAN within its group's range, a rack's location in its site, a device's rack position free), and custom fields against their definitions. Custom fields are checked when a row sets or changes them. Each row is checked and saved on its own, so one bad row doesn't stop the rest. |
| Devices | A new device gets its type's interfaces and other components, as one added in the UI does. |
| Cables | Updated only: a row can't carry a cable's ends, and a cable needs both. |
| Validate | A dry run - the same checks as the import, with the same errors, writing nothing. |
| Limit | Up to 5000 rows per import. An Excel file may be up to 25 MB, 50 MB once unpacked, with at most 250,000 distinct texts and 500 columns per row; a larger workbook is refused before it is read. |
Note
You can only import object types you have add permission for - see Permissions & access.
File formats¶
- CSV, Excel (.xlsx), and JSON are detected by file extension.
- CSV files should be UTF-8 (a byte-order mark is tolerated). The delimiter is read from the header line - a comma, or the semicolon Excel writes in locales that use a decimal comma, a tab or a pipe.
- An empty cell in a required column that has a default (
gateway_policyon a site, say) takes the default; an empty required column with no default is refused, and the error names the column. - List and JSON columns hold JSON. An empty list exports as
[], and an empty cell in such a column is read as its empty value, never as text. Earlier releases stored such a cell as""(or{}in a list column); the upgrade to 0.17.2 puts those rows back to their empty list or object. - Excel files are read on the server, so no spreadsheet plugin is needed.
Extending it (for developers / plugins)¶
Every registered, tenant-scoped model gets round-trip export/import automatically.
A model with special keys - or a model shipped by a plugin app - customises it
by subclassing ModelIOHandler and registering the handler from the app's
io.py (auto-imported at startup):
# myplugin/io.py
from api.io import ModelIOHandler, register_io
from auth_api.object_types import register_object_type
from .models import Widget
class WidgetIO(ModelIOHandler):
model = Widget
natural_key = ["serial"] # fallback match key when id is absent
fk_keys = {"vendor": "name"} # how each FK is rendered/looked up
# override to_row / apply for full control
register_object_type("myplugin.Widget", "Widgets", "Plugins") # RBAC + discovery
register_io(WidgetIO())
Add the app to INSTALLED_APPS and its Widgets type appears in the permission
picker and gains a Data menu wherever its table is shown - no core changes.
Import and export go through the type's routed viewset: its initial() gates
(PluginEnabledMixin, IntegrationToggleMixin), permission classes and
allowed methods apply to them. A serializer that shows some fields only to
some users mixes in core.hidden_fields.PermissionHiddenFieldsMixin and names
them in hidden_fields(obj); the export leaves the same fields out. Don't
drop fields per user in a bare to_representation - the export can't see it.
Related¶
- Exporting tables - quick export of any list.
- Tags & custom fields - the
tagsandcustom_fieldscolumns. - Permissions & access - who may import.