Skip to content

Migrate from Adobe Experience Manager

Move an AEM Sites site to CMS Orbit: how pages, components, Content Fragments, Experience Fragments, DAM assets, tags, language copies and live copies map, reading pages as JSON with the Sling Model Exporter and fragments with GraphQL, turning components into blocks and tags into taxonomy CSV, and importing it with redirects.

How-to guide16 min read

Adobe Experience Manager (AEM) keeps a page as a tree of components under /content, and structured content as Content Fragments in the DAM. CMS Orbit keeps a page as an entry with fields and a list of blocks, so components map to components and fragments to entries. This guide reads pages from AEM's author service as JSON with the Sling Model Exporter (.model.json), reads Content Fragments with AEM's GraphQL API, turns them 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 with Core Components, authors as Content Fragments, a topics tag namespace, and English, Norwegian and German language copies. If you haven't planned the move yet, start with Plan a migration.

The guide assumes AEM as a Cloud Service with Core Components and the Adobe Client Data Layer turned on, which new projects from the AEM project archetype have. AEM 6.5 offers the same .model.json, QueryBuilder and GraphQL routes; sign in with a user there instead of a token.

How AEM maps to CMS Orbit

Site, such as /content/northwilds
CMS Orbit
Space
Page
CMS Orbit
Entry
Page template
CMS Orbit
Content type
Notes
Its page properties become fields, and its allowed components the content type's allowed components
Component
CMS Orbit
Component
Notes
Your own components and the Core Components you use
Container, layout container
CMS Orbit
Blocks in order, or a Components slot
Notes
Column widths from the layout mode don't come across: your website lays out the blocks
Content Fragment Model
CMS Orbit
Content type, or component
Content Fragment
CMS Orbit
Entry
Content Fragment variation
CMS Orbit
Not yet
Notes
Import the master. Keep a variation that a channel needs as an entry of its own
Experience Fragment
CMS Orbit
Shared section
DAM asset
CMS Orbit
File in the media library
Notes
CMS Orbit makes sizes on request, so renditions are not needed
Tag namespace, such as northwilds:topics
CMS Orbit
Taxonomy
Notes
Terms are a flat list. Import them as CSV: see Read and transform the content
Localised tag titles
CMS Orbit
Labels per language
Language masters and language copies
CMS Orbit
Languages in a region
Notes
Each language holds its own copy of the entry, linked as translations
MSM blueprint and live copies
CMS Orbit
Copies in other regions
Notes
A copy is linked to its source and editors choose Update from source. A cancelled inheritance becomes a field marked Differs by region. See Copy a page to another region or language
sling:vanityPath
CMS Orbit
A redirect to the entry's address
sling:alias
CMS Orbit
The entry's slug in that language
Redirect maps in the dispatcher or in ACS AEM Commons
CMS Orbit
Redirects
Launches
CMS Orbit
Releases
Workflows
CMS Orbit
Reviews
Universal Editor, SPA Editor
CMS Orbit
Live preview with click-to-select
HTL templates, client libraries, dispatcher
CMS Orbit
Your website
Notes
CMS Orbit is headless: your website draws the pages

Field types:

Single line text, textfield
CMS Orbit
text
Multi line text (plain text), textarea
CMS Orbit
textarea
Multi line text (rich text), richtext
CMS Orbit
richtext
Multi line text (Markdown)
CMS Orbit
richtext: convert it to HTML while you transform
Number, numberfield
CMS Orbit
number
Boolean, checkbox
CMS Orbit
boolean
Date and time, datepicker
CMS Orbit
date, or datetime when the time matters
Enumeration, select
CMS Orbit
select or multiselect
Tags, tagfield
CMS Orbit
taxonomy or taxonomyTerms
Content Reference or pathfield to an asset
CMS Orbit
asset or assets
pathfield to a page
CMS Orbit
link
Fragment Reference
CMS Orbit
reference or references
Composite multifield
CMS Orbit
components slot with a small component for one item
JSON Object
CMS Orbit
Not yet: model the data as fields

