Cloud Conversions

Architecture at a glance

Apps arrive in the client's Qlik Cloud tenant via QAMT (exact on-premise app, permissions included). All work happens inside one shared space restricted to developers — apps are never published; "publish" always means sheet visibility within that space. Original sheet IDs are preserved end-to-end so bookmarks stay intact; the kit re-creates each sheet's contents as cloud-born objects (full property export → new object created by the Cloud engine → grid-cell swap), guaranteeing every object is registered as cloud-created and receives future cloud feature updates. Frozen "(Original)" clone sheets in a public "Original" group are the visual reference and part of the rollback safety net.

The lifecycle

1. Preflight (once per tenant/space): validates every schema assumption live — write capability, sheet cloning, container children refs, layout geometry keys, sheet-group schema, publish rights → preflight_report.json. First create one sheet group manually in the test app so the group schema can be confirmed. --execute refuses to run without a passing preflight.
2. Dry-run: prints the complete per-app action plan. The orchestrator is a plan/execute split — execute applies exactly the printed plan; the two cannot drift.
3. Execute (per app): canary "object testing" sheet proves edit rights → every sheet (hidden ones included) is cloned as "(Original) <name>", grouped, published → working sheets go private → masters, sheet cells, and container children convert to the standard targets. Every conversion is verified immediately; the first instance of each conversion type must pass before bulk conversion of that type, and a circuit breaker halts the app after repeated findings. Originals are never destroyed at this stage.
4. Review verification_report.csv; run scan_stories.py for story/snapshot references to old object ids.
5. Sign-off with the client on the converted (still private) sheets while consumers keep seeing the frozen Original clones.
6. Promote: the explicit go-live — publishes the converted working sheets. Refuses while unresolved "attention" verifications exist (--force overrides).
7. Cleanup: destroys original objects only where the conversion verified.
8. Decommission: removes the "(Original)" sheets and group so apps don't carry doubled sheets forever.

Safety model

• Single-space guardrail: QLIK_SPACE_ID is mandatory; every script refuses any app outside the designated space.
• Dry-run by default everywhere; state-changing runs need --execute.
• Approval gating: Qlik first-party objects convert ungated; third-party (Vizlib etc.) convert only with approved=Y in approved_conversions.csv (seeded by make_approval_worklist.py, merge-safe on rerun).
• Deferred destruction: converted originals stay as invisible orphans until --cleanup; rollback is a cell swap.
• Checkpoint/resume: progress saved per app at DoSave phase boundaries (run_state/); interrupted runs resume, never half-redo.
• Change freeze: plan fingerprints sheet state; execute aborts if the app changed since planning.
• Audit everything: restructure_log.csv (all actions), conversion_audit.csv (every object, old→new id, map version), container_rebuilds.jsonl + object_exports.jsonl (full pre-conversion property trees).

Four-tier recovery (rollback_app.py --app <id>)

0. Whole-app QVF backup — with QLIK_CLI_BACKUP=1, qlik-cli exports each app to qvf_backups/ before any change; a failed backup aborts the app untouched.
1. Orphaned original — still exists until cleanup; swap the cell back. Fast and exact.
2. JSON export replay — full pre-conversion property trees.
3. "(Original)" clone copy — every duplicated sheet holds an exact copy of each original object at the same grid position; located automatically, and always available for manual recovery by simply opening the "(Original) <name>" sheet. (Master-item instances on clones follow the shared converted master — tiers 1-2 cover those.)

What's in the kit

Client-environment setup

1. Python 3.8+, then pip install websocket-client (the kit's only dependency).
2. Claude Code: install per claude.com/claude-code and sign in with the company account. The kit's AGENTS.md briefs any AI assistant automatically (CLAUDE.md points Claude to it).
3. Download & unzip the kit from this page into a working folder; open the folder in Claude Code.
4. Tenant API key: Profile settings → API keys (developer role required).
5. Environment variables:

   QLIK_TENANT   = clienttenant.region.qlikcloud.com
   QLIK_API_KEY  = <api key>
   QLIK_SPACE_ID = <designated shared-space GUID>

6. Sanity check offline: python test_planner.py
7. Inventory first: python qlik_cloud_inventory.py → python analyze_inventory.py → add any unmapped_types.csv rows to the map → python make_approval_worklist.py → review in the Conversion Analysis app.
8. Then the lifecycle above, piloting one app with --app <id> before the fleet.

AI integration (works with any assistant)

• AGENTS.md in the kit is the canonical, cross-AI agent guide (Claude, ChatGPT/Codex, Gemini, Grok, Cursor …); CLAUDE.md just points to it. Any capable assistant can run the full lifecycle.
• Qlik MCP server (official, tenant-hosted): connect any MCP-capable assistant at https://<tenant-id>.<region>.qlikcloud.com/api/ai/mcp (CIMD recommended; DCR or manual OAuth otherwise; requires the Qlik MCP: Allowed permission). ~90 tools for discovery, analysis, dashboards, master items, lineage, and automations — ideal for inventory cross-checks and exploring the findings app. No conversion tools exist in MCP: the object surgery remains this kit's Engine API code.
• qlik-cli v3.4.0+ (github.com/qlik-oss/qlik-cli/releases; verify the published SHA-256): runs off the same env vars. Set QLIK_CLI_BACKUP=1 for automatic whole-app QVF backups before each app executes — recovery tier 0; a failed backup aborts the app untouched.

Open decisions & reminders

• Vizlib licensing: if the client holds/renews Vizlib Cloud licenses, many Vizlib objects can upgrade in place instead of converting to native at 50-75% fidelity. Resolve before approving Vizlib conversions.
• Multi KPI is already broken in Cloud (unavailable since Apr 2025; removal May 2027) — apps using it are first-wave rebuild candidates.
• Old table removal date still unannounced (as of the May 2026 release; Qlik promises advance notice) — moot for this design, since every classic table converts to the Straight table anyway.
• Cross-check the inventory: the May 2026 client-managed release ships a deprecated-chart tracking sheet (Content Monitor) — run it on the source system as an independent validation of the kit's findings before each migration wave.
• Change freeze: agree a no-edit / no-scheduled-reload window for each conversion run (single-developer space makes this easy, but the orchestrator checks anyway).
• Phase two: expression-level compatibility scan; custom theme availability in the tenant.