Skip to content

Migrate from Sitecore

Move a Sitecore site to CMS Orbit from SitecoreAI (XM Cloud) or XP 10: how templates, renderings, datasources, placeholders, the media library, language versions and redirect maps map, reading every page's layout with the Experience Edge GraphQL schema, turning components into blocks and data items into entries and taxonomy CSV, and importing it with redirects.

How-to guide17 min read

Sitecore keeps a page as an item with fields, and its body as renderings in placeholders, each with a datasource item for its content. CMS Orbit keeps a page as an entry with fields and a list of blocks, so renderings map to components and their datasource fields to the block's fields. This guide reads every page's layout with Sitecore's Experience Edge GraphQL schema, as a headless website does, turns it into an import file and a taxonomy CSV, and imports them with the script from Import content with the Management API. The examples move the Northwilds journal: article pages, authors and topics as data items, and English, Norwegian and German language versions. If you haven't planned the move yet, start with Plan a migration.

The guide assumes SitecoreAI (formerly XM Cloud) with an SXA headless site, or Sitecore XP 10.3 or 10.4 with Headless Services 21 or later. Both answer the same GraphQL queries from the content management (CM) instance. For XP without Headless Services, see XP without Headless Services.

How Sitecore maps to CMS Orbit

Site, such as an SXA site under /sitecore/content/Northwilds/Northwilds
CMS Orbit
Space
Notes
Several sites in one tenant become a space each, or regions of one space when they share content
Page item (an item with a layout)
CMS Orbit
Entry
Page template
CMS Orbit
Content type
Notes
Fields from base templates go on each content type that uses them
Standard values
CMS Orbit
A field's default
Notes
Set through the Management API
Rendering
CMS Orbit
Component
Datasource item
CMS Orbit
The block's fields
Notes
A datasource shared by many pages becomes a shared section
Rendering parameters
CMS Orbit
Fields on the component, such as a select for a style
Placeholder
CMS Orbit
The page's blocks, or a Components slot
Notes
Nested placeholders become slots
Partial designs and page designs (SXA)
CMS Orbit
Shared sections, and your website's layout
Data items, such as authors
CMS Orbit
Entries of their own content type, referenced from pages
Items used as a list of options, such as topics
CMS Orbit
Taxonomy
Notes
Import them as CSV: see Read and transform the content
Media library
CMS Orbit
Media library
Notes
Alt text per language
Language versions
CMS Orbit
Languages in a region
Notes
Each language holds its own copy of the entry, linked as translations
Language fallback
CMS Orbit
Language fallback
Notes
Set per language
Numbered versions and workflow
CMS Orbit
Drafts, reviews and scheduled publishing
Redirect maps (SXA), aliases
CMS Orbit
Redirects
Notes
Exact addresses, without patterns
Dictionary items
CMS Orbit
A global entry, or your website's own text
Pages editor, Experience Editor
CMS Orbit
Live preview with click-to-select
Experience Edge delivery
CMS Orbit
Delivery API
Notes

Field types:

Single-Line Text
CMS Orbit
text
Multi-Line Text
CMS Orbit
textarea
Rich Text
CMS Orbit
richtext
Integer, Number
CMS Orbit
number
Checkbox
CMS Orbit
boolean
Date, Datetime
CMS Orbit
date or datetime
Image, File
CMS Orbit
asset
General Link
CMS Orbit
link
Droplink, Droptree
CMS Orbit
reference, or taxonomy when it picks from a list of options
Droplist
CMS Orbit
select
Multilist, Treelist, Multilist with Search
CMS Orbit
references, or taxonomyTerms when they pick from a list of options
Checklist
CMS Orbit
multiselect or taxonomyTerms
Name Value List, Name Lookup Value List
CMS Orbit
Not yet: model the data as fields

Before you start

  • An API key for the CM instance's GraphQL endpoint, https://<CM host>/sitecore/api/graph/edge, which reads the master database, drafts included. In SitecoreAI, generate a Preview API key for the environment in SitecoreAI Deploy. In XP, create an API key item under /sitecore/system/Settings/Services/API Keys and copy its item id. Requests send it in the sc_apikey header.
  • The site's name, as in the SXA site grouping or the site definition, such as northwilds.
  • Media the import can download. The import fetches each file from its address without a sign-in. If the CM host asks for one, run the queries against the Experience Edge Delivery API instead, https://edge.sitecorecloud.io/api/graphql/v1 with a delivery token, whose media addresses are public for published items.
  • In CMS Orbit: a space with Staging, a region and every language you need, and a management token. See "Before you start" in Import content with the Management API.
  • Node 24 or later. It runs the TypeScript script below as it is, with no build step.

