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

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

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

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

Field types:

| AEM | CMS Orbit |
| --- | --- |
| Single line text, `textfield` | `text` |
| Multi line text (plain text), `textarea` | `textarea` |
| Multi line text (rich text), `richtext` | `richtext` |
| Multi line text (Markdown) | `richtext`: convert it to HTML while you transform |
| Number, `numberfield` | `number` |
| Boolean, `checkbox` | `boolean` |
| Date and time, `datepicker` | `date`, or `datetime` when the time matters |
| Enumeration, `select` | `select` or `multiselect` |
| Tags, `tagfield` | `taxonomy` or `taxonomyTerms` |
| Content Reference or `pathfield` to an asset | `asset` or `assets` |
| `pathfield` to a page | `link` |
| Fragment Reference | `reference` or `references` |
| Composite `multifield` | `components` slot with a small component for one item |
| JSON Object | 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](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 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](https://docs.bifrostorbit.com/cms/developers/schema-as-code/).

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

| AEM | CMS Orbit |
| --- | --- |
| Article page with `jcr:title`, `jcr:description`, `cq:tags`, and the project's own `articleDate` and `authorFragment` page properties | `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) | `author` with `bio` and `photo` |
| Core Text component (`northwilds/components/text`) | `text` |
| Core Image component (`northwilds/components/image`) | `imageBlock` with `image` and `caption` |
| `northwilds/components/gear-list` container with a `heading` | `gearList` with `heading` and an `items` slot |
| `northwilds/components/gear-item` with `name` and a `link` | `gearItem` with `name` and `link` |
| `northwilds:topics` tags | `topics` taxonomy |

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

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

```bash
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](https://docs.bifrostorbit.com/cms/developers/image-address/).
- **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.

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

## 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. Build a component on your website for each component key, in place of the HTL templates. See [Render components](https://docs.bifrostorbit.com/cms/developers/render-blocks/).
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](https://docs.bifrostorbit.com/cms/developers/connect-a-website/).
3. Replace the Universal Editor or SPA 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. 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](https://docs.bifrostorbit.com/cms/developers/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.
