tableau-to-hex-migration

--- name: tableau-to-hex-migration description: Migrate a Tableau, Looker, or Power BI dashboard to a Hex app that matches it exactly — same queries, results, filters, colors, layout, and tooltips. Use when the user pastes a Tableau dashboard/view link, a Looker dashboard link, or a Power BI report link and asks to migrate, replicate, copy, or rebuild it in Hex, or mentions "Tableau to Hex" / "Looker to Hex" / "Power BI to Hex". ---

# Tableau/Looker/Power BI → Hex Dashboard Migration

Given a Tableau, Looker, or Power BI dashboard URL, produce a Hex app that is a faithful copy: same underlying queries and numbers, same filters, same colors/layout/labels, same tooltips. The build is driven by the **Hex agent** (`hex thread` CLI); source logic is extracted from the **ground truth** — Tableau's workbook file (.twbx), Looker's dashboard + query APIs, or Power BI's report definition (PBIR) + semantic model (TMDL/DAX) — and validated against the **same warehouse Hex queries** before it is handed to Hex.

All command snippets referenced below live in [reference.md](reference.md) — read it before starting Phase 1.

**Adaptivity rule**: the procedure is environment-agnostic; only the leaf commands vary. Phase 0 pins four environment choices — **source BI** (Tableau / Looker / Power BI), warehouse engine (Snowflake / BigQuery / Databricks / Postgres-Redshift), source hosting (Tableau Cloud vs self-hosted Server; Looker-hosted vs customer-hosted; Power BI capacity/licensing tier), and OS (macOS vs Linux) — and every snippet in reference.md is either shared or labeled per branch. Follow your branch exactly; don't mix branches mid-run. (The Tableau + Snowflake + macOS branch is the most battle-tested; the others are documented equivalents.) Phases 2–5 are source-agnostic: Phase 1 is the **source adapter**, and whatever the source, it must produce the same artifact — a written spec with ground-truth queries, calc definitions, parameters/filters, colors, layout, and a rendered PNG.

## Preconditions and non-goals

Confirm these before Phase 1, and tell the user about anything that applies:

- **Works for**: dashboards of charts, tables, and heatmaps whose datasources are reachable from a Hex warehouse connection (Tableau custom SQL or published sources; Looker explores/Looks on a warehouse connection Hex can also reach; Power BI DirectQuery/composite models over such a warehouse, or import models whose upstream source tables live in one), with quick filters and parameters (Looker: dashboard filters and listen-mapped tiles; Power BI: slicers and report/page/visual-level filters). - **Power BI hard blockers — check before promising anything**: (a) an **import-mode model with no reachable upstream warehouse** (data lives only inside the pbix/semantic model) has nothing for Hex to query — stop and tell the user; (b) measures are **DAX, not SQL** — every measure must be *translated* to warehouse SQL and proven equivalent, which makes Phase 2 the dominant cost and complex DAX (nested `CALCULATE` context transitions, heavy time intelligence) a per-measure judgment call; (c) licensing walls — XMLA read and export-to-file need Fabric capacity or Premium-Per-User, and the `executeQueries` REST API needs its tenant setting enabled. Budget roughly 2× the Tableau/Looker correction rounds. - **Hex workspace requirements**: the CLI must be enabled for the workspace, and Phase 3 depends on the **Hex agent (threads)** feature, which consumes the workspace's AI credits and may be disabled or exhausted on some plans. Verify early — `hex thread create` failing with a credits/feature error means the whole build path is blocked until the workspace admin enables it (there is no free fallback with comparable quality). - **No clean Hex equivalent — agree a fallback with the user up front**: Tableau Stories; dashboard actions (filter/highlight/URL/set actions); row-level security and user filters; user-specific data blending. - **Out of scope**: refresh schedules, permission migration, publishing/embedding, alert subscriptions. The deliverable is a draft Hex app at visual/numeric parity (Phase 5 evidence pack). - A container usually holds **several dashboards** (a Tableau workbook, a Power BI report's pages, a Looker folder). After Phase 1 lists them, **ask the user two scope questions** and record the answers in the spec: 1. **Which to migrate** — all of them, only the linked one, or a subset. Default to only the linked one if they don't care. 2. **One app or one app with tabs** — if the selected dashboards are **tabs of the same logical report** (a Tableau workbook published with tabs, a Power BI report's pages), the default is **one Hex Generative app with a tab per dashboard** (generative apps support tab navigation; say so in the build prompt and keep each tab's SQL cells scoped to its own dashboard). Only genuinely unrelated dashboards get separate apps (one thread each).

Whatever the grouping, never mix panels from a dashboard that isn't in scope into another dashboard's tab.

## Progress checklist

``` - [ ] Phase 0: Setup + ground rules (tooling, fidelity policy, run manifest) - [ ] Phase 1: Extract the source spec (Tableau: twbx + XML; Looker: dashboard/query APIs; Power BI: PBIR + TMDL/DAX; + rendered PNGs) - [ ] Phase 2: Validate every query against the warehouse (the source's numbers as truth) - [ ] Phase 3: Build the Hex app with `hex thread create --new-project` - [ ] Phase 4: Self-check loop (screenshot diff, YAML, numbers) until parity - [ ] Phase 5: Deliver the parity evidence pack, get user sign-off ```

## Phase 0 — Setup and ground rules

Check what's installed; install only what's missing.

1. **Hex CLI** (required — this drives the whole build; macOS/Linux, Windows via WSL): ```bash hex --version || curl -fsSL https://hex.tech/install.sh | bash hex auth status || hex auth login # opens browser; confirms workspace + user ``` 2. **Source BI access** (required — pick your source branch): - **Tableau**: a Personal Access Token for the Tableau site — works for both **Tableau Cloud** and self-hosted **Tableau Server** (Server needs 2019.4+ for PATs; branch notes: reference.md §1). If a Tableau MCP server is configured for your agent, its `env` block already has `SERVER`, `SITE_NAME`, `PAT_NAME`, `PAT_VALUE` — reuse those values for the REST API (config locations per agent: reference.md §5). Otherwise ask the user for a PAT (Tableau: My Account Settings → Personal Access Tokens). PATs expire after ~15 days of non-use. If sign-in returns `401001` (also shows up as the Tableau MCP server stuck in an `error` state), the PAT is dead — recovery steps: reference.md §1. - **Looker**: **API3 credentials** (client ID + secret; user's Admin → Users → Edit → API keys, or ask a Looker admin) plus the instance base URL. Works for Looker-hosted and customer-hosted instances alike via `POST /api/4.0/login` (reference.md §11). If a Looker MCP is configured (managed MCP server or the MCP Toolbox `--prebuilt looker`), its env already has `LOOKER_BASE_URL`/`LOOKER_CLIENT_ID`/`LOOKER_CLIENT_SECRET` — reuse those. The API user needs access to the dashboard's folder and explores (API calls inherit their content permissions — a tile you can't see in the UI won't return SQL either). - **Power BI**: a **Microsoft Entra token** — easiest via the Azure CLI: `az login --allow-no-subscriptions` then `az account get-access-token` per API audience (reference.md §12); a service principal also works but skips row-level security, which changes the numbers you validate against. The user needs Build permission on the semantic model and read+write on the report (the Fabric `getDefinition` API oddly requires write). Also verify the licensing preconditions above **now**, and check whether Microsoft's Power BI MCP servers are available (remote Fabric-hosted or local `@microsoft/powerbi-modeling-mcp`) — useful accelerators, not required (reference.md §12). 3. **Warehouse CLI** (required for validation): determine which engine the Hex data connection uses — ask the user or check the Hex workspace's data connections — then set the `WH` branch and smoke-test it (reference.md preamble): Snowflake `snow`, BigQuery `bq`, Databricks `dbsqlcli`/Statement API, Postgres/Redshift `psql`. For any other engine (Trino, Athena, DuckDB/MotherDuck, ...), follow the same pattern: any CLI that takes a SQL string and returns JSON rows plugs into §8/§9 unchanged. **All validation SQL and everything you feed the Hex prompt must be in this engine's dialect** — Tableau's twb custom SQL and Looker's generated SQL already are (they ran against that warehouse), so never translate those; Power BI DAX is the exception that must be translated into this dialect (Phase 2). Never validate against a different engine than the one Hex will query. 4. **Source MCP** (optional, nice for live queries from chat): Tableau MCP config in reference.md §5; Looker managed MCP server or MCP Toolbox config in reference.md §11; Power BI remote/local MCP config in reference.md §12. The REST API paths work without any of them. 5. **Fidelity policy — ask the user now, not at Phase 4**: if the source dashboard turns out to be internally inconsistent (two panels disagreeing, a label that doesn't match its formula), should the copy **replicate the inconsistency faithfully (default)** or fix it in flight? The answer defines what "parity" means for the whole run; record it in the spec. 6. **Run manifest — create it first, update it as IDs appear**: a migration spans hours and multiple sessions; `thread_id`/`project_id` must not live only in shell scrollback. Use a stable run directory that survives reboots — `~/.tab2hex/<dashboard-slug>/` (not `/tmp`) — for the spec, saved SQL, PNGs, and a `manifest.json` with: dashboard URL, source IDs (Tableau: workbook + view LUIDs; Looker: dashboard ID + tile query IDs; Power BI: workspace + report + semantic-model IDs), spec path, source PNG paths, `thread_id`, `project_id`, Hex draft URL, and the environment branch (source BI, `WH` engine + connection name, hosting flavor, OS). **Resuming a partial migration** = read the manifest, re-pin the same environment branch, `hex project export` to see current state, continue the existing thread with `hex thread continue` — never start a second thread for the same app. 7. **Secret handling**: the source secret (Tableau PAT / Looker client secret / Entra token) lives only in your agent's MCP config (locations: reference.md §5, §11, §12) and session env vars — never in the repo, the spec, the run manifest, or the Hex prompt. Pass it to `curl` via a payload file, not inline `-d` (terminal transcripts capture full command text; reference.md §1, §11). Remind the user to revoke/rotate it when the migration is done. 8. **Time budget**: this is a multi-hour task, not a one-shot. Expect ~10–15 min of thread time for the initial build, ~4–10 min per correction round plus export/validate/screenshot time, and **3+ correction rounds** (dense dashboards take more). Heavy validation queries may need a larger warehouse. 9. **Approval fatigue — allowlist commands and front-load logins (tell the user this now, not mid-run)**: the run issues hundreds of terminal commands over hours, and every "Allow once" click makes the user the bottleneck (worse: an unattended run stalls at the first prompt). - **Suggest allowlisting the repeated CLIs** in the agent's settings for this session/project: `curl`, `python3`, `unzip`, `hex`, the warehouse CLI (`snow` / `bq` / `dbsqlcli` / `psql`), and `az` (Power BI branch). Where: **Cursor** → Settings → Terminal command allowlist (or per-prompt "Always allow" for that command); **Claude Code** → `/permissions` → add allow rules like `Bash(hex:*)`, `Bash(curl:*)` (or `permissions.allow` in `.claude/settings.json`); **Codex** → approvals policy in config. Scope rules to these specific binaries — do NOT suggest blanket auto-approval of all commands, and never