1Create the content model

List your page templates and datasource templates under /sitecore/templates/Project/Northwilds, in the Content Editor or as YAML with Sitecore CLI serialization (dotnet sitecore ser pull). Each page template becomes a content type, with the fields of its base templates. Each rendering editors place becomes a component, with its datasource template's fields, and rendering parameters that change what visitors see as extra fields. Write them in a schema.mjs and create them with Schema as code. Keep Sitecore's field names, in camel case, where they read well.

The script below assumes the journal model from that guide, with a topics taxonomy, and these Sitecore items mapped to it:

Article page template with Title, Excerpt, PublishedOn, Cover (image), Author (droptree) and Topics (multilist), and renderings in headless-main
CMS Orbit
journalPost with excerpt, publishedOn, cover, author and topics, and the renderings as blocks
Author items under Data/Authors with Name, Bio (rich text) and Photo (image)
CMS Orbit
author with bio and photo
Topic items under Data/Topics with Title
CMS Orbit
topics taxonomy
RichText rendering with a Text field
CMS Orbit
text
Image rendering with Image and ImageCaption
CMS Orbit
imageBlock with image and caption
GearList rendering with Heading, and GearItem renderings in its placeholder
CMS Orbit
gearList with heading and an items slot
GearItem rendering with Name and Link (general link)
CMS Orbit
gearItem with name and link

2Read and transform the content

The script sends four GraphQL queries to the CM instance:

  • site { siteInfo { routes } } lists every page under /journal in the main language, 100 at a time with a cursor.
  • layout(site, routePath, language) gives a page's layout, the same JSON a headless website renders: the page's own fields in route.fields, and its renderings in route.placeholders, each with componentName, the datasource's fields and any nested placeholders. It is read once per language.
  • item { children } lists the authors and the topics under the site's Data folder, with every field as jsonValue, once per language. If the CM answers Query is too complex to execute, lower first.
  • site { siteInfo { redirects } } gives the site's redirect maps.

It converts renderings with BLOCKS, keys every item by its id, and writes import.json, topics.csv and redirects-translations.csv. Adjust LANGUAGES, BLOCKS and newUrl to your site:

