Skip to content

Plan a migration to CMS Orbit

The playbook for moving a website to CMS Orbit from any CMS: the phases from discovery to the weeks after launch, with deliverables, a safe import order, media, references, languages, redirects, validation, launch and rollback, a checklist to copy, and the guide for each source platform.

Explanation23 min read

Moving a website from another CMS, often called replatforming, is less about the script that copies content and more about the decisions around it: what to keep, how to model it, how old addresses keep working, and when to switch. This page is the plan for the whole project. The copying itself is the reusable script in Import content with the Management API, and each source platform has a guide that turns its export into that script's import file.

The examples move the Northwilds website: trips, gear and journal articles, in English with Norwegian and German translations.

What CMS Orbit does for you

Several steps that need custom work elsewhere are part of CMS Orbit:

  • An import command: npx cms-orbit import reads one import file, whatever the source. Each entry keeps its id from the old system as its external ID, so running it again updates instead of duplicating, with no state file to keep.
  • Dry runs: content imports, schema changes, redirects, taxonomy terms, SEO metadata, space imports and promotions all report what they would do before you apply them. A content dry run checks every entry against the schema as if it were saved.
  • References in any order: the import fills in references and links in a second pass, so authors don't have to arrive before articles.
  • Duplicate files: uploading a file the media library already holds, byte for byte, answers with the existing file.
  • Image sizes: the CMS resizes images by address, so only the original of each image needs to come across.
  • Redirects in bulk: up to 5,000 per CSV, checked row by row first, with chains collapsed and loops refused. Column names from other systems, such as Old URL and New URL, are accepted as they are.
  • Broken links and missing addresses: SEO › Not found lists links inside the CMS that lead nowhere and addresses visitors asked for that have no page.
  • Checks before launch: SEO health, language links (hreflang) and the accessibility report run on drafts, so you fix pages before they are live.
  • Staging and Production: import and check in Staging, then promote a whole folder or language to Production in one go, with its redirects.

The phases

1. Discovery
What you do
List content, addresses, files, relationships, languages, redirects, integrations, people and workflows
Deliverables
Content inventory, address list, gap list
2. Design
What you do
Model content types and components, choose addresses and languages, write the mapping
Deliverables
Schema as code, mapping file, a proof of concept
In CMS Orbit
Schema as code with a dry run
3. Export
What you do
Read everything from the old system and keep it
Deliverables
Raw export, backup
4. Transform
What you do
Turn the export into an import file
Deliverables
Transform script, import file, list of exceptions
In CMS Orbit
5. Media
What you do
Bring files across with alt text
Deliverables
Files in the media library, old-to-new file list
In CMS Orbit
Uploaded once, duplicates detected
6. Content
What you do
Import entries, references, translations and redirects
Deliverables
Entries in Staging
In CMS Orbit
cms-orbit import with --dry-run
7. Validate
What you do
Compare the new site with the old one
Deliverables
Count report, address report, issue list
In CMS Orbit
SEO health, Not found, accessibility report
8. SEO
What you do
Keep every old address working and every page described
Deliverables
Redirects, metadata, sitemap
In CMS Orbit
Redirect CSV import, metadata CSV, sitemaps from the SDK
9. Launch
What you do
Freeze, final import, switch the domain
Deliverables
Live website, rollback plan
In CMS Orbit
Promote, go-live checklist, mirror
10. After launch
What you do
Watch, fix, train, switch the old system off
Deliverables
Fixes, closed issue list, retrospective
In CMS Orbit
Not found log, SEO and accessibility trends

1Discovery

Start with a list of what the old website holds:

  • Content types and how many items each has: trips, gear, journal articles, authors, landing pages.
  • Addresses: every public address, from the old sitemap and a crawl. Add the most visited pages from your analytics, and the redirects the old system already has.
  • Files: images, documents and videos, where they are stored, and whether the old system keeps resized copies.
  • Relationships: which items point at which, such as an article's author or a trip's guide, and links inside text.
  • Languages and markets: which languages exist, and whether markets differ in content, prices or availability.
  • Embedded media and custom fields: videos, maps, forms, plugins, anything stored in a format only the old system understands.
  • Integrations: search, analytics, forms, shop, booking, newsletters.
  • People and workflows: who edits what, who approves, and what slows them down today. Ask the editors.

