# Migrating to Agility

> Source: https://agilitycms.com/docs/developers/migrating-to-agility

Moving a website or content hub to Agility CMS is a project with a predictable shape. This page breaks it into six phases, says who usually does what, shows where an AI agent saves time, and links to guides for specific source systems and for launch day.

> [!NOTE]
> Content you import through the Management API, the Management SDK or the MCP server lands in **Staging**. The CLI also leaves synced content in staging unless you pass `--autoPublish`. Nothing goes live until someone publishes it, so plan publishing as its own step.

## The six phases

| Phase | Goal | What you end up with |
| --- | --- | --- |
| 1. Inventory | Know exactly what you are moving | Counts per content type, fields in use, relationships, assets, URLs, integrations |
| 2. Model | Design the target in Agility | Content models, component models, page models, containers, locales |
| 3. Map | Decide how each source field becomes an Agility field | A field map, a URL map and transform rules |
| 4. Import | Load content into Staging | A re-runnable import script and a source ID to Agility content ID map |
| 5. Verify | Prove the import is complete and correct | Counts, spot checks, preview review, sign-off |
| 6. Cut over | Move traffic to the new site | Content freeze, final sync, redirects, DNS change, rollback plan |

Phases 3 to 5 usually loop. Import a small sample, check it, fix the model or the map, and import again. Changing a model is much cheaper before thousands of items exist.

### 1. Inventory

- Count the items of each content type in the source, and list the fields that are actually populated, not every field the source system supports.
- Record relationships between records (authors, categories, related items). They become linked content in Agility.
- List the assets you need to move: featured images, inline images, downloadable files.
- Export every public URL now, from the old site's sitemap, its CMS and your analytics. You need this list for redirects. See [Keep Your Search Rankings Through a Migration](/docs/developers/keep-search-rankings-through-a-migration).
- List the integrations that read from or write to the old system: forms, search indexes, feeds, webhooks.
- Note anything awkward: shortcodes, page-builder markup, embedded scripts, content that differs per locale.

### 2. Model

Design the destination before you move anything. Decide which source patterns become:

- **Content models and containers** for lists of structured content such as articles, authors and categories. See [Content Models](/docs/developers/content-models).
- **Component models** for the building blocks editors place on pages, and **page models** for page layouts and their zones. See [Component Models](/docs/developers/component-models) and [Page Models](/docs/developers/page-models).
- **Pages in the sitemap**, including dynamic pages that generate one page per item in a list. See [Generating Dynamic Pages From Content](/docs/editors/generating-dynamic-pages-from-content).
- **Linked content** relationships. See [Getting Started with Linked Content](/docs/developers/getting-started-with-linked-content).
- **Locales**, if the source is multilingual.

Aim for structure, not HTML blobs: authors, dates, images and categories should be their own fields or linked items. [Legacy Content Migration](/docs/developers/legacy-content-migration) explains why. Use letters and numbers only in reference names; a hyphenated container name can't be queried through GraphQL.

### 3. Map

Write down, for every source content type, which Agility model and container it goes to, and for every field, the Agility field and any transform. A field map is a simple table:

| Source field | Agility field | Field type | Transform |
| --- | --- | --- | --- |
| `title` | `Title` | Text | Decode HTML entities |
| `body` | `Body` | HTML | Rewrite internal links and image URLs |
| `author` (ID) | `Author` | Linked Content | Look up the Agility content ID of the imported author |
| `id` | `SourceID` | Text | Store as-is, so re-runs update instead of duplicating |

Decisions to make in this phase:

- **Rich text:** keep it as HTML in an HTML field, convert it to Markdown for a Markdown field, or break recurring patterns into fields and components.
- **References:** which items must exist first so others can link to them.
- **Assets:** which files to upload to the media library, and how to rewrite their URLs in body content.
- **URLs:** the new path for every old URL, and which ones need a redirect.

[Field Types and What the APIs Return](/docs/developers/field-types-api-reference) shows what each Agility field type stores and returns, which helps you pick types.

### 4. Import

Pick the tool that fits the volume and the job:

| Tool | Best for | Notes |
| --- | --- | --- |
| AI agent with the [Agility MCP Server](/docs/developers/agility-cms-mcp-server) | Creating models and importing a reviewable sample of dozens of items | Every call is visible in the conversation. See [Migrating Content into Agility with an AI Agent](/docs/developers/migrating-content-with-an-ai-agent). |
| [Management SDK](/docs/javascript/management-sdk/getting-started) (JavaScript or .NET) or the Management API | Hundreds of items or more, and imports you need to re-run | Save in sequential batches. See the throughput notes below. |
| Content list Excel export and import | Small lists you want to edit by hand | See [Importing Content](/docs/developers/importing-content). |
| URL Redirections import | Loading many redirects at once | See [URL Redirections](/docs/editors/url-redirections). |
| [Agility CLI](/docs/developers/cli) | Copying models and content **between Agility instances**, for example from a migration sandbox into a blank production instance | Not an importer for other systems. Sync into a blank target; synced items get new content IDs; sync never deletes on the target. |

Import in dependency order: upload assets and create the items others point to (authors, categories, tags) first, keep a map from source ID to Agility content ID, then import the items that reference them, then build pages.

### Throughput: batches, limits and tokens

