Skip to content

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 id plus 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

  1. Prepare a .csv or .xlsx file with the columns above (an export is the easiest starting point).
  2. Open the prefix import page and upload your file.
  3. Review the result summary.

For each row, Danbyte:

  1. Checks the cidr is valid (an invalid one is skipped and reported).
  2. Finds an existing prefix - by id if present, otherwise by cidr and vrf.
  3. Updates it if found, or creates a new one if not.
  4. 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.

  1. Go to Integrations → Import.
  2. Pick the object type and the format (CSV or JSON).
  3. Upload your file, or paste its contents.
  4. Review the available columns - required ones are marked.
  5. Click Validate to preview without saving anything.
  6. 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_policy on 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.