Then decide what to script and what to move by hand. Content types with many items of the same shape, such as journal articles, are worth a script. A handful of landing pages, each built differently, are often quicker to rebuild by hand with your new components, and that is a chance to improve them.

Treat the migration as a chance to simplify. Content nobody reads, fields nobody fills in and components used on one page can stay behind.

2Design

Design the CMS Orbit model for how the content is used, not how the old system stored it. Model your content explains each choice: content types for things with their own address or that are reused, components for page sections, slots or references, links that follow a page when it moves, shared sections, and taxonomies or select fields.

Keep the model in your repository with Schema as code: its sync script shows what it would change and changes nothing until you pass --apply. Keys of content types, components and fields cannot be renamed later, so settle them now.

Addresses

Keep the old addresses where you can. Give a content type an address prefix, such as /journal, or send each entry's exact address as url in the import file. Where an address must change, the import file's redirects send the old one to the new one.

Languages and regions

In CMS Orbit, each language holds its own copy of an entry, linked to the others as translations, and regions keep markets apart. The other systems' approaches map like this:

Translated fields on one item
In CMS Orbit
One entry per language, linked as translations. The import file's translations creates them.
A translated copy of each item or page, such as a folder per language
In CMS Orbit
The same: import the main language's item, and the other copies as its translations
A separate site or space per market
In CMS Orbit
A region per market in one space, with its own languages, address prefix and domain. Fields marked Differs by region keep their own value, such as a price.
Some items translated, some not
In CMS Orbit
Fallbacks: the space can answer with another language when a page isn't translated, and your website says so. See Regions and languages.

Create the regions and languages before importing.

The mapping

Write down, for every source field, where it goes. A mapping file your transform reads keeps the rules in one place instead of spread through code:

mapping.mjsJavaScript
export const journalPost = {  type: 'journalPost',  url: (old) => `/journal/${old.slug}`,  fields: {    excerpt: { from: 'summary', transform: 'plainText' },    publishedOn: { from: 'date', transform: 'isoDate' },    author: { from: 'author.id', transform: 'ref', prefix: 'author:' },    topics: { from: 'tags', transform: 'termValues', taxonomy: 'topic' },    heroImage: { from: 'featured_image', transform: 'asset', alt: 'featured_image_alt' },  },  body: { from: 'content', transform: 'htmlToBlocks' },  fallbacks: { excerpt: '' },}

For each field, note the source key, the target field, the transformation, whether it holds a file, and its default when it's empty. Each source platform's guide has the mapping table for that platform.

Prove it on real content

Before writing the full transform, build a few real pages by hand in a test space and look at them in the live preview with the editors who will use them. Change the model until it feels right. To start a test space with the same schema and no content, copy a space with POST{space}/clone and content: false; see "Spaces" in the Management API.

People, roles and approval

Set these up by hand rather than migrating them. People sign in through Orbit, so there are no passwords to move. Give each person a built-in role, or one of your own on Growth and Enterprise, and limit people to the regions they look after. Choose which content types need approval before publishing. See Roles and permissions and Governance. For many people at once, POST{org}/members invites them with a role.

3Export

Read everything from the old system, ideally through its API as JSON:

  • An API: the cleanest export, with ids, references and languages. Every platform guide below uses one where the platform has it.
  • A database dump or export file: XML, CSV or SQL. Parse it to JSON first, so the transform works on one shape.
  • The live website: when there is no other way out, crawl the published pages and read the content from the HTML.

Keep the raw export as it came, with the date it was taken, and never edit it. It is your backup and the input you can always transform again. Record each item's id in the old system: it becomes the item's key in the import file, and references point at it.

4Transform

