DocumentationAEMUser Guide

Migrate a Production Site production-migration

Last update: November 12, 2026
  • Applies to:
  • Experience Manager as a Cloud Service

CREATED FOR:

  • User
  • Admin
  • Developer

Use this workflow to move an agreed list of pages to Edge Delivery Services, the Adobe Experience Manager service that delivers websites. Start with a sample page for each template, settle how its content and design map to the new site, and import more pages only once the samples work in the editor that your authors will use. If terms such as blocks, default content, or preview are new to you, see How Your Site Is Built and Updated and Shape the Content Structure.

For a few demonstration pages or a first evaluation, use the smaller demo and trial workflows. They don’t need the checks that a production site needs before release.

Agree Scope and Destinations scope

The migration lead and architect agree the scope and destinations. You need authorization to read the source, modify the target repository, and write content and assets to the destination. Agree who signs off the result and who authorizes release. If some pages require sign-in, set up protected site authentication with a dedicated read-only account. If the source blocks automated visitors, arrange access with its administrator before cataloging. See Source Sites with Bot Protection.

Record:

Input
Decisions to retain
Source inventory
Domains, page URLs, locales, documents, assets, and excluded or retired content.
Code
Repository, working branch, review policy, and release owner.
Content destination
Which of the two storage options the project uses.
Design
Preserve the source appearance or apply a new design. Name the approved reference and version.
Behavior
Navigation, forms, search, commerce, consent, analytics, personalization, and other integrations that must work. Identify their owners.
URL policy
Destination paths, redirects, canonical URLs, language relationships, and links to retain.
Recovery
Code baseline, content backup and recovery process, and authority to overwrite or publish.

Page import copies each page’s content and design. Integrations and CMS features run on the source’s servers, such as search, form processing, personalization rules, and content inheritance, so import copies only their output on each page. List them under Behavior and decide how each works on the new site. See Limitations.

A console workspace works on one site at a time. In a program with several sites, agree their order, and push and upload each site’s work before you open the next one with Switch site.

Relaunch a Site That Runs on Experience Manager relaunch-aem-site

Once your team has decided on the relaunch, the workflow is the same as for any other source. These points are specific to an Experience Manager source:

  • Your other sites: The agent reads the source site’s pages and doesn’t change the source. It writes only to the new site’s Git repository and to the content destination that you choose, so your organization’s other Experience Manager sites keep running as they are, and so does the source site until you switch its domain at release. With Experience Manager authoring, the upload writes pages under /content/{site-name} and images under the site’s Assets folder, and replaces any page already at that path, so agree both with the author instance’s administrator. See Upload Content.
  • How the agent reads the source: The agent reads each page as a browser renders it, not the source’s components, templates, or repository. Components, experience fragments, and content inheritance therefore don’t carry over as such: their output appears on each page. Decide which shared content to keep once on the new site. See What Remains Project Work.
  • Where content goes: The destination is your choice, as for any source; see Where Content Is Stored and How Authors Edit It. Experience Manager authoring needs an Experience Manager as a Cloud Service author instance, so an author instance that runs elsewhere can’t be the destination.
  • Repositories: If your code is in a repository connected through Cloud Manager, the console works with it too. See Use Another Git Host.
  • Decisions for your team: Languages, inheritance between markets, and approval workflows are your team’s decisions. Import gives you the pages at their source paths, not these structures. Record them with the other scope decisions before you catalog.

Prepare and Catalog prepare

  1. Follow shared console setup, or Experience Manager authoring setup if the content goes to Experience Manager authoring. Reuse an existing project’s configuration rather than recreate it.
  2. Ask the agent to catalog the authorized site: Scope site https://www.example.com. The site catalog discovers pages and groups them into templates (pages that share a layout) and block variants.
  3. Review the catalog in the Planning view. Correct template and block groupings and investigate failed URLs.
  4. Compare the discovered URLs with your agreed page list. Add pages that discovery missed, and decide explicitly about failed, skipped, duplicate, or excluded URLs.
  5. Pick a sample page for each template and important variant. Cover long content, unusual images, locales, and pages with a lot of interaction.

