V2 UI Reference — Extract Preview Tab

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 Extract Preview

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.

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 Sync Preview or Full Sync.

Triggering a Run

There are two entry points:

• The Extract Preview button in the Detail page action bar (amber download icon) — runs immediately and refreshes the tab.
• The Open Debug Console button — pick Extract Preview from the mode picker and watch the live stdout stream.

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.

Summary Cards

Card	Tone	Meaning
Status	Sky	Run state — queued, running, completed, or failed. A failed status surfaces an error banner under the cards.
Records extracted	Violet	Total record count returned from the upstream for this preview.
Extract 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	Hover 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 extracted = 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 extracted 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 extracted 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 Sync Preview.
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.

Where to Go Next

Once Extract Preview returns the records you expect:

• Move to Sync Preview 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.

Asset Inventory

• Screenshot: PLACEHOLDER_v2_extract_preview_button.png — Detail page action bar with the Extract Preview button highlighted.
• Screenshot: PLACEHOLDER_v2_extract_preview_tab.png — Extract Preview tab with summary cards, error banner area, and a populated result table.
• Verification: confirm the four summary card labels (Status, Records extracted, Extract limit, Translated filters) match the live IntegrationExtractPreviewTab.vue at the V8.2.0 release tag.
• Verification: confirm the result table column order (External ID, Hostname, Primary IP, Payload Keys, Extracted, Details) is unchanged in the released build.