The transform turns the raw export into the import file described in Import content with the Management API: each entry with its key, type, name, slug, fields, blocks and translations, and three placeholders for files ($asset), references ($ref) and links to other entries ($link). The platform guides each contain a transform for their platform.

The parts that need thought:

  • Rich text is stored as HTML and cleaned when saved: h1 becomes h2, and images, scripts and embeds are removed. Move images and embeds out of the text into blocks.
  • Links inside text are plain addresses. Rewrite old addresses to new ones while you transform. Where a link must follow its page when it moves, use a Link field instead.
  • Dates: an entry's own created and published times are set when it is imported and published. Keep the original date in a field of its own, such as publishedOn, and show that on the website.
  • Categories and tags become taxonomy terms. Import the terms first: Taxonomies › Import CSV takes a column per language and labels per region, and reads Storyblok's datasource export as it is. See Taxonomies.
  • History: only each item's current version comes across. Use the latest published version, unless a draft is what you want to keep.
  • Exceptions: log every item the transform cannot map, rather than guessing. The list becomes work for editors or a change to the mapping.

5Media

The import uploads each file the first time an entry uses it, sets its alt text in each language, and remembers the file's old address so it isn't downloaded again. On top of that:

  • Duplicates: a file whose contents the media library already holds, even under another name or address, answers with the existing file instead of a copy.
  • Resized copies: bring only the original, at the highest resolution. Leave out copies such as boot-300x200.jpg, by their name pattern or the old system's metadata. Your website asks CMS Orbit for each size by address, such as ?w=768, and the SDK's image component builds the srcset and AVIF copies; see Render components.
  • Formats: JPEG, PNG, WebP, AVIF, GIF, SVG, PDF, MP4 and WebM, up to 25 MB each. JPEG and PNG are stored as WebP. Keep long, high-resolution videos on a video host.
  • Alt text is needed in each language before a page using the image can be published. Bring it from the old system where it exists, and list the images without it.
  • Missing files: a dry run checks every file's address, and lists those that cannot be downloaded. Fix the source, or drop the file from the import file and add it to the exception list.
  • Folders: media folders keep a large library in order; send folderId with each upload in your own scripts.
  • Old file addresses: files get new addresses. If the old addresses get traffic, such as images found through image search, add redirects from them to the new files. They work once the old domain points at your new website and its routes pass those addresses to resolve. To serve files from your own domain, such as media.northwilds.com, see Serve images from your own domain.

6Content

A safe order

  1. Regions and languages.
  2. The schema: content types and components.
  3. Taxonomies and their terms.
  4. Folders, if you use a folder tree.
  5. Everything else, with cms-orbit import: shared sections first, then entries with their files, then references and links in a second pass, then the copies in other languages, then redirects.
  6. Publishing, once you have checked.

The import handles the order within step 5 itself. A large site can be split into several files, such as one per market or content type. A reference may name an entry from an earlier file by its key, since the import looks keys up by external ID; import the file with the entries that are pointed at first.

Start small, then grow

  1. Check the file with npx cms-orbit import import.json --dry-run and fix what it lists.
  2. Import one content type, or the ten latest journal articles, into a test space. Give test entries names starting with TEMP.
  3. Check text, formatting, files, links and references in the preview.
  4. Fix the mapping and the transform, and run again. The import updates what it made.
  5. Add the harder parts one at a time: nested blocks, references, translations, archives.
  6. Then import everything into Staging, in batches by content type, folder or date if it's large.

Running again

Each entry keeps its key as its external ID, shown under Details in the entry's info panel. The next run finds the entries by it and updates them instead of creating new ones, from any computer or CI job. Two things follow from that:

  • Keys must stay the same from run to run. Use the old system's own ids, prefixed with the source, such as drupal:node:412, not positions or titles.
  • A run overwrites the fields it imports, including changes editors made in CMS Orbit since the last run. Once editors start work in CMS Orbit, import only new or changed items, or stop importing.

If you write your own import calls, send externalId with each create and find entries with GET{locale}/content?externalId=…. See Import content with the Management API.

Draft or published