Cataloging reads the source and imports nothing. A run with the status complete can still have failed pages; see Results and Status. Before moving on, give every in-scope URL a template or an approved exclusion.

How the Agent Migrates at Scale migration-at-scale

The agent doesn’t send every page through the AI model. Interpreting each page separately wouldn’t scale to thousands of pages, and the model could treat similar pages slightly differently each time. Instead, the AI model works out the mapping on one sample page per template, and the agent turns that mapping into code that runs on the template’s other pages:

  1. Group pages into templates. The site catalog groups the source site’s pages into templates, which are pages that share a layout. If you migrate pages without a catalog, each page that you name starts a template of its own.
  2. Migrate a sample page. For each template, the agent first migrates one real page that shows the template’s typical layout and, ideally, most of its blocks and variants. The site catalog proposes one for each template. If another page of the template shows more of its blocks, choose that page instead: blocks that the sample page lacks are only added later, when an imported page needs them. The AI model maps the sample page’s content to default content and blocks, and creates the blocks that it needs or reuses existing ones.
  3. Generate an import script. The agent writes an import script for the template: one part, the parser, extracts each block’s content from the source HTML, and another, the transformer, cleans up the page as a whole. The scripts are JavaScript files in the project’s tools/importer/ folder, versioned in Git with the rest of your code.
  4. Refine the pattern, not the page. When you ask for a correction, the agent changes the block or the import script that produced the result instead of editing one page’s output. The correction then applies to every page of the template, and later templates reuse the blocks that already exist.
  5. Import the remaining pages in bulk. The bulk import runs the import script on the template’s other pages without the AI model interpreting each one. The agent then compares the imported pages with their source pages, fixes the import script for pages that differ too much, and imports those pages again.

Validate a few pages of each template before you import all of them. See Import in Batches.

The same applies to changes in content structure, such as which content becomes a block or where a page splits into sections: change the import script. It is code, reviewed and merged like the rest, and the next import applies it to every page of the template. An edit to one imported page stays local, and importing the template again overwrites it.

To change the templates and blocks themselves, such as moving pages to another template or making one block a variant of another, use the Planning view or ask in chat. The agent follows these changes the next time it generates blocks or imports pages, and pages that you already imported don’t change. To consolidate the design, see Restyle Sites. To consolidate block code, see Refactor Without Changing the Outcome.

NOTE
A template in the console is a group of source pages with the same layout, which the agent uses to plan and import them. It isn’t the template page metadata, which adds a class to the page’s body element so that the project’s code can style those pages differently. To align the two, ask the agent to set the metadata in the import script, so that every page of the template gets it on import, for example: “For the article template, set the page metadata template to article in the import script, and give article pages a narrower main column.”

Validate Sample Pages representatives

The migration lead, designers, and authors settle the first template together. Start with a few of its pages. For example:

Migrate only these product pages: https://www.example.com/products/tents, https://www.example.com/products/backpacks, and https://www.example.com/products/boots. Store the content as document-based content under /products. Keep the approved text, links, metadata, and image meaning. Reuse the project’s blocks and content conventions. Report missing content and interactions that the import doesn’t reproduce. Do not upload, push, or publish.

Replace the example URLs and paths with your own, and for Experience Manager authoring, say that the content is stored in the JCR.

  1. Review the content structure: the sections, default content, blocks, variants, and section styles that the agent chose. Authors will edit every migrated page in this structure, so settle it on the sample pages. See Shape the Content Structure.

  2. Compare imported text, links, images, metadata, and section order with the source. When a pattern is wrong, fix the import script, not the page. See How the Agent Migrates at Scale.

  3. Apply source styling or follow the redesign workflow. Check global styles before refining individual blocks.

  4. Complete the shared header, navigation, and footer separately from page import. The agent migrates them, including footer images, once for the whole site, so that every page shares one header and one footer.

  5. Upload a sample page to the content destination, then edit, save, reopen, and preview it:

  6. Record the agreed mapping from source to output, the block models, design decisions, and known exceptions before you import more pages.

A page that looks right still fails if authors can’t edit it. For Experience Manager authoring, also check block models, generated component configuration, conversion errors, and where images are stored before you import more.

Shape the Content Structure content-structure

