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
/sitecore/content/Northwilds/Northwildsselect for a styleField types:
texttextarearichtextnumberbooleandate or datetimeassetlinkreference, or taxonomy when it picks from a list of optionsselectreferences, or taxonomyTerms when they pick from a list of optionsmultiselect or taxonomyTermsBefore 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 Keysand copy its item id. Requests send it in thesc_apikeyheader. - 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/v1with 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:
Title, Excerpt, PublishedOn, Cover (image), Author (droptree) and Topics (multilist), and renderings in headless-mainjournalPost with excerpt, publishedOn, cover, author and topics, and the renderings as blocksData/Authors with Name, Bio (rich text) and Photo (image)author with bio and photoData/Topics with Titletopics taxonomyRichText rendering with a Text fieldtextImage rendering with Image and ImageCaptionimageBlock with image and captionGearList rendering with Heading, and GearItem renderings in its placeholdergearList with heading and an items slotGearItem rendering with Name and Link (general link)gearItem with name and link2Read and transform the content
The script sends four GraphQL queries to the CM instance:
site { siteInfo { routes } }lists every page under/journalin 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 inroute.fields, and its renderings inroute.placeholders, each withcomponentName, the datasource'sfieldsand any nestedplaceholders. It is read once per language.item { children }lists the authors and the topics under the site'sDatafolder, with every field asjsonValue, once per language. If the CM answersQuery is too complex to execute, lowerfirst.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:
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`)export SITECORE_API_KEY=<preview API key>SITECORE_GRAPHQL=https://cm.northwilds.com/sitecore/api/graph/edge node sitecore.tsWhat it does with the parts that need thought:
- Renderings map one to one with
BLOCKS, bycomponentName. 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'schildren. - Only
headless-mainbecomes 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,spanand classes when it saves. - References go through ids: a droptree to an author becomes a
$refto the author's item id, a general link to a page becomes a$linkto it, and the import fills in the CMS Orbit ids. Sitecore writes the same id in several forms, such as{A1B2…}anda1b2…, soguidmakes 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.csvhas a row per item underData/Topics, with the item's name made into a slug as the value, such asski-touring, and itsTitlein 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 winterbecoming/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
pathsor with their own, and add a function likearticlefor each template, byroute.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 inBLOCKSto asharedSectionblock with a$refto it, bycomponent.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
- In CMS Orbit, open Schema › Taxonomies, open the
topicstaxonomy and choose Import CSV. Picktopics.csv, check the preview and choose Import. See Tag content with taxonomies. - Check the file with a dry run, then run the import, with
cms-orbitfrom Import content with the Management API:
``bash npx cms-orbit import import.json --dry-run npx cms-orbit import import.json ``
- 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
- 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. - 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. - Replace the Pages editor or Experience Editor with CMS Orbit's live preview. See Set up the live preview.
- Point webhooks at your website, so publishing refreshes the cache. See Webhooks.
- 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?