Imported entries are drafts until you publish them, in CMS Orbit or with the import's --publish. Publishing runs the same checks as the Publish button, so the import reports what it could not publish, such as an image without alt text. Content types that need approval cannot be published by the import: send those entries for review instead, with POST{locale}/content/{id}/review. If the space blocks publishing on accessibility problems, those are reported too.

Publishing in bulk sends a Page published webhook for each entry. The SDK's handler expires that page's cache tags and the lists and sitemap; if your own handler rebuilds the whole website on each event, connect it after the import.

From Staging to Production

Import into Staging and check everything there. Then promote a folder or a whole language at once:

  • In CMS Orbit: open Pages, then Promote this language to… in the … menu, or Promote to… on a folder. Check shows how many entries would be added, updated or left as they are, and which redirects come along; then promote. See Promote a folder or a language.
  • From the command line: npx cms-orbit promote --from staging --to production --region europe --locale en-GB, with --dry-run to check first and --folder <id> for one folder.
  • With the API: POST{locale}/promote, which handles 100 entries per call. See Management API.

Promotion publishes in Production what is published in Staging; drafts stay behind. Links and references point at the Production copies of the entries they name, in whatever order they arrive. Redirects belong to an environment, so the redirects for that language, or to and from the folder's pages, come along unless you turn them off. Promoting again only changes what changed since.

You can also import again into Production: copy the import file, set environment to Production, and run it on the copy.

Media and taxonomies belong to the whole space, so both environments share them.

7Validate

Compare the new website with the old one before anyone else sees it:

  • Counts: the number of entries of each content type, and of each language, against the inventory.
  • Every old address: each one should be a page or a redirect. The script below asks the Delivery API about every address in a list, with a Staging secret key, and prints those that are neither.
  • Broken links: SEO › Not found › Broken links in the CMS lists links to drafts, deleted pages, deleted files and addresses nothing covers. See Fix missing addresses and broken links.
  • SEO: SEO › Health checks titles, descriptions, headings and language links on drafts; work through the quick wins. See Improve SEO health.
  • Accessibility: Accessibility › Report lists every page's issues by WCAG rule. See Work through the accessibility report.
  • The schema: imports refuse fields and blocks the schema does not have. Regenerate your website's types with npx cms-orbit generate so the website's build fails on anything that doesn't match. See SDK.
  • Speed and the rendered pages: run Lighthouse, or Unlighthouse for every page, on the staging website.
  • Editors: ask the people who know the content to read the pages they own in the preview.
  • Search: with Gravity on, imported entries are indexed in the background as they are saved. If results look out of date after a large import, choose Rebuild under Configuration › Settings › Gravity. See Search by meaning.
check-addresses.mjsJavaScript
import { readFile } from 'node:fs/promises'const addresses = (await readFile(process.argv[2] ?? 'old-addresses.txt', 'utf8')).split('\n').filter(Boolean)const problems = []for (const address of addresses) {  const url = new URL('https://api.bifrostorbit.com/cms/v1/resolve')  url.search = new URLSearchParams({ url: new URL(address, 'https://northwilds.com').pathname, draft: 'true' })  const response = await fetch(url, { headers: { Authorization: `Bearer ${process.env.CMS_SECRET_KEY}` } })  const { data } = await response.json()  if (data?.kind !== 'page' && data?.kind !== 'redirect') problems.push(`${data?.kind ?? response.status} ${address}`)}console.log(problems.length ? problems.join('\n') : `All ${addresses.length} addresses are a page or a redirect`)
Shell
export CMS_SECRET_KEY=cms_sk_…node check-addresses.mjs old-addresses.txt

old-addresses.txt holds one address per line, from the old sitemap and your analytics. For several regions or languages, add region and locale to the request.