Authors edit every migrated page in the structure that the agent chooses on import, and the bulk import repeats that structure on every page of a template. Edge Delivery Services pages are made of sections that contain default content and blocks; see Markup, Sections, Blocks, and Auto Blocking. The agent follows David’s Model and keeps the structure as plain as the design allows, because every block and variant is one more thing for authors to learn.

Structure
What the agent does on import
How to steer it
Section
Splits the page where its background or layout changes. Empty space between parts of a page is spacing, not a section.
Ask it to merge sections that authors see as one part of the page, or to split one that does two jobs.
Default content
Keeps everything that an author could type in a document as default content: headings, paragraphs, lists, links, and inline images. CSS lays it out however the design needs.
Where it created a block for content of this kind, ask it to use default content and style it with CSS.
Block
Uses a block for repeated items, interactive components, and fixed side-by-side layouts. Similar items that flow and wrap become cards; columns hold a fixed set of different content side by side. A photo background belongs to its block, such as a hero. It reuses a block of the project before it creates one.
Name the block that a pattern should use, or ask it to reuse an existing one. See Compose Before Creating a Block.
Block variant
Creates a variant, such as cards-compact, for a small difference in look that authors choose. Content with different fields or a different job gets a block of its own. Optional content and a different number of items don’t make a variant.
Ask it to merge variants that differ only slightly, or to turn a variant whose fields differ into a block of its own.
Section style
Gives a section a style in its section metadata when its background differs from the page’s, its alignment isn’t the default, or its default content sits beside a block. It names the style after the look, such as dark, light-grey, or centered. Text and buttons in the section take their color from the style, so a color alone never creates a block or a variant.
Agree on the list of section styles and their names, so that authors choose from the same few on every page.

To steer the structure:

  1. Before you migrate, review the catalog in the Planning view and correct block names and groupings there. See Refining the Catalog.
  2. Record the blocks, variants, and section styles of the project in AGENTS.md, so that the agent reuses them on later pages and in later sessions. See Document Content Conventions.
  3. Check each sample page in the Document view of the preview panel, which shows its sections, blocks, and default content. See Content Views.
  4. Correct a wrong pattern in the import script so that the bulk import repeats the correction on every page. See How the Agent Migrates at Scale.
  5. Ask an author to edit a sample page. If they hesitate over which block, variant, or style to use, there are too many choices.

Keep the choices that authors make few. The design system should make the decisions that authors shouldn’t have to: when a block needs more than a handful of variants or options, ask whether some of them belong in the design.

Estimate Before You Commit estimate

The catalog and the first sample pages give you an estimate based on the work that the site needs, not on its page count:

  1. Catalog the site. The catalog lists the templates, block variants, and locales, and the URLs that failed. See Prepare and Catalog.
  2. Validate sample pages of the main templates. Record what each one needed: new blocks, corrections to import scripts, styling, and changes to the content structure.
  3. Size the remaining templates from what the sample pages needed. Later templates reuse the blocks that already exist, so count the blocks that each one adds. A page with a layout of its own counts as a template of its own.
  4. Add the items that import doesn’t cover: the behavior that you recorded under Behavior in the scope, and the project work that your team decides and builds.

Check the estimate against the first batch’s record per URL.

Work as a Team collaboration

Several people can work on the same project with the agent, each in their own console workspace. They share code through Git and content through the content destination. The console doesn’t show who is working on what, and it doesn’t merge two people’s changes to the same page, so agree who works on what and keep talking to each other.

Scope matters more with an agent than without one. A single request can change many files, so when two people change the same blocks or styles at the same time, someone has to resolve conflicts across many files by hand.

Lead the Migration phases

A migration runs in phases. The agent does most of the repetitive work in each one, and your team makes the decisions and signs off the result. Let one person, such as the migration lead, run the first phases; others join once the blocks and import scripts are settled. See Work as a Team.

Visual contributors can work on styling from the sample-pages phase onward. See Make Visual Changes.

Start with One Person, Then Divide the Work divide-work

The first steps lay the foundation that everything else builds on: the global styles, the first blocks, and the import scripts of the first templates. Let one person set them up. Before you divide the work, check that the blocks fit real content and are easy for authors to use. See Shape the Content Structure.

