How to migrate from Adobe AEM to a headless CMS

Plan an AEM move to headless delivery or Payload. Map fragments, assets and URLs, distinguish retention from replacement and check the new answer source.

To migrate from Adobe AEM to a headless CMS, first decide whether AEM remains the content source or you transfer its records to another CMS. AEM already delivers structured content headlessly. Moving its content to Payload requires field mapping and a rebuilt publishing system, including the frontend.

This procedure fits retail teams preserving approved product guidance and policy references during that change. Structured fields can move through supported APIs and a destination import. AEM page layouts, permissions and workflows need separate implementation. Broken references or an incorrect publication state can leave customers reading obsolete advice.

Decide whether AEM stays or is replaced

Retain AEM when your editorial workflow works and the main requirement is a separately built frontend. AEM Content Fragments supply structured content through documented delivery APIs. Your developers can change how customers see that content while editors keep their existing content owner.

Adobe documents headless delivery with Content Fragments and GraphQL for Cloud Service. It also documents Content Fragment Delivery with OpenAPI. These routes deliver content to an application that still needs its own rendering and preview setup.

A move to Payload changes the content owner as well as delivery. It fits a team choosing a code-defined collection model and accepting responsibility for rebuilding the editorial experience. Compare the proposed approval workflow with the one editors use now, including translation and restricted publishing.

Include hosting, database backups and file storage in the Payload operating plan. Compare the actual software agreement and implementation costs with your AEM contract. A content transfer does not end an existing licence agreement or recreate its service arrangements.

If the decision is still about AEM’s capabilities, use the Adobe CMS assessment. Choose the destination before designing an export, because retaining fragments and translating them into another record model are different projects.

Inventory the actual AEM content and dependencies

Inventory the deployed AEM version and each content object before selecting an extraction method. Separate Cloud Service from AEM 6.5 and 6.5 LTS, then use the documentation for that deployment.

Record these objects in the inventory:

  • Sites pages with their component trees and template dependencies.
  • Content Fragment Models with field types and validation rules.
  • Content Fragments with identifiers, variations and publication state.
  • Assets with original files, metadata and every referenced rendition.
  • Locales and language copies, including relationships between translated records.
  • Public URLs with canonical destinations and inbound references.
  • Integrations that supply catalogue facts or consume approved content.

Keep editor groups and publishing permissions in a separate access inventory. Identify the service accounts used for extraction and delivery. Record backups, their restore procedure and the point after which editorial changes need another export. Keep source content and media available throughout validation.

For Cloud Service, Adobe’s Content Fragment Management OpenAPI documentation directs existing Content Fragment Assets HTTP API usage to the management OpenAPI. The management interface operates on Author and requires authorised access for external integrations. Use the delivery interface for public consumption.

Do not treat a delivery response as a complete authoring backup. It contains the content that interface exposes, not every permission or workflow dependency. Adobe’s 6.5 LTS fragment documentation has its own version scope. Match the extraction method to that estate instead of applying Cloud Service endpoints to it.

The extraction example below assumes Cloud Service fragments. Page components and media need their own inventory and extraction work alongside the fragment records.

Map records into the destination model

Map every source field to a destination field, with an explicit action for presentation or behaviour that cannot transfer as data. When AEM stays, preserve its model identifiers and adapt the frontend to the delivery response. For Payload, define destination collections before importing records.

Fictional AEM-to-Payload transfer matrix

This example uses a retail buying guide and its delivery policy. The destination field names are proposed fields for this example.

Source itemSupported routeRetained valueSeparate rebuilding work
Fragment identifier and modelRead through the version-matched management APIOriginal identifier in a sourceId field and the selected destination collectionDefine each Payload collection and its validation rules
Heading and plain-text fieldsTransform returned fields into collection dataText and editorial labelsResolve differences in required fields before import
Rich-text bodyTransform into the destination editor’s data formatApproved wording and supported linksRecreate unsupported embeds and presentation
Fragment referencesImport referenced records, then update relationships using an ID mapThe relationship between guide and policyReplace source paths or identifiers with destination document IDs
Asset referencesRetrieve files, create destination uploads and repair referencesOriginal file and mapped metadataRebuild rendition URLs and verify image use rights
Variations and localesCreate the mapped destination fields or localised recordsEach selected language and variationDefine fallback behaviour and review missing translations
Public URLPreserve the route or create an explicit redirect entryIntended canonical destinationImplement routing and redirect responses in the frontend
Templates, permissions and workflowsInventory separately from content importReference documentation for the existing behaviourRecreate layout, roles and approval logic

Payload’s Import Export plugin accepts collection data in CSV or JSON. Its JSON import expects an array of document objects. Convert the AEM response into that destination structure before importing. A Payload-shaped JSON file is different from an unchanged AEM export.

