# 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.

Source: https://docs.bifrostorbit.com/cms/developers/migrate-from-sitecore/

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](https://docs.bifrostorbit.com/cms/developers/import-content/). 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](https://docs.bifrostorbit.com/cms/developers/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](#xp-without-headless-services).

## How Sitecore maps to CMS Orbit

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

Field types:

| Sitecore | CMS Orbit |
| --- | --- |
| Single-Line Text | `text` |
| Multi-Line Text | `textarea` |
| Rich Text | `richtext` |
| Integer, Number | `number` |
| Checkbox | `boolean` |
| Date, Datetime | `date` or `datetime` |
| Image, File | `asset` |
| General Link | `link` |
| Droplink, Droptree | `reference`, or `taxonomy` when it picks from a list of options |
| Droplist | `select` |
| Multilist, Treelist, Multilist with Search | `references`, or `taxonomyTerms` when they pick from a list of options |
| Checklist | `multiselect` or `taxonomyTerms` |
| Name Value List, Name Lookup Value List | 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](https://docs.bifrostorbit.com/cms/developers/import-content/).
- Node 24 or later. It runs the TypeScript script below as it is, with no build step.

## 1. Create 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](https://docs.bifrostorbit.com/cms/developers/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:

| Sitecore | CMS Orbit |
| --- | --- |
| Article page template with `Title`, `Excerpt`, `PublishedOn`, `Cover` (image), `Author` (droptree) and `Topics` (multilist), and renderings in `headless-main` | `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) | `author` with `bio` and `photo` |
| Topic items under `Data/Topics` with `Title` | `topics` taxonomy |
| `RichText` rendering with a `Text` field | `text` |
| `Image` rendering with `Image` and `ImageCaption` | `imageBlock` with `image` and `caption` |
| `GearList` rendering with `Heading`, and `GearItem` renderings in its placeholder | `gearList` with `heading` and an `items` slot |
| `GearItem` rendering with `Name` and `Link` (general link) | `gearItem` with `name` and `link` |

## 2. Read 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:

```ts
// sitecore.ts
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`)
```

```bash
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.

## 3. Other 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`.

## 4. Import

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](https://docs.bifrostorbit.com/cms/editors/taxonomies/).
2. Check the file with a dry run, then run the import, with `cms-orbit` from [Import content with the Management API](https://docs.bifrostorbit.com/cms/developers/import-content/):

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

3. 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](https://docs.bifrostorbit.com/cms/developers/plan-a-migration/).

## 5. Switch 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](https://docs.bifrostorbit.com/cms/developers/render-blocks/).
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](https://docs.bifrostorbit.com/cms/developers/connect-a-website/).
3. Replace the Pages editor or Experience Editor with CMS Orbit's live preview. See [Set up the live preview](https://docs.bifrostorbit.com/cms/developers/preview/).
4. Point webhooks at your website, so publishing refreshes the cache. See [Webhooks](https://docs.bifrostorbit.com/cms/developers/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](https://docs.bifrostorbit.com/cms/developers/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.