Once the team agrees on the blocks, divide the work so that people change different files:

  • By block: One person refines the cards block while another builds a carousel.
  • By template: Each person refines the import script of a different template. See How the Agent Migrates at Scale.
  • By expertise: A designer refines the styling of existing blocks while a developer builds an integration.

Don’t give two people the same block, the global styles, or the same import script at the same time unless they agree how to coordinate.

Share Code in Small Steps share-code

  1. Agree on a shared branch, such as main or a development branch. Each person switches their workspace to it with Switch branch in the Code view.
  2. Keep each request to the agent focused on one block, template, or task. Push the result as soon as it works, with Create new PR: the console pushes your changes to a new branch, opens a pull request into the shared branch, and leaves your workspace on the new branch.
  3. Review and merge pull requests often. Small changes conflict less and are quicker to review, and a pull request that stays open for days collects conflicts.
  4. Before you start a new task, switch back to the shared branch with Switch branch and pull it with Sync > Pull > Code, so that you build on everyone’s merged work.

If a pull is unavailable or reports a conflict, see If Someone Else Changed the Branch.

Small, frequent pushes also give the team a readable history of what the agent changed and why. To get one commit per request, see Leave a Record of Each Request.

Coordinate Content Changes share-content

Content has no merge. Your workspace holds copies of the pages, and an upload replaces the page in the content destination with your copy. If two people change the same page, the last upload wins, and the other person’s changes are lost. Give each page, or set of pages, to one person at a time.

To get pages that others uploaded into your workspace:

  • Open a page that shows a cloud icon in the content view. The console downloads it into your workspace.
  • In document-based projects, select Sync > Pull > Content to download every page from Experience Workspace. It replaces your local copies, including edits that you haven’t uploaded, so upload the edits that you want to keep first.

Import in Batches batches

Use the catalog bulk-import workflow and bulk-import prompts after you validate the sample pages.

  1. Import a small batch with the template’s import script.
  2. Check ordinary pages and edge cases. If the import script is wrong, correct it and import the affected pages again before you continue.
  3. Keep a record for each source URL: destination, import state, errors, sign-off, and any approved exclusion.
  4. Continue template by template. Count discovered, analyzed, imported, failed, skipped, and signed-off pages separately.
  5. Recheck earlier sample pages when you change shared styles, import scripts, block models, or block code.

Once authors start editing the migrated pages in the content destination, their pages become the source of truth. Importing or uploading those pages again overwrites the authors’ work, and a corrected import script doesn’t merge it, so agree with the authors first.

Complete the Site complete-site

Automated import is one part of delivery. Implement and verify the agreed requirements, including:

  • Header, footer, navigation, internal links, and error pages.
  • Images, downloads, fonts, asset permissions, and any retained Dynamic Media references.
  • Titles, descriptions, canonical URLs, structured data, redirects, sitemaps, and locale relationships where required.
  • Forms, search, commerce, account features, analytics, consent, and other integrations.
  • Author guidance, operational ownership, access, and deployment configuration.

The agent implements the code side of these, for example blocks that call your search or commerce API, forms, and the code that loads analytics and consent. It can’t configure systems outside your repository and content, such as the search service, the CDN, or the analytics account, and it doesn’t decide your requirements. Give it the API documentation and the agreed behavior, and name an owner for each external system who signs off the result. See Connect Services and Applications, for forms, Form Submissions, and for product pages, Commerce Pages.

Images and Documents assets

How images reach the new site depends on the content destination:

  • Experience Workspace: While you work in the console, an imported page can still reference images on the source site. When you upload the page, the console uploads its images with it, including images that it downloads from the source, into a folder named after the page with a leading dot. It then points the page to the uploaded copies. If an image is missing, in an unsupported format, or ambiguous, the console reports it and doesn’t upload the page. After the upload, it checks that every image arrived. See Upload Content.
  • Experience Manager authoring: Select Upload images when you upload the content package, and choose a folder under /content/dam/. The default is /content/dam/site. See Upload Content.
  • Adobe Dynamic Media: Images that the source serves from Dynamic Media, including Scene7 and Dynamic Media with OpenAPI URLs, stay there. The imported page references them, and the project’s code renders them.