- **Writes are queued.** Every Management API save, delete or workflow operation is queued as a batch and completes moments later. The SDKs wait for the batch by default. See [Batches and the Batch API](/docs/javascript/management-sdk/batches).
- **Run batches one after another, not in parallel.** Parallel calls can trigger rate limiting and batch conflicts.
- **Use the bulk endpoints.** One batch workflow call publishes, unpublishes or approves up to 250 items. One URL redirections call creates or updates up to 250 redirects.
- **Check every item.** A processed batch can still contain failed items, so read each item's `errorMessage`. The JavaScript SDK's `saveContentItems` returns `-1` for an item that failed.
- **Back off on 429.** If the API answers `429 Too Many Requests`, wait and retry with an increasing delay. Build the import to slow down when told to rather than aiming at a fixed rate.
- **Page every list.** Management API lists return 50 items by default and at most 250 per request. Page with `take` and `skip` until a short page comes back.
- **Only re-save what changed.** Every save creates a new version of the item.
- **Use a Personal Access Token for long jobs.** OAuth access tokens last 24 hours. See [Personal Access Tokens](/docs/developers/personal-access-tokens).
- **Your new site has limits too.** The Content Fetch API allows 10 uncached requests per second; responses served from the CDN cache don't count. Keep this in mind for verification crawls and full-site builds. See [Fetch API Status Codes and Caching](/docs/developers/fetch-api-status-codes-and-caching).

### 5. Verify

Before anything is published, check:

- Item counts per container match the source, minus anything you skipped on purpose.
- Every failed save is accounted for, and re-runs updated items instead of creating duplicates.
- Linked content resolves in the editor (dropdowns show a value, not a blank).
- Image and file fields point at `cdn.aglty.io`, not the old site.
- Body content has no leftover shortcodes, page-builder markup or links to the old domain.
- Content is in the right locale.
- A sample renders correctly on the new site in preview mode.
- Every URL in your inventory either exists on the new site or has a redirect.

The full checklist, with a prompt that asks an agent to run the checks, is in [Migrating Content into Agility with an AI Agent](/docs/developers/migrating-content-with-an-ai-agent#verification-checklist).

### 6. Cut over

Launch day has its own sequence: content freeze, final sync, publishing, redirects, the DNS change, cache and webhook checks, and a rollback plan. Follow the [Migration Cutover Runbook](/docs/developers/migration-cutover-runbook), and use [Keep Your Search Rankings Through a Migration](/docs/developers/keep-search-rankings-through-a-migration) for the SEO side.

## Who does what

One person can hold several of these roles on a small project.

| Role | Responsibilities |
| --- | --- |
| Project lead | Scope, timeline, freeze dates, the go or no-go decision |
| Content modeler | Inventory, content and component models, the field map. Creating models needs an Agility role that can manage models (Designer, Manager or Admin). |
| Developer | Export and import scripts, the front end, redirects, webhooks, preview |
| Content owners and editors | Review the sample, fix content that can't be mapped automatically, sign off |
| SEO owner | URL inventory, URL map, metadata, post-launch monitoring |
| Agility administrator | Users and roles, tokens, webhooks. Running the CLI needs the Org Admin, Instance Admin or Manager role. |

## Where an AI agent helps

An agent connected to the Agility MCP Server is most useful at the start and the end of a migration:

- **Inventory:** read the source API or export file and report content types, counts, fields in use and awkward cases.
- **Model:** propose content models from the inventory, check what already exists in your instance, and create the approved models and containers.
- **Sample import:** import 10 to 20 varied items into Staging so people can review them in the editor.
- **Script:** write the Management SDK import script from the approved models and the sample's field shapes.
- **Verify:** page through every container and report empty fields, leftover markup and broken asset URLs.

Keep people in the loop where it matters: approving the model, reviewing the sample and deciding when to publish. The agent acts with your Agility permissions. Move bulk volume to a script rather than individual tool calls. The whole flow, with prompts and code, is in [Migrating Content into Agility with an AI Agent](/docs/developers/migrating-content-with-an-ai-agent).

## Guides in this section

- [Migrate from WordPress to Agility](/docs/developers/migrate-from-wordpress)
- [Migrate from Contentful to Agility](/docs/developers/migrate-from-contentful)
- [Migrate from Sitecore to Agility](/docs/developers/migrate-from-sitecore)
- [Migration Cutover Runbook](/docs/developers/migration-cutover-runbook)
- [Keep Your Search Rankings Through a Migration](/docs/developers/keep-search-rankings-through-a-migration)

Migrating from another system, or from hand-built HTML? The phases above still apply, and [Legacy Content Migration](/docs/developers/legacy-content-migration) covers parsing HTML into structured fields.

## Related

- [Migrating Content into Agility with an AI Agent](/docs/developers/migrating-content-with-an-ai-agent)
- [Batches and the Batch API](/docs/javascript/management-sdk/batches)
- [Getting Started with the Management SDK](/docs/javascript/management-sdk/getting-started)
- [AgilityCLI (Command Line Interface)](/docs/developers/cli)
- [Website Deployment Checklist](/docs/developers/website-deployment-checklist)

---

## Related pages

- [Migrate from WordPress to Agility](https://agilitycms.com/docs/developers/migrate-from-wordpress.md)
- [Migrate from Contentful to Agility](https://agilitycms.com/docs/developers/migrate-from-contentful.md)
- [Migrate from Sitecore to Agility](https://agilitycms.com/docs/developers/migrate-from-sitecore.md)
- [Migration Cutover Runbook](https://agilitycms.com/docs/developers/migration-cutover-runbook.md)
- [Keep Your Search Rankings Through a Migration](https://agilitycms.com/docs/developers/keep-search-rankings-through-a-migration.md)

Index of every docs page: https://agilitycms.com/docs/llms.txt