V2 UI Reference: Extract Preview Tab

The Extract Preview tab is the same on every V2 driver: Statseeker, Zabbix, Nautobot, NetBox, PRTG, AKIPS, Checkmk, Infrahub. This page documents what the tab does, what each control means, and how to read the result table. Each driver guide links here instead of repeating the same explanation.

When to Use This Tab

Run Extract Preview any time you change filters, change credentials, or change the upstream’s group / tag layout. It runs only the extract stage of the V2 pipeline: no canonicalize, no reconcile, no writes: so it is safe to repeat as many times as you need.

Prerequisites

• A saved V2 integration instance that has passed Test Connection.
• setting.view permission to view the tab, setting.create/setting.update to trigger a run.

What Extract Preview Does

Extract Preview asks the driver to call the upstream API exactly the way a full sync would, but stops immediately after the raw records come back. The records are stored in their own integration_extract_preview_runs table so the result survives a page reload and you can compare runs side-by-side via the run history.

Specifically, Extract Preview will:

1. Translate the configured filters into the upstream’s native query syntax (Statseeker query params, Zabbix host group IDs, Nautobot/NetBox GraphQL, etc.).
2. Authenticate to the upstream and page through the result set, respecting the driver’s pagination limits.
3. Persist each record’s raw payload so you can inspect every field the upstream returned, even ones the canonical mapping discards.
4. Return a result page to the UI without touching integration_source_records, integration_canonical_candidates, or any device.

The Run Insights, Problem Devices and Logs tabs are not updated by an Extract Preview run: only by a Preview Sync or Full Sync.

Triggering a Run

There are two entry points:

1. Click the Extract Preview button in the Detail page action bar: a magnifying-glass icon, amber-coloured. It runs immediately and refreshes the tab.
2. Or click Open Debug Console, select the Preview mode toggle, and run from there to watch the live stdout stream instead.

The button is disabled until the instance has a saved configuration that passed Test Connection. If you click it before saving, the form prompts you to save first.

Reading the Tab

The tab is laid out as four summary cards across the top, followed by the per-record result table.

Extract Preview tab showing the Status, Records, Limit, and Translated Filters summary cards above a populated result table. Shown with the Zabbix driver. Every V2 driver uses the same screen.

Summary Cards

Card	Tone	Meaning
Status	Emerald when completed, amber when running/queued, red when failed, sky otherwise	Run state. A failed status surfaces an error banner under the cards.
Records	Violet	Total record count returned from the upstream for this preview.
Limit	Indigo	The cap the driver applied for this preview: Extract Preview deliberately uses a lower limit than a full sync to keep the round trip quick.
Translated Filters	Teal	Number of filter expressions sent to the upstream after translation. 0 means the driver pulled an unfiltered sample.

Error Banner

If validate_setup or extract failed, the cards are followed by a red error summary banner with the exception message. The full exception (with stack and previous exceptions) is preserved in the Logs tab: the banner is the headline, not the full story.

Result Table

The result table shows one row per upstream record:

Column	What it shows
External ID	Upstream identifier the driver chose (id, deviceid, cdt_deviceid, etc., depending on driver).
Hostname	Hostname the driver resolved using the schema’s hostname_paths. Empty cells mean the upstream record lacked all of the configured paths.
Primary IP	IP resolved using the schema’s primary_ip_paths. Empty is allowed at this stage but will fail in canonicalize if the schema requires it.
Payload Keys	First four top-level keys in the raw payload, comma-separated. A quick visual sanity check that the upstream returned a “fat” record vs a sparse stub.
Extracted	Timestamp the record was pulled.
Details	A View detail button that opens a card with the full JSON payload. Use this to inspect tags, group IDs, custom fields and anything else that the canonical mapping does not surface in the table.

Pagination

Long preview runs are paginated server-side. Previous / Next buttons appear under the table when last_page > 1. The page state is local to the tab: the underlying preview run does not change as you page.

Refresh

The refresh icon in the top-right re-fetches the latest preview run for this instance. It does not run a new preview: use the action-bar button for that.

Triage: What to Do When Preview Looks Wrong

Symptom	Likely cause	Fix
Records = 0	Filters too narrow, or API user lacks visibility of the target objects.	Loosen filters or expand the upstream user’s permission scope. Re-run.
Records matches expected count but Hostname column is empty	The upstream is returning a different field than the schema’s default hostname_paths.	Inspect the Details payload to find the right field, then either remap upstream or update the schema.
Records very high and run is slow	No upstream filters in use, full inventory pulled.	Add at least one filter (group, tag, status) before promoting to Preview Sync.
Translated Filters = 0 even though you configured filters	Filter operator not supported by this driver: driver dropped it silently.	Check the driver’s schema filters.fields for supported operators. The Logs tab shows the dropped expressions.
Status failed, error mentions 401 / 403	Bearer/token expired, or auth path wrong.	Go back to Setup, re-test connection, re-test credentials, save, re-run.
Status failed, error mentions SSL / certificate	Self-signed cert or hostname mismatch.	Toggle Verify TLS Peer / Hostname off in Setup (lab/internal only) or fix the cert.

Common Gotchas

Common gotchas

• Extract Preview uses a lower record cap than a real sync, so a low Records count here does not necessarily mean your full sync will be small: check the Limit card before assuming.
• The refresh icon only re-fetches the latest stored preview run. It never starts a new one: click the action-bar button (or use the Debug Console) to actually run the extract again.
• An empty Hostname or Primary IP column at this stage is not fatal to Extract Preview itself, but it will fail validation in canonicalize once you move to a Preview Sync.

Related Documentation

Once Extract Preview returns the records you expect:

• Move to Preview Sync to walk the full pipeline (canonicalize → reconcile → decide) without writing.
• See Run Insights Tab for how to read the resulting pipeline run.
• See Problem Devices Tab for triaging candidates that fail validation or reconciliation.