Edge Delivery Services serves images in sizes and formats that fit each screen. Check large files, videos, and SVG images against the limits for file types and sizes.

Check the links to documents, such as PDFs, on the sample pages. Each link must point to a copy on the new site, not to the source site that you will retire.

URLs, Redirects, and Search Metadata urls-seo

The agent takes each page’s path from its source URL. It lowercases the path, removes .html, turns a trailing / into index, and replaces other characters, such as spaces and underscores, with hyphens. /About_Us.html becomes /about-us. Every URL that changes this way, or that you change on purpose, needs a redirect.

The agent doesn’t create redirects, sitemaps, or language alternates by itself. Ask it for them as a task, and review the result:

  • Redirects: A redirects spreadsheet with Source and Destination columns, one row per URL, without wildcards. Ask the agent to list the source URLs whose path changed, as rows for the sheet. See Redirects.
  • Page metadata: Import keeps each page’s title, description, and social image in its metadata block. To set metadata for many pages at once, use a metadata spreadsheet. See Bulk Metadata.
  • Sitemap and languages: A helix-sitemap.yaml file in the repository, which can include the language alternates (hreflang) of each page. See Sitemaps.
  • Search engines: The preview and live sites, *.aem.page and *.aem.live, are hidden from search engines; your production domain isn’t. Check robots.txt before the cutover. See robots.txt.
  • Query index: Lists of pages, such as article listings and site search, read from a query index that includes only published pages. See Indexing.

Check and Sign Off acceptance

Agree with the site owner what must work before release, and test it on the preview and live sites. The site owner signs off the result with testers and authors.

Area
Signed off when
Coverage
Every in-scope URL has a destination or an approved exception. Failed and skipped pages are resolved or recorded.
Content
Text, links, assets, metadata, and locale content are complete and correct.
Authoring
Authors can edit typical fields and blocks, save, reopen, and preview the result in their editor.
Design
Approved desktop and mobile layouts work on real content, including long text and block variants.
Function
Navigation, keyboard interaction, forms, integrations, and agreed user journeys work.
Quality
Accessibility, performance, and relevant SEO and security checks meet the project’s agreed requirements. Automated accessibility tools find only the issues that a rule can detect, so also test sample pages with a keyboard and a screen reader. Test performance with PageSpeed Insights; on GitHub, Edge Delivery Services runs the same check on each pull request for the test URLs in its description.
Operations
Repository review, content publication, recovery, monitoring, and support ownership are documented and tested as needed.

Each automated signal checks one thing: an importer status that the script ran, a generated package that content was converted, a visual similarity score that a page looks like its source, and a Lighthouse score how one page loads in a lab test. Production readiness needs every area in the table.

Release, Recover, and Hand Over handoff

The release owner coordinates the code merge, content publication, and domain cutover, then confirms that the site’s ongoing owners have taken it over.

  1. Push the signed-off code and have it reviewed as the repository’s policy requires. Merging into main updates the live site’s code immediately, so plan the merge with the content release. See How Changes Go Live.
  2. Upload only the signed-off content and images to the confirmed destination. Review the errors for each page and image.
  3. Verify the saved content with the intended code revision on the preview site, *.aem.page.
  4. Obtain the site’s release approval and follow the configured publication and domain cutover process. Publishing makes pages available on *.aem.live; the cutover is what serves them on your own domain, through the Adobe-managed CDN or your own CDN. Work through the go-live checklist before the cutover.
  5. Check the live URLs, redirects, key journeys, and monitoring after release. Operational Telemetry shows how real visitors experience the site’s performance.
  6. Provide the project handover, the record per URL, author examples, sign-off results, exceptions, and recovery contacts.

When something fails, keep the exact URL or path, the operation, and the error log. Retry the smallest affected scope after you correct the cause. Don’t restart a successful batch because one page failed.

Pushing code, uploading documents, importing a content package into Experience Manager, and publishing are separate operations on separate systems. A partial failure can leave only some changes applied, and no single rollback undoes all of them. Recover code through Git, and content and images through the version history of the content destination or your agreed process.

recommendation-more-help
experience-manager-cloud-service-help-main-toc