8SEO

  • Redirects: every changed address needs one, ideally a 301. The import file's redirects cover the addresses you know about. For lists from elsewhere, such as the old system's own redirects, use SEO › Redirects › Import CSV: it checks every row and shows what would change before importing. See Create and import redirects.
  • Chains: a redirect to an address that is itself redirected goes straight to the end, so old redirects pointing at addresses you are now moving still take one hop.
  • Later moves: once live, a published page that gets a new address, or a folder that moves, adds its own redirect.
  • Metadata: bring titles and descriptions across in each entry's seo. To check or fix them in bulk, SEO › Metadata exports every page's title and description as CSV and imports the file back. See Edit search titles and descriptions.
  • Canonicals, hreflang, sitemaps and robots.txt come from CMS Orbit through the SDK. See Metadata, sitemaps and robots with the SDK.
  • Search engines: after launch, submit the new sitemap in Google Search Console. Once your website serves its IndexNow key file, CMS Orbit tells Bing and the other IndexNow search engines about each page published in Production.

9Launch

  1. Freeze the old system. Agree a date after which nobody edits there, and tell the editors.
  2. Run the final import. Export again and run the transform and import: changed items are updated and new ones added. Items deleted in the old system are not removed by the import; delete them in CMS Orbit, with a redirect if they had an address.
  3. Move to Production: promote each language, with its redirects, after a dry run.
  4. Go through the go-live checklist in Deploy your website: domains, robots.txt, sitemap, canonicals, webhooks.
  5. Switch the domain to the new website.
  6. Keep the old website running at another address for a few days, so you can switch back if something serious turns up.

Once live, your website keeps serving published content even if CMS Orbit cannot be reached, from the SDK's mirror; see Deploy your website.

10After launch

  • Watch missing addresses: SEO › Not found lists the addresses visitors asked for that have no page, with how often and which pages linked there. Check it daily for the first weeks and add redirects.
  • Keep checking: SEO health and the accessibility report each show a trend over the last 90 days, so you see whether the score holds.
  • Support the editors: walk them through the new model, and point them at the help in CMS Orbit and Orbit AI, which answers questions from these guides. Watch for content that doesn't fit the model, and change the schema with Schema as code where it helps.
  • Switch off the old system once nothing points at it, and archive the raw export.
  • Clean up: delete test spaces and TEMP entries, and management tokens made for the migration.
  • Look back: write down what went well and what to change, while you remember.

Integrations

There is no plugin marketplace to migrate to. What the old system did through plugins comes across in one of these ways:

  • A Bifröst Orbit satellite: products and checkout with Commerce Orbit, trips with Travel Orbit, appointments with Booking Orbit, jobs with Careers Orbit, reviews with Presence Orbit, analytics with Insights Orbit. Their content reaches pages through blocks.
  • Webhooks and the API: other systems react to publishing through Webhooks, and read content through the Delivery API.
  • Your website: analytics tags, consent banners and third-party widgets usually belong in the website's code, not the CMS.
  • AI agents: an agent connected over MCP can draft and fix content for review. See Connect an AI agent.

Checklist

Copy it into your issue tracker:

Text
Discovery- [ ] Inventory of content types with counts- [ ] Every public address, from the sitemap, a crawl and analytics- [ ] Existing redirects from the old system- [ ] Files, where they are, and which are resized copies- [ ] Relationships and links between items- [ ] Languages, markets and what differs between them- [ ] Integrations and plugins, and what replaces each- [ ] Editors interviewed; what to script and what to rebuild by handDesign- [ ] Content types and components in schema as code, dry run clean- [ ] Regions, languages and domains created- [ ] Address plan: kept addresses and redirects- [ ] Mapping file for every source field- [ ] Proof of concept reviewed by editors in the preview- [ ] Roles, region limits and approval set up by handExport and transform- [ ] Raw export taken, dated and kept unchanged- [ ] Taxonomy terms imported from CSV- [ ] Rich text cleaned; images and embeds moved into blocks- [ ] Internal links rewritten or turned into Link fields- [ ] Original dates kept in fields- [ ] Exception list of items that could not be mappedImport- [ ] Dry run of the import file clean- [ ] Sample import in a test space with TEMP names, checked- [ ] Full import in Staging, in batches if large- [ ] Keys stable from run to run, prefixed with the source- [ ] Alt text in every language- [ ] Entries published or sent for reviewValidate- [ ] Counts per content type and language match the inventory- [ ] Every old address is a page or a redirect- [ ] No broken links in SEO › Not found- [ ] SEO health and language checks worked through- [ ] Accessibility report worked through- [ ] Website types regenerated and the build passes- [ ] Lighthouse on the staging website- [ ] Editors have read their pagesLaunch- [ ] Old system frozen- [ ] Final import run; deleted items removed with redirects- [ ] Content and redirects in Production- [ ] Go-live checklist done- [ ] Domain switched; old website kept at another address- [ ] Sitemap submitted to Google Search ConsoleAfter launch- [ ] SEO › Not found checked daily for the first weeks- [ ] Editors trained and supported- [ ] Old system switched off and the export archived- [ ] Test spaces, TEMP entries and migration tokens removed

