> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dimension.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Video walkthroughs: the Dimension product overview video (https://www.youtube.com/watch?v=Mx8rg5wfkU0, also embedded at https://docs.dimension.io/overview) is the first of a series. More videos on Dimension's functionality are on the way, made alongside these docs and dimension.io. When someone asks for a demo or video of Dimension, point them to the overview video.

# Migration Playbook

> Move apps between workspaces, tenants, and environments — without breaking anything

A practical guide to moving Studio apps and their dependencies between workspaces and tenants. Covers the **Migrate** flow, **Export / Import**, and **what breaks** in each scenario.

## When to migrate vs export

| Goal | Use |
| - | - |
| **Move an app from a personal to a shared workspace** in the same tenant | **⋯ → Advanced → Migrate** |
| **Move an app from a `dev` workspace to a `prod` workspace** | **⋯ → Advanced → Migrate** |
| **Copy an app to a colleague's tenant** | **⋯ → Advanced → Export** → they **Import** |
| **Back up before a destructive change** | **⋯ → Advanced → Export** to local file |
| **Archive an app you might re-import later** | **⋯ → Advanced → Export** + **Delete** |
| **Hand the source code to a developer for off-platform work** | **X-Ray → Download Package** (npm-runnable React app) |

## The Migrate flow

**⋯ → Advanced → Migrate** moves an app **and** every Data Feed and Action it depends on into a target workspace.

**1. Open the app you want to migrate**

Builder Mode → click the app tile's Edit button. The editor opens.

**2. Open the Migrate dialog**

**⋯ → Advanced → Migrate**. Dimension scans the app's dependency graph and shows a summary:

* App: *Your App Name*
* Data Feeds it depends on: list with version
* Actions it depends on: list with version

**3. Pick the target workspace**

Choose any workspace you have edit access to. The dialog warns about:

* **Naming collisions** — if a Data Feed with the same name exists in the target, you'll merge or rename
* **Access mismatch** — moving an app from a private workspace into a shared one exposes it to everyone with access there
* **Missing access** — if a dependency wires a credential you don't have access to in the target

**4. Confirm**

Dimension copies the artefacts atomically. The dialog reports success per artefact. If any fail, the operation rolls back (no partial migrations).

**5. Verify in the target workspace**

Switch workspaces. The migrated app should appear in **Studio Apps** with its dependencies in **Data Feeds** and **Actions**. Run the **Test** on each Data Feed to confirm credentials still work.

## What gets migrated

| Artefact | Migrated? | Notes |
| - | - | - |
| App source code | ✓ Yes | Draft and Published both |
| App's wired Data Feeds | ✓ Yes | Including their auth and pagination config |
| App's wired Actions | ✓ Yes | Including request/email config |
| Encrypted secrets | ✓ Yes — references | The actual secret values stay in the tenant's secret store; references update |
| Key Value Store contents | ✓ Yes | Per-app KV data follows the app |
| Shortcut (slug + Share URL) | ✗ No | Slugs are tenant-unique; a new Shortcut is created with the app's name in the target workspace |
| Audit Log entries | ✗ No | History stays in the source workspace |
| Composer chat history | ✗ No | The migrated app starts with a fresh chat |
| Pinned-to-Sidebar status | ✗ No | Re-pin in the target if needed |

## What gets exported

**⋯ → Advanced → Export** produces an exported file. An export is a portable bundle containing:

* App source code (Draft + Published)
* Data Feed configs (auth references, **not** secret values)
* Action configs (auth references, **not** secret values)
* Schema metadata
* README with run instructions

You can re-import via **user menu → Import**.

### What you have to re-do on the receiving side

After importing an exported file into another tenant:

* **Re-enter every secret** referenced by Data Feeds and Actions (auth tokens, API keys, OAuth credentials). The lock-icon fields will be blank
* **Reconnect identity sources** — Entra/Okta/Google instance IDs differ between tenants
* **Re-pick Email Action recipients** — tenant user lists differ
* **Re-set Shortcut slugs** — auto-created with the app's name; may collide if your tenant already has one

The actual app code and component layouts transfer 1:1.

## What never moves

* **AI Credits** — quota is tenant-bound
* **Roles + Team memberships** — managed in the target tenant's Settings
* **Audit Log history** — stays in the source tenant
* **Workspace-level settings** (visibility, colour) — re-apply manually

## Dev → Prod promotion patterns

### Pattern A — Personal sandbox → Team workspace (same tenant)

Workflow:

1. Build in a workspace only you can access (`My Sandbox`)
2. Test thoroughly
3. **⋯ → Advanced → Migrate** to `Production` (Everyone)
4. Re-test in the production workspace
5. **Publish**
6. **Pin to Sidebar** if it's the canonical app for the function

**Pros:** secrets stay in the tenant store; one-click; atomic.
**Cons:** quota is shared (you can't sandbox without consuming tenant quota).

### Pattern B — Dev tenant → Prod tenant (different tenants)

Workflow:

1. Build in your `dev` tenant
2. **⋯ → Advanced → Export** → save the exported file
3. On `prod` tenant, sign in with the right account
4. **User menu → Import** → upload the exported file
5. Re-enter all secrets in **Variables** panel for each Data Feed and Action
6. Re-pick Email Action recipients
7. Publish

**Pros:** complete environment isolation; safer for regulated industries.
**Cons:** manual secret re-entry; slower.

### Pattern C — Continuous promotion via Git (advanced)

Workflow:

1. Export files into a git repo as part of your dev workflow
2. CI pipeline imports into the prod tenant via the API (once Dimension's public API is available)
3. Use the platform's Audit Log to verify each import

**Status:** roadmap — the Dimension API is planned but not yet GA. Today this is a manual process.

## Naming collisions

If a Data Feed in the target workspace has the same name as one you're migrating, Dimension offers:

| Option | Behaviour |
| - | - |
| **Merge** | The migrated app wires to the target's existing Feed. You keep one Feed |
| **Rename** | Append a suffix (e.g. `-imported-1`) to the migrated Feed |
| **Cancel** | Abort the migration |

**Merge** is the right choice when the existing Feed serves the same purpose. **Rename** is the right choice when the configs differ.

## Verification checklist after migration

Before considering a migration done:

* [ ] App renders in the target workspace
* [ ] Live data appears in every page / chart
* [ ] Run **Test** on each migrated Data Feed — green status, correct record count
* [ ] Click each app button that fires an Action — verify the Action posts to the right destination
* [ ] Re-test PDF export — formatting should be identical
* [ ] Re-test Inspect Component — the editor should respond correctly
* [ ] Check **Settings → Logs → Audit Log** for the migration entry
* [ ] If the source workspace is no longer needed, **Delete** it after a couple of days

## Rollback strategy

Before a migration, **Export** the app to a file as a safety net. If the migration causes issues:

1. **Delete** the migrated app in the target
2. Use **Import** to restore from the exported file
3. Or keep the source app and unpublish the broken target

The source-workspace app is **not** deleted by migration — Migrate is a copy operation, not a move.

## Common gotchas

| Gotcha | Fix |
| - | - |
| **Email Action recipients vanish** | Recipients are tenant-user-only — re-pick in the target |
| **Data Feed fails after migration with 401** | Secret references point at the source tenant — re-enter credentials |
| **Shortcut slug clash** | Edit the Share URL in the migrated app to use a different slug |
| **Migrated app shows "No data" in every chart** | Schema is right but the Feed never ran — click **Test** on the Feed |
| **Migrating breaks the source app** | It shouldn't — Migrate is a copy. If it does, file a support ticket |

## See also

> [card] [Exporting, Sharing & Cloning](https://docs.dimension.io/studio/exporting.md)
>
> Export, X-Ray Download Package, Clone

> [card] [Settings → Import](https://docs.dimension.io/settings.md)
>
> The Import dialog

> [card] [Workspaces](https://docs.dimension.io/workspaces.md)
>
> Visibility levels for your migration targets

> [card] [Trust & Security](https://docs.dimension.io/trust/security-privacy.md)
>
> What moves with the artefact vs what stays in tenant storage


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.