For a custom importer, Payload’s Local API creates a document with payload.create, a collection slug and its data. The returned document supplies the destination ID. Use that ID to build a durable mapping for later reference repair.

For example, a fictional AEM policy identifier aem-policy-17 maps to Payload document policy-301. A guide identifier aem-guide-42 maps to guide-812. Replace the guide’s policy reference with policy-301 after creating both records. Keep the source identifiers in the migration log so a rerun can match existing records instead of creating duplicates.

The plugin supports create, update and upsert import modes. Select the mode deliberately and define the matching field before a repeat import. A stable sourceId field can support matching if your destination configuration makes it unique.

Keep import authority explicit. Payload’s Local API access-control guide states that local operations bypass access control by default. To enforce the import user’s rules, pass its authenticated user context and set overrideAccess to false. Review collection hooks before importing, because record creation can trigger configured side effects such as notifications.

Move content and validate the retail answers

Extract and transform a bounded content set first, then validate its records and references before changing public delivery. Run the first import in an isolated destination, with customer notifications disabled through the application’s configured controls.

  1. Capture the agreed source version. Export the selected fragments and model details through the supported management interface. Save media originals separately and record publication states. Set an editorial pause or a defined process for collecting changes made after extraction.
  2. Transform fields into the mapped destination schema. Convert rich text and preserve locale identifiers. Flag unsupported components for recreation, and keep drafts separate from approved records.
  3. Create media and content records. Use the chosen Payload import mode or Local API importer, then save each returned ID beside its source identifier. With retained AEM, keep the records and configure the new frontend against the selected delivery API.
  4. Repair references after the relevant destination IDs exist. Resolve nested fragments and media links. Render the guide in the destination preview, checking that its policy and product references point to the intended records.
  5. Reconcile counts and publication states. Compare accepted source records with created destination records for each collection and locale. Inspect import failures individually, then resolve them before publication. A draft source record must remain outside public delivery.
  6. Publish the approved test set through the destination workflow. Check the rendered frontend and its canonical URLs. Refresh the customer-answer source through the configured import or indexing process, then verify its policy answers.

Use a fictional acceptance set of 12 guides, two policies and 18 media files. If every item is in scope, expect those counts in the destination with zero unresolved references. Count language copies separately if they are separate records. Compare the final content, since equal counts can still hide a guide connected to the wrong policy.

For a policy check, change the approved dispatch window from two business days to four. Publish the changed record, refresh the frontend’s cache and update the shopping-answer source. The visible guide and an answer about dispatch must both use four business days. A draft alternative must remain absent from both.

A retained-AEM frontend can still display old content after publication. Adobe’s Cloud Service caching guide distinguishes Dispatcher invalidation from CDN expiry. Inspect the delivered content before the frontend, then inspect any separate answer index. Correct the layer that still holds the older policy.

If a media file is missing, compare its source identifier with the upload map and repair the destination reference. For the wrong locale, inspect the requested locale and fallback rule. Stop the publication changeover when public output contains a draft or a reference resolves to the wrong product.

Cut over with retained source records

Change public delivery only after the destination passes the agreed content and access checks, while retaining AEM and the source extracts. Assign the frontend owner to routing and releases. The identity owner handles access, while the integration owner handles content-source switching. Editors approve the final policy versions.

Preserve existing URLs where the content still fulfils the same purpose. For a changed URL, map the old path directly to its final destination. Payload’s Redirects plugin manages redirect records and supports redirect types such as 301. Your frontend must implement the actual redirect response. Test the old URL, the destination and its canonical URL together.

Collect the final editorial changes before switching the frontend and the customer-answer integration. Record which source each consumer now uses. Confirm that the old answer source stops contributing records, so a retired policy cannot compete with its replacement.

Keep the previous frontend release and its source configuration available during the transition. A return to that route needs reconciliation of edits made after the switch. It must also restore the intended answer-source selection. A routing change alone cannot undo content writes in another system.

For damaged Cloud Service content, Adobe documents content restoration through Cloud Manager. It restores content while leaving code and the AEM version unchanged. A full restore removes later content changes, so assess selective restoration first and have the authorised administrator approve the recovery target.

Where Payload versioning is enabled, its Versions documentation describes restoring a document to a retained prior version. That recovers the selected content record. Frontend releases, external integrations and media storage need their own recovery procedures.

Resolve failed extraction or AEM restoration with the authorised administrator through Adobe’s support route. Include the affected environment, object identifiers and a redacted error. For destination failures, use the team responsible for the Payload application and its contracted support arrangement.

After cutover, check public content again after a normal cache refresh and a new editorial publication. Keep AEM, backups and the ID map until those checks pass and the owner approves retirement. Reconcile outstanding contract charges and scheduled jobs before ending the old service.

Give your store its own shopping agent

Customers ask in their own words. Your agent finds, compares and checks out from your catalogue, right on your site.

See it in actionFree trial · Simple setup