sitecore.tsTypeScript
import { writeFile } from 'node:fs/promises'const ENDPOINT = process.env.SITECORE_GRAPHQL ?? 'https://cm.northwilds.com/sitecore/api/graph/edge'const API_KEY = process.env.SITECORE_API_KEY ?? ''const SITE = 'northwilds'const DATA = '/sitecore/content/Northwilds/Northwilds/Data'const MAIN = 'en'const LANGUAGES: Record<string, string> = { en: 'en-GB', 'nb-NO': 'nb-NO', 'de-DE': 'de-DE' }type Json = Record<string, any>type Block = { type: string; fields: Json; children?: Record<string, Block[]> }type Route = { routePath: string; route: Json }async function graphql(query: string, variables: Json): Promise<Json> {  const response = await fetch(ENDPOINT, {    method: 'POST',    headers: { sc_apikey: API_KEY, 'Content-Type': 'application/json' },    body: JSON.stringify({ query, variables }),  })  const result = await response.json()  if (!response.ok || result.errors) throw new Error(`Sitecore answered ${response.status}: ${JSON.stringify(result.errors)}`)  return result.data}const ROUTES = `query Routes($site: String!, $language: String!, $paths: [String], $first: Int, $after: String) {  site { siteInfo(site: $site) { routes(language: $language, includedPaths: $paths, first: $first, after: $after) {    results { routePath }    pageInfo { endCursor hasNext }  } } }}`const LAYOUT = `query Layout($site: String!, $routePath: String!, $language: String!) {  layout(site: $site, routePath: $routePath, language: $language) { item { rendered } }}`const CHILDREN = `query Children($path: String!, $language: String!, $first: Int, $after: String) {  item(path: $path, language: $language) { children(first: $first, after: $after) {    results { id name language { name } fields(ownFields: true) { name jsonValue } }    pageInfo { endCursor hasNext }  } }}`const REDIRECTS = `query Redirects($site: String!) {  site { siteInfo(site: $site) { redirects { pattern target redirectType } } }}`async function routes(language: string): Promise<Route[]> {  const list: Route[] = []  let after: string | null = null  do {    const data = await graphql(ROUTES, { site: SITE, language, paths: ['/journal'], first: 100, after })    const page = data.site.siteInfo.routes    for (const { routePath } of page.results) {      const layout = await graphql(LAYOUT, { site: SITE, routePath, language })      const route = layout.layout?.item?.rendered?.sitecore?.route      if (route) list.push({ routePath, route })    }    after = page.pageInfo.hasNext ? page.pageInfo.endCursor : null  } while (after)  return list}async function children(path: string, language: string): Promise<Json[]> {  const list: Json[] = []  let after: string | null = null  do {    const data = await graphql(CHILDREN, { path, language, first: 20, after })    const page = data.item?.children    if (!page) return list    for (const item of page.results) {      list.push({ ...item, fields: Object.fromEntries(item.fields.map((field: Json) => [field.name, field.jsonValue])) })    }    after = page.pageInfo.hasNext ? page.pageInfo.endCursor : null  } while (after)  return list}const guid = (id = '') => id.replace(/[{}-]/g, '').toLowerCase()const slugify = (text: string) =>  text.toLowerCase().replace(/ø/g, 'o').replace(/æ/g, 'ae').replace(/ß/g, 'ss').normalize('NFKD')    .replace(/[̀-ͯ]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b)const cell = (text = '') => (/[",\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text)const newUrl = (routePath: string) => routePath.toLowerCase().replace(/ /g, '-')const prefixes = new RegExp(`^/(${Object.keys(LANGUAGES).join('|')})(?=/)`, 'i')function asset(image?: { src?: string; alt?: string }) {  if (!image?.src) return null  const url = new URL(image.src, ENDPOINT)  url.search = ''  return { $asset: { url: url.href, alt: image.alt ?? '' } }}const main = await routes(MAIN)const urls = new Map(main.map(({ routePath }) => [routePath.toLowerCase(), newUrl(routePath)]))const pageIds = new Set(main.map(({ route }) => guid(route.itemId)))function localLinks(html: string) {  return html.replace(/href="([^"]+)"/g, (match, href: string) => {    const path = href.startsWith('/') ? href : href.startsWith('http') ? new URL(href).pathname : ''    const url = urls.get(path.replace(prefixes, '').toLowerCase())    return url ? `href="${url}"` : match  })}function link(value?: { href?: string; linktype?: string; id?: string }) {  if (!value?.href) return null  if (value.linktype === 'internal' && pageIds.has(guid(value.id))) return { $link: guid(value.id) }  if (value.linktype === 'mailto') return { kind: 'email', href: value.href.replace(/^mailto:/, '') }  return { kind: 'url', href: value.href }}function richText(html: string): Block[] {  const blocks: Block[] = []  for (const part of localLinks(html).split(/(<p>\s*<img[^>]*>\s*<\/p>)/)) {    const img = part.match(/^<p>\s*(<img[^>]*>)/)?.[1]    if (img) {      const image = asset({ src: img.match(/src="([^"]*)"/)?.[1], alt: img.match(/alt="([^"]*)"/)?.[1] })      if (image) blocks.push({ type: 'imageBlock', fields: { image } })    } else if (part.trim()) {      blocks.push({ type: 'text', fields: { text: part.trim() } })    }  }  return blocks}const BLOCKS: Record<string, (component: Json) => Block[]> = {  RichText: (component) => richText(component.fields?.Text?.value ?? ''),  Image: (component) => {    const image = asset(component.fields?.Image?.value)    return image ? [{ type: 'imageBlock', fields: { image, caption: component.fields?.ImageCaption?.value || null } }] : []  },  GearList: (component) => [{ type: 'gearList', fields: { heading: component.fields?.Heading?.value }, children: { items: placeholders(component) } }],  GearItem: (component) => [{ type: 'gearItem', fields: { name: component.fields?.Name?.value, link: link(component.fields?.Link?.value) } }],}function convert(component: Json): Block[] {  const map = BLOCKS[component.componentName]  if (map) return map(component)  if (component.placeholders) return placeholders(component)  console.warn(`No mapping for the ${component.componentName} rendering`)  return []}function placeholders(component: Json): Block[] {  return Object.values<Json[]>(component.placeholders ?? {}).flat().flatMap(convert)}const topicItems = await children(`${DATA}/Topics`, MAIN)const topicValues = new Map(topicItems.map((item) => [guid(item.id), slugify(item.name)]))const topicRows = new Map(topicItems.map((item) => [guid(item.id), [slugify(item.name), item.fields.Title?.value ?? item.name]]))function article({ routePath, route }: Route) {  const fields = route.fields ?? {}  return {    type: 'journalPost',    name: fields.Title?.value || route.displayName,    slug: newUrl(routePath).split('/').pop(),    url: newUrl(routePath),    fields: {      excerpt: fields.Excerpt?.value || null,      publishedOn: fields.PublishedOn?.value?.slice(0, 10) || null,      cover: asset(fields.Cover?.value),      author: fields.Author?.id ? { $ref: guid(fields.Author.id) } : null,      topics: (fields.Topics ?? []).flatMap((topic: Json) => topicValues.get(guid(topic.id)) ?? []),    },    components: (route.placeholders?.['headless-main'] ?? []).flatMap(convert),  }}function person(item: Json) {  return { type: 'author', name: item.fields.Name?.value || item.name, fields: { bio: localLinks(item.fields.Bio?.value ?? ''), photo: asset(item.fields.Photo?.value) } }}const entries: Json[] = [  ...(await children(`${DATA}/Authors`, MAIN)).map((item) => ({ key: guid(item.id), slug: slugify(item.name), ...person(item), translations: {} })),  ...main.map((page) => ({ key: guid(page.route.itemId), ...article(page), translations: {} })),]const byKey = new Map(entries.map((entry) => [entry.key, entry]))const translationRedirects: string[] = []for (const [language, code] of Object.entries(LANGUAGES).filter(([language]) => language !== MAIN)) {  for (const item of await children(`${DATA}/Authors`, language)) {    const entry = byKey.get(guid(item.id))    const bio = person(item).fields.bio    if (entry && item.language?.name === language && !same(bio, entry.fields.bio)) entry.translations[code] = { fields: { bio } }  }  for (const page of await routes(language)) {    const entry = byKey.get(guid(page.route.itemId))    if (!entry || page.route.itemLanguage !== language) continue    const { name, slug, url, fields, components } = article(page)    if (same({ name, fields, components }, { name: entry.name, fields: entry.fields, components: entry.components })) continue    entry.translations[code] = { name, slug, url, fields: { excerpt: fields.excerpt ?? undefined }, components }    if (url !== entry.url) translationRedirects.push([page.routePath, url, 301, 'europe', code].join(','))  }  for (const item of await children(`${DATA}/Topics`, language)) {    topicRows.get(guid(item.id))?.push(item.language?.name === language ? item.fields.Title?.value ?? '' : '')  }}const { site } = await graphql(REDIRECTS, { site: SITE })const redirects = (site.siteInfo.redirects ?? []).flatMap((rule: Json) => {  if (/[\^$*+?()[\]\\|]/.test(rule.pattern)) {    console.warn(`Pattern left out, add it by hand: ${rule.pattern}`)    return []  }  const from = rule.pattern.replace(/(.)\/$/, '$1')  const to = urls.get(rule.target.toLowerCase()) ?? rule.target  return [{ from, to, status: rule.redirectType === 'REDIRECT_302' ? 302 : 301 }]})for (const { routePath } of main) {  if (routePath !== newUrl(routePath)) redirects.push({ from: routePath, to: newUrl(routePath) })}await writeFile('import.json', JSON.stringify({  environment: 'staging',  region: 'europe',  locale: LANGUAGES[MAIN],  translations: Object.keys(LANGUAGES).filter((language) => language !== MAIN).map((language) => LANGUAGES[language]),  entries,  redirects,}, null, 2))await writeFile('topics.csv', [  ['value', 'label', ...Object.keys(LANGUAGES).filter((language) => language !== MAIN).map((language) => `label:${LANGUAGES[language]}`)].join(','),  ...[...topicRows.values()].map((row) => row.map((text) => cell(text)).join(',')),].join('\n'))await writeFile('redirects-translations.csv', ['source,destination,status,region,locale', ...translationRedirects].join('\n'))console.log(`Wrote ${entries.length} entries, ${topicRows.size} topics and ${redirects.length + translationRedirects.length} redirects`)
Shell
export SITECORE_API_KEY=<preview API key>SITECORE_GRAPHQL=https://cm.northwilds.com/sitecore/api/graph/edge node sitecore.ts

What it does with the parts that need thought:

  • Renderings map one to one with BLOCKS, by componentName. A rendering without a mapping that has placeholders of its own, such as an SXA container or column splitter, is opened and its renderings taken in order, so the page's blocks come out flat. Any other rendering without a mapping is left out with a warning, so you see what is missing.
  • Nested placeholders, such as the gear list's gear-items-{*} placeholder, become the slot's children.
  • Only headless-main becomes the page's blocks. Header and footer placeholders usually come from partial designs: rebuild them once, as global entries or shared sections.
  • Rich text arrives with Sitecore's links already turned into addresses. Links to other pages become their new addresses, without the language prefix. A paragraph holding only an image becomes an imageBlock. CMS Orbit keeps headings, paragraphs, lists, quotes, tables and links, and removes images, div, span and classes when it saves.
  • References go through ids: a droptree to an author becomes a $ref to the author's item id, a general link to a page becomes a $link to it, and the import fills in the CMS Orbit ids. Sitecore writes the same id in several forms, such as {A1B2…} and a1b2…, so guid makes them one.
  • Media: an image's address points at the media library, with resizing in the query string. The script drops the query string, so the import downloads the original. Alt text comes from the image field or the media item, per language. The import sets a file's alt text once, in the main language, so add the Norwegian and German alt text in the media library before publishing those copies.
  • Language versions: the script reads each page and each data item in every language, and keeps a translation only where it is in that language and differs from the main one, so content filled in by language fallback is left to CMS Orbit's copy. A translation brings its title, excerpt and blocks. Where a site puts display names in addresses, translated addresses go into redirects-translations.csv, each for its own language.
  • Topics: topics.csv has a row per item under Data/Topics, with the item's name made into a slug as the value, such as ski-touring, and its Title in each language as the labels.
  • Redirects: rules from the site's redirect maps with a plain address come across, pointed at the new address where the target is a page. Server transfers, which showed another page at the same address, become 301 redirects. Rules with a pattern are listed for you to add by hand: CMS Orbit's redirects are exact addresses. Pages whose address changes, such as /Journal/Lofoten in winter becoming /journal/lofoten-in-winter, get a redirect too.

XP without Headless Services

Without Headless Services, read items with the Sitecore Item Service REST API on the CM instance. Sign in with POST/sitecore/api/ssc/auth/login and a domain, username and password, then read an item and its children with GET/sitecore/api/ssc/item/?path=…&database=master&language=nb-NO and GET/sitecore/api/ssc/item/{id}/children?database=master&language=nb-NO. The answers hold raw field values: rich text keeps dynamic links such as ~/link.aspx?_id=… and media links such as -/media/….ashx that you resolve through the same id lookup, and a page's renderings are XML in its __Final Renderings field. Installing Headless Services and using the script above is usually quicker.

3Other content

  • Other page templates: read them from the same routes, without paths or with their own, and add a function like article for each template, by route.templateName.
  • Shared datasources: a datasource item used on many pages, such as a newsletter sign-up, is easier to keep as a shared section. Import it once with type: 'sharedSection', and map its rendering in BLOCKS to a sharedSection block with a $ref to it, by component.dataSource.
  • Dictionary items: site { siteInfo { dictionary } } lists them, per language. Move the text into a global entry, or into your website's own translations.
  • Several sites: run the script once per site, into a space each, or into a region each with its own region.

4Import

  1. In CMS Orbit, open Schema › Taxonomies, open the topics taxonomy and choose Import CSV. Pick topics.csv, check the preview and choose Import. See Tag content with taxonomies.
  2. Check the file with a dry run, then run the import, with cms-orbit from Import content with the Management API:

``bash npx cms-orbit import import.json --dry-run npx cms-orbit import import.json ``

  1. Open SEO › Redirects, choose Import CSV and pick redirects-translations.csv.

Check the entries in CMS Orbit on Staging, then run the import again with --publish, or publish them in CMS Orbit. Promote them to Production with their redirects as described in Plan a migration.

5Switch the website

  1. A Next.js website built with the Sitecore Content SDK or JSS already has a component for each rendering. Register them under the new component keys, and replace <Placeholder> with the SDK's blocks. See Render components.
  2. Replace the layout and GraphQL calls with the SDK: cms.resolve({ path }) for a page, cms.list({ type: 'journalPost' }) for an index. See Connect a website.
  3. Replace the Pages editor or Experience Editor with CMS Orbit's live preview. See Set up the live preview.
  4. Point webhooks at your website, so publishing refreshes the cache. See Webhooks.
  5. Promote the content to Production and point the domain at the new website. Old addresses then redirect through resolve.

What does not come across

  • Numbered versions and workflow history. Each entry starts with one draft.
  • Personalisation rules, Sitecore Personalize and CDP, and xDB analytics. Use Experiments for A/B tests.
  • Forms. Not yet in CMS Orbit: keep them in a forms service.
  • Item security and roles. People sign in with Orbit and get roles in CMS Orbit.

Was this page helpful?

Read next