Before you start

  • An access token for the author service. In Cloud Manager, open the environment's Developer Console, then Integrations. Local token gives a token for 24 hours, enough for a test. For the full run, create a technical account there and exchange its service credentials for an access token. Give the technical account's user read access to /content, /content/dam and /content/cq:tags in AEM.
  • A GraphQL endpoint for the site's configuration, such as /content/cq:graphql/northwilds/endpoint, under Tools › General › GraphQL.
  • Assets published, or a publish service that serves them. The import downloads each file from its address without a sign-in, so the script points at the publish service.
  • 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 templates under Tools › General › Templates, your components in the project's ui.apps (/apps/northwilds/components), and your Content Fragment Models under Tools › General › Content Fragment Models. Each template becomes a content type, with its page properties as fields. Each component editors place becomes a component, with its dialog fields as fields. Content Fragment Models become content types when the fragments have their own page or are referenced, such as authors, and components when they only exist inside one page. Write them in a schema.mjs and create them with Schema as code.

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

Article page with jcr:title, jcr:description, cq:tags, and the project's own articleDate and authorFragment page properties
CMS Orbit
journalPost with excerpt, topics, publishedOn and author, and the page's components as blocks
Author Content Fragment with name, bio (rich text) and photo (content reference)
CMS Orbit
author with bio and photo
Core Text component (northwilds/components/text)
CMS Orbit
text
Core Image component (northwilds/components/image)
CMS Orbit
imageBlock with image and caption
northwilds/components/gear-list container with a heading
CMS Orbit
gearList with heading and an items slot
northwilds/components/gear-item with name and a link
CMS Orbit
gearItem with name and link
northwilds:topics tags
CMS Orbit
topics taxonomy

2Read and transform the content

The script reads from the author service, with the token as a bearer token:

  • Pages: a QueryBuilder search, /bin/querybuilder.json?path=…&type=cq:Page&p.limit=-1, lists every page under the journal in each language master. For each page, {page}/jcr:content.json gives its page properties, and {page}.model.json its components as JSON, with each container's children in :items and their order in :itemsOrder. Each component says what it is in :type, such as northwilds/components/text.
  • Content Fragments: a GraphQL query, authorPaginated, lists the authors under each language's DAM folder, 100 at a time with a cursor. Each asset's alt text comes from its dc:description in {asset}/jcr:content/metadata.json.
  • Tags: /content/cq:tags/northwilds/topics.1.json gives every tag in the namespace, with its localised titles in jcr:title.{language}.

It converts components with BLOCKS, matches each language copy to its master by its path below the language root, and writes import.json, topics.csv and redirects-translations.csv. Adjust LANGUAGES, BLOCKS and oldUrl to your site:

aem.tsTypeScript
import { writeFile } from 'node:fs/promises'const AUTHOR = process.env.AEM_AUTHOR ?? 'https://author-p12345-e67890.adobeaemcloud.com'const PUBLISH = process.env.AEM_PUBLISH ?? 'https://publish-p12345-e67890.adobeaemcloud.com'const HEADERS = { Authorization: `Bearer ${process.env.AEM_TOKEN}` }const SITE = '/content/northwilds/language-masters'const DAM = '/content/dam/northwilds'const MAIN = 'en'const LANGUAGES: Record<string, string> = { en: 'en-GB', nb: 'nb-NO', de: 'de-DE' }type Json = Record<string, any>type Block = { type: string; fields: Json; children?: Record<string, Block[]> }type Page = { path: string; relative: string; properties: Json; model: Json }type Fragment = { _path: string; name: string; bio?: { html: string }; photo?: { _path: string } }async function get(path: string): Promise<Json> {  const response = await fetch(`${AUTHOR}${path}`, { headers: HEADERS })  if (!response.ok) throw new Error(`AEM answered ${response.status} for ${path}`)  return response.json()}async function graphql(query: string, variables: Json): Promise<Json> {  const response = await fetch(`${AUTHOR}/content/cq:graphql/northwilds/endpoint.json`, {    method: 'POST',    headers: { ...HEADERS, 'Content-Type': 'application/json' },    body: JSON.stringify({ query, variables }),  })  const result = await response.json()  if (!response.ok || result.errors) throw new Error(`GraphQL answered ${response.status}: ${JSON.stringify(result.errors)}`)  return result.data}async function pages(language: string): Promise<Page[]> {  const root = `${SITE}/${language}`  const params = new URLSearchParams({ path: `${root}/journal`, type: 'cq:Page', 'p.limit': '-1' })  const { hits } = await get(`/bin/querybuilder.json?${params}`)  const list: Page[] = []  for (const { path } of hits as { path: string }[]) {    list.push({ path, relative: path.slice(root.length), properties: await get(`${path}/jcr:content.json`), model: await get(`${path}.model.json`) })  }  return list}const AUTHORS = `query Authors($root: String!, $after: String) {  authorPaginated(first: 100, after: $after, filter: { _path: { _expressions: [{ value: $root, _operator: STARTS_WITH }] } }) {    edges { node { _path name bio { html } photo { ... on ImageRef { _path } } } }    pageInfo { endCursor hasNextPage }  }}`async function authors(language: string): Promise<Fragment[]> {  const list: Fragment[] = []  let after: string | null = null  do {    const data = await graphql(AUTHORS, { root: `${DAM}/${language}/authors/`, after })    list.push(...data.authorPaginated.edges.map((edge: Json) => edge.node))    after = data.authorPaginated.pageInfo.hasNextPage ? data.authorPaginated.pageInfo.endCursor : null  } while (after)  return list}const altTexts = new Map<string, string>()async function asset(path: string | undefined, alt?: string) {  if (!path) return null  if (alt === undefined) {    if (!altTexts.has(path)) {      const metadata: Json = await get(`${path}/jcr:content/metadata.json`).catch(() => ({}))      altTexts.set(path, metadata['dc:description'] ?? metadata['dc:title'] ?? '')    }    alt = altTexts.get(path)  }  return { $asset: { url: `${PUBLISH}${encodeURI(path)}`, alt } }}const relativeTo = (path: string, root: string) => (path.startsWith(`${root}/`) ? path.slice(root.length) : null)function newUrl(page: Page) {  const alias: string | undefined = page.properties['sling:alias']  return alias ? page.relative.replace(/[^/]+$/, alias) : page.relative}const oldUrl = (url: string) => `${url}.html`const tagValue = (tag: string) => (tag.startsWith('northwilds:topics/') ? tag.split('/').pop() : undefined)const main = await pages(MAIN)const urls = new Map(main.map((page) => [page.path, newUrl(page)]))function link(href?: string) {  if (!href) return null  const page = relativeTo(href.replace(/\.html$/, ''), `${SITE}/${MAIN}`)  if (page && urls.has(`${SITE}/${MAIN}${page}`)) return { $link: `page:${page}` }  if (href.startsWith('mailto:')) return { kind: 'email', href: href.slice('mailto:'.length) }  return { kind: 'url', href }}function localLinks(html: string) {  return html.replace(/href="([^"]+)\.html"/g, (match, path: string) => {    const url = urls.get(path.replace(/\/language-masters\/[a-z]{2}\//, `/language-masters/${MAIN}/`))    return url ? `href="${url}"` : match  })}const BLOCKS: Record<string, (item: Json) => Promise<Block[]>> = {  title: async () => [],  text: async (item) => [{ type: 'text', fields: { text: localLinks(item.richText ? item.text : `<p>${item.text}</p>`) } }],  image: async (item) => {    const repoPath = Object.values<Json>(item.dataLayer ?? {})[0]?.image?.['repo:path']    const image = repoPath ? await asset(repoPath, item.alt ?? '') : { $asset: { url: new URL(item.src, PUBLISH).href, alt: item.alt ?? '' } }    return [{ type: 'imageBlock', fields: { image, caption: item.title ?? null } }]  },  'gear-list': async (item) => [{ type: 'gearList', fields: { heading: item.heading }, children: { items: await blocks(item) } }],  'gear-item': async (item) => [{ type: 'gearItem', fields: { name: item.name, link: link(item.link?.url) } }],}async function blocks(container: Json): Promise<Block[]> {  const list: Block[] = []  for (const key of container[':itemsOrder'] ?? []) {    const item = container[':items'][key]    const map = BLOCKS[item[':type'].split('/').pop()]    if (map) list.push(...(await map(item)))    else if (item[':items']) list.push(...(await blocks(item)))    else console.warn(`No mapping for the ${item[':type']} component`)  }  return list}async function article(page: Page) {  const fragment = page.properties.authorFragment ? relativeTo(page.properties.authorFragment, `${DAM}/${MAIN}`) : null  return {    type: 'journalPost',    name: page.properties['jcr:title'],    slug: newUrl(page).split('/').pop(),    url: newUrl(page),    fields: {      excerpt: page.properties['jcr:description'] ?? null,      publishedOn: page.properties.articleDate?.slice(0, 10) ?? null,      author: fragment ? { $ref: `author:${fragment}` } : null,      topics: [page.properties['cq:tags'] ?? []].flat().flatMap((tag: string) => tagValue(tag) ?? []),    },    components: await blocks(page.model),  }}async function person(fragment: Fragment) {  return { type: 'author', name: fragment.name, fields: { bio: localLinks(fragment.bio?.html ?? ''), photo: await asset(fragment.photo?._path) } }}const entries: Json[] = []const mainAuthors = await authors(MAIN)for (const fragment of mainAuthors) {  const relative = relativeTo(fragment._path, `${DAM}/${MAIN}`) ?? fragment._path  entries.push({ key: `author:${relative}`, slug: relative.split('/').pop(), ...(await person(fragment)), translations: {} })}for (const page of main) entries.push({ key: `page:${page.relative}`, ...(await article(page)), translations: {} })const redirects = main.flatMap((page) => [  { from: oldUrl(newUrl(page)), to: newUrl(page) },  ...[page.properties['sling:vanityPath'] ?? []].flat().map((vanity: string) => ({ from: vanity, to: newUrl(page) })),])const translationRedirects: string[] = []for (const [language, code] of Object.entries(LANGUAGES).filter(([language]) => language !== MAIN)) {  for (const fragment of await authors(language)) {    const entry = entries.find((item) => item.key === `author:${relativeTo(fragment._path, `${DAM}/${language}`)}`)    if (entry) entry.translations[code] = { fields: { bio: localLinks(fragment.bio?.html ?? '') } }  }  for (const page of await pages(language)) {    const entry = entries.find((item) => item.key === `page:${page.relative}`)    if (!entry) continue    const { name, slug, url, fields, components } = await article(page)    entry.translations[code] = { name, slug, url, fields: { excerpt: fields.excerpt ?? undefined }, components }    if (url !== page.relative) translationRedirects.push([oldUrl(url), url, 301, 'europe', code].join(','))  }}const tags = await get('/content/cq:tags/northwilds/topics.1.json')const languages = Object.keys(LANGUAGES).filter((language) => language !== MAIN)const cell = (text = '') => (/[",\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text)const topics = Object.entries(tags)  .filter(([, tag]) => tag?.['jcr:primaryType'] === 'cq:Tag')  .map(([value, tag]) => [value, tag['jcr:title'] ?? value, ...languages.map((language) => tag[`jcr:title.${language}`] ?? '')].map(cell).join(','))await writeFile('import.json', JSON.stringify({  environment: 'staging',  region: 'europe',  locale: LANGUAGES[MAIN],  translations: languages.map((language) => LANGUAGES[language]),  entries,  redirects: redirects.filter((redirect) => redirect.from !== redirect.to),}, null, 2))await writeFile('topics.csv', [['value', 'label', ...languages.map((language) => `label:${LANGUAGES[language]}`)].join(','), ...topics].join('\n'))await writeFile('redirects-translations.csv', ['source,destination,status,region,locale', ...translationRedirects].join('\n'))console.log(`Wrote ${entries.length} entries, ${topics.length} topics and ${translationRedirects.length} translated redirects`)
Shell
export AEM_TOKEN=<access token>AEM_AUTHOR=https://author-p12345-e67890.adobeaemcloud.com AEM_PUBLISH=https://publish-p12345-e67890.adobeaemcloud.com node aem.ts

