Aem

Adobe Experience Manager projects vary widely. Before writing migration code, determine:

• AEM 6.5 on-premise or AEM as a Cloud Service.
• Author-tier access, publish-tier access, or exported content only.
• Whether content is mostly pages with components, Content Fragments, Experience Fragments, DAM assets, or a mixture.
• Whether the site uses Core Components, custom components, or both.
• Whether Multi-Site Manager language copies are in scope.
• Whether unpublished drafts, inherited content, and Experience Fragments must be preserved.

Authentication

• AEM 6.5/on-premise commonly supports HTTP Basic auth with a read-only service account.
• AEM as a Cloud Service production does not use Basic auth; use Adobe IMS/service credentials or another approved bearer-token flow.
• Publish tier exposes published content only. Use author-tier access when drafts, unpublished content, or inherited authoring state is in scope.

Extraction Paths

Use the most structured source that covers the required scope:

• Content Fragments: use AEM GraphQL. Discover types from /content/_cq_graphql/global/endpoint.GQLschema, then query fragments through /content/_cq_graphql/global/endpoint.json.
• Core Component pages: use .model.json where Sling Model exporters are present.
• Custom component pages: use .infinity.json or .tidy.infinity.json to inspect raw JCR nodes under jcr:content.
• Bulk discovery: use QueryBuilder to enumerate pages, fragments, DAM assets, tags, and Experience Fragments.
• DAM assets: fetch binaries from /content/dam/... and metadata from /content/dam/.../jcr:content/metadata.json.
• Dialog/schema discovery: if repository or component paths are available, inspect _cq_dialog.infinity.json and sling:resourceSuperType chains to infer component fields.

Save raw extraction responses to disk before transforming. AEM APIs can be slow, auth-sensitive, and environment-specific.

aem-to-sanity Toolkit Pattern

For large AEM migrations, use or mirror the staged aem-to-sanity toolkit pattern from github.com/demo-repositories/aem-to-sanity.

Pipeline stages:

• Schemas (migrate:schema): fetch _cq_dialog.infinity.json, walk Granite UI dialogs and sling:resourceSuperType chains, discover slots/container drop zones, and emit Sanity object/page builder schemas.
• Types (typegen): generate sanity.types.ts from emitted schemas.
• Extract (aem-extract): walk content roots through .infinity.json, following depth truncation markers, and write raw files under an AEM cache directory.
• Tags (aem-tags): emit taxonomy/category documents from /content/cq:tags/... when AEM tags are in scope.
• Transform (aem-transform): map sling:resourceType through the generated registry, coerce string booleans/numbers, convert HTML to Portable Text, and resolve tag refs.
• Assets (aem-assets): dedupe, download from AEM, upload to Sanity Media Library or assets, link into the dataset, and rewrite clean documents.
• Import (aem-import): commit documents with transaction().createOrReplace(), importing categories before pages.

Operational defaults from the toolkit:

• Dry-run by default; real writes require MIGRATION_DRY_RUN=false.
• Per-tenant folders hold credentials, component paths, content roots, tag roots, component exceptions, generated caches, and reports.
• Run a doctor step before migration to catch missing env/config drift.
• Use content-derived identity: JCR path -> _id, JCR UUID -> _key, DAM path -> asset manifest key.
• Treat unknown component shapes as findings in reports, not immediate fatal errors, unless config or schema validation is broken.

Mapping to Sanity

Map AEM shapes by editorial meaning, not JCR structure:

• cq:Page with authored components can become a page document with a page builder array.
• Content Fragments usually become standalone document types.
• Reusable Content Fragments, Experience Fragments, tags, people, products, or snippets should become referenceable documents when reused.
• AEM text/RTE components become Portable Text fields or custom Portable Text objects.
• AEM image components become Sanity image fields with migrated asset references.
• AEM tags become taxonomy documents before content documents are written.
• MSM language copies can map to document-level localization with language fields and translation metadata documents.

Use sling:resourceType as the main discriminator for component-to-object mapping.

Transformation Notes

• Strip JCR/system fields such as jcr:primaryType, jcr:created, and sling:resourceType unless they are needed in migration metadata.
• Convert RTE HTML to Portable Text with source-specific preprocessing for empty paragraphs,   spacer rows, inline styles, spans, tables, and double-encoded entities.
• Normalize paths and slugs. AEM URLs often include /content/<site>/<locale>/... prefixes and .html extensions.
• Deduplicate DAM assets by full DAM path, asset UUID, or source URL before upload.
• Use deterministic IDs based on AEM paths or UUIDs.
• Create translations and parent/child references after all target documents exist.

Load Order

1. Taxonomies/tags from /content/cq:tags.
2. DAM assets or asset manifest.
3. Content Fragments and reusable Experience Fragments.
4. Page/content documents.
5. Translation metadata and post-import relationship fixes.

Gotchas

• .model.json can silently omit custom components without Sling Model exporters. Cross-check representative pages against .infinity.json.
• .infinity.json may be depth-limited or truncated on large trees. Detect truncation and recurse into child paths if needed.
• Publish-tier APIs expose published content only. Use author-tier access when drafts or unpublished changes are in scope.
• DAM URLs may require auth or point at internal hostnames. Verify asset fetchability before a large import.
• AEM tags are namespaced paths, not flat slugs.
• MSM inheritance can produce locale pages with inherited source-language fields. Detect identical translated fields before assuming content is localized.
• Experience Fragments live in a separate content tree and must be migrated before pages that reference them.
• Source-edited RTE content can contain layout tables, scripts, or arbitrary HTML that needs manual cleanup.

Validation Checklist

• Compare page, fragment, tag, Experience Fragment, and DAM counts against source queries.
• For each major template, verify every sling:resourceType has an explicit Sanity mapping or an intentional skip.
• Spot-check .model.json and .infinity.json parity for custom components.
• Confirm language variants have correct slugs, language fields, and translation metadata.
• Confirm all DAM references resolve to Sanity assets or Media Library assets.
• Crawl old AEM URLs and verify redirects to the new frontend.