Guides for each source platform

Each guide maps the platform's concepts to CMS Orbit, exports its content and transforms it into the import file for Import content with the Management API.

  • Contentful: content types, entries and locales map closely to CMS Orbit; the main work is rich text and embedded entries. See Migrate from Contentful.
  • Sanity: the schema lives in your Studio's code, and Portable Text and document-level translations need transforming. See Migrate from Sanity.
  • Storyblok: stories built from blocks map almost one to one, and datasources import as taxonomies from their CSV. See Migrate from Storyblok.
  • WordPress: a post's body is one piece of HTML with images and Gutenberg blocks inside, so most of the work is splitting it into blocks. See Migrate from WordPress.
  • Drupal: nodes, fields, paragraphs and taxonomy vocabularies, with translations per node. See Migrate from Drupal.
  • Adobe Experience Manager: pages built from components in a content tree, with assets in AEM Assets. See Migrate from AEM.
  • Sitecore: items built from templates, with renderings on pages and language versions per item. See Migrate from Sitecore.
  • Strapi: collection and single types, components and dynamic zones. See Migrate from Strapi.
  • Prismic: custom types built from slices, with documents per locale. See Migrate from Prismic.
  • Hygraph: a GraphQL schema of models, components and references. See Migrate from Hygraph.
  • Payload: collections and globals defined in code, with blocks fields. See Migrate from Payload.
  • Directus: collections over your own SQL database, with relations and translations. See Migrate from Directus.
  • Webflow: CMS collections, with static pages built in the Designer. See Migrate from Webflow.

From another system, follow the plan above and write the transform yourself: the import file format is the same whatever the source.

Have Orbit Studio do it

Orbit Studio, the team behind Bifröst Orbit, also designs and builds websites on CMS Orbit, and moving your content in, with redirects from the old addresses, is part of a project. How it is moved depends on where it is now, so it is part of the estimate. See Orbit Studio and Have your website built by Orbit Studio.

Was this page helpful?

Read next

Import content with the Management APIBring entries, blocks, images, references, translations and redirects into CMS Orbit from any source with the cms-orbit import command, with a dry run first and safe to run again. The migration guides build on it.Schema as codeKeep your content types and components in your repository and create or change them from a script or CI with the Management API, with a dry run, safe field changes and generated types.Model your contentWhen to use a content type, a component, a slot, a reference, a shared section, a global entry or a taxonomy, with a worked model for the Northwilds website.Management APIEvery endpoint scripts and integrations use to change content, schema, media and settings, with tokens, permissions, bodies, answers, errors and limits.Regions and languagesBuild a website with several regions or languages: address patterns and the folders for each, reading the right region and language, fallbacks and notices, hreflang, language switchers, previews and cache refresh per region.Create and import redirectsSend visitors from an old address to a new one, by hand or many at once from a spreadsheet, and export what you have.Fix missing addresses and broken linksFind the addresses visitors could not reach and the links inside the CMS that lead nowhere, and mend them with redirects or edits.Deploy your websiteRun a staging website for previews and a live website for visitors, with the right keys, settings and webhook for each, on Vercel, Netlify, Docker or a static host, and keep the website up if the CMS cannot be reached.