What it does with the parts that need thought:

  • Components map by the last part of their :type, such as text for northwilds/components/text. A container without a mapping, such as a layout container, is opened and its children taken in order, so the page's blocks come out flat. A component without a mapping is left out with a warning, so you see what is missing. The Title component is left out, because the page's title is the entry's name.
  • Rich text: the Text component's text is HTML. CMS Orbit keeps headings, paragraphs, lists, quotes, tables and links, and removes div, span, classes and images when it saves. Links to other pages, such as /content/northwilds/language-masters/en/journal/what-to-pack.html, become their new addresses.
  • Images: the Image component's data layer gives the DAM path of the original, such as /content/dam/northwilds/journal/lofoten.jpg, and the import downloads it from the publish service. Alt text comes from the component, or from the asset's dc:description for fragments. 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. Renditions are not needed: CMS Orbit makes each size on request. See Serve images from your own domain.
  • References go through ids: the page's authorFragment becomes a $ref to the author with the same path below the language folder, and a link to a page becomes a $link to the entry made from it.
  • Language copies: a page in language-masters/nb/journal/… is the Norwegian copy of the page with the same path in language-masters/en, and a fragment in /content/dam/northwilds/nb/… of the English fragment with the same path. A copy brings its title, description and blocks, and keeps its own slug when it has a sling:alias.
  • Topics: topics.csv has a row per tag in northwilds:topics, with the tag's name as the value, jcr:title as the label, and jcr:title.nb and jcr:title.de as the Norwegian and German labels. Pages store the tag's name, such as ski-touring.
  • Redirects: each page's old address, here /journal/lofoten-in-winter.html, redirects to its new one, and so does each sling:vanityPath. Translated addresses from a sling:alias go into redirects-translations.csv, each for its own language. Change oldUrl to match your Sling mappings and dispatcher rewrites, so the redirects use the addresses visitors saw.

3Live copies, fragments and other content

  • Live copies: the script reads the language masters. If your markets are MSM live copies, such as /content/northwilds/no/nb, import the masters into one region, then copy them into each market's region in CMS Orbit with Copy to. Each copy stays linked to its source, so Update from source does what a rollout did. Where a market cancelled inheritance on a component to change it, run the script for that live copy's root into its own region instead, or make the change again after copying.
  • Experience Fragments: read each one's .model.json under /content/experience-fragments/northwilds and import it as a shared section, with type: 'sharedSection'. Map the Experience Fragment component in BLOCKS to a sharedSection block with a $ref to it.
  • Content Fragments as pages: for fragments with their own address, such as trips, write a query like authorPaginated for their model and map them as the script maps pages. The Content Fragments OpenAPI on the author service, GET/adobe/sites/cf/fragments?path=…, gives the same fragments with every field, 50 at a time with a cursor, if you prefer REST.
  • Other templates: read their pages with the same QueryBuilder search under another path, and map their page properties to fields.
  • Redirect maps: add the rules from your dispatcher or redirect manager to the import file's redirects, pointed at the new addresses. CMS Orbit's redirects are exact addresses, without patterns, so expand a rule with a pattern into the addresses it covers, or keep it in your website's own routing.

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. Build a component on your website for each component key, in place of the HTL templates. See Render components.
  2. Replace the page model calls of an SPA Editor app, or the persisted GraphQL queries of a headless app, with the SDK: cms.resolve({ path }) for a page, cms.list({ type: 'journalPost' }) for an index. See Connect a website.
  3. Replace the Universal Editor or SPA 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. Addresses ending in .html and vanity addresses then redirect through resolve.

What does not come across

  • Page versions, launches in progress and workflow history. Each entry starts with one draft.
  • Content Fragment variations. Import the master; see the table above.
  • Personalisation with Adobe Target, and ContextHub segments. Use Experiments for A/B tests.
  • Closed user groups. Pages that need a sign-in are your website's job.
  • Users, groups and permissions. People sign in with Orbit and get roles in CMS Orbit.

Was this page helpful?

Read next