AEM Sites Playbook, Chapter 20: Upgrades, migration, cutover and continuous improvement
Should we upgrade, migrate, launch, hold or retire the implementation?
November 10, 2026
Define the change and the decision it serves
Inventory what must survive
Check content, extensions, identities and operating assumptions.
Transfer a representative slice
Reconcile references and prove ordinary-role tasks.
Cut over or hold
Resolve mandatory gaps and assign recovery authority.
Use this chapter when choosing an upgrade, moving hosting/platform, changing authoring/delivery or retiring an implementation. State the business reason and compare a supported repair, a narrower modernization and the larger move. Record source and target releases, runtime, components, extensions, editors, delivery path, connected systems and support responsibilities.
Keep AEM 6.5 upgrades, 6.5 LTS transitions and Cloud Service migration as separate paths. Review 6.5 upgrade planning, LTS guidance, Core Component compatibility and the Cloud migration journey as applicable. Do not infer one path's procedures from another's name or service-pack number.
Inventory what must continue working
List content, assets, models, templates, dialogs, workflows, identities, permissions, integrations, queries/indexes, domains, URLs, redirects, measurement and recovery procedures. Identify legacy APIs or private customizations and the person who must assess each. Use representative author and customer tasks as the inventory's acceptance criteria.
In the LTS Content Fragment component discussion, existing content rendered but authors could not complete a new selection. A planned move to Core Components was not a confirmed repair. In the 6.5.21 deletion case, the author later implicated an extension version. Both cases require target-specific task tests beyond a successful installation.
For Cloud Service, examine cluster/interruption assumptions in custom code and integrations. The fixed-Publisher case requires duplicate/replay tests, while the POST endpoint case adds real public-route testing after an AMS move. If adopting Edge Delivery, reassess composition and reuse rather than assume traditional Experience Fragments transfer unchanged. Reuse discussion
Rehearse transfer and reconciliation
Choose a representative content slice that includes difficult references, permissions, versions/locales and media. Define source ownership, what the target may overwrite, how ongoing changes are captured and how source/target results are compared. A count alone cannot verify content meaning or working references.
For migration to Cloud Service, Adobe's Content Transfer Tool overview distinguishes extraction and ingestion and describes differential top-up capability. Follow the tool's current prerequisites and supported workflow rather than treat content transfer as a copy command. Rehearse the intended change/top-up behavior before setting a production freeze window.
Treat identities explicitly. Adobe's group-migration guidance explains that content-associated groups and IMS-related setup require assessment; the tool does not simply migrate users as local accounts. Validate actual user access and group relationships on the target. A principal report is evidence to inspect, not proof that every intended person has the right authority.
Prepare a controlled cutover
Step 1. Reconcile the final content/change set and verify required references and identities.
Step 2. Confirm compatible application/configuration versions and required tests on the target.
Step 3. Check domains, TLS, redirects, canonical/locale metadata, search, analytics and connected-system destinations.
Step 4. Record the cutover authority, hold conditions, monitoring owner, support cover and recovery/rollback procedure.
Step 5. Execute the authorized change, then observe the critical author and customer tasks through their real routes.
Define which changes make a rollback unsafe or require reconciliation of newer content. Record the decision point before the window, including who can authorize a limited launch. Avoid averaging away a failed mandatory requirement in a readiness score.
Choose the migration boundary from the requirement
Community discussions expose different migration boundaries: extension compatibility, LTS component authoring and clustered Cloud Service execution. Their reported or proposed outcomes cannot replace an assessment of the organization's full dependencies and operating model. Retain target-specific task tests for each affected boundary.
Scroll horizontally if needed.
| Proposed path | Primary assessment | Evidence before authorizing cutover |
|---|---|---|
| Repair or service-pack/dependency change | Compatibility and the failing task on a supported configuration | Reproduction, regression and recovery |
| Move to 6.5 LTS | Applicable source/target path, runtime and removed/changed dependencies | Supported release assessment, authoring and integration tests |
| Move on-premises/AMS content and code to Cloud Service | Cloud-compatible code, content/identity transfer and delivery operation | Rehearsed transfer, reconciliation, roles, APIs and cluster/retry behavior |
| Change authoring/delivery model | Composition, reuse, preview, frontend and content-consumer responsibilities | Representative editorial and customer journeys on the new model |
| Retire a system or channel | Remaining data, consumers, URLs, credentials and retention duties | Owned decommission plan and continuity evidence |
Use upgrade planning, LTS guidance and the Cloud migration journey for their respective paths. A commercial platform decision does not settle which code/content adaptations are required.
Worked scenario of an AMS to Cloud Service move
The migration set, findings and decisions below are hypothetical. An AMS-hosted site has two locales, shared assets, a product import, a publishing workflow and a job that contacts an external system. The target is Cloud Service. Business owners require that authors can keep making corrections, customer URLs continue to work and approved access is preserved.
The migration lead selects a representative slice: pages with shared references, localized fragments, protected content and integration state. The team records source content/code identities and explicitly identifies which state each tool transfers versus which must be configured or adapted separately.
Scroll horizontally if needed.
| Workstream | Rehearsal evidence | Acceptance owner |
|---|---|---|
| Content and assets | Required objects, references, locale relationships and outputs | Content/media owners |
| Authoring and workflow | Create / edit / compare / approve / withdraw with normal roles | Editorial owner |
| Identities and authority | Actual users can perform intended actions and fail denied ones | Identity/platform owners |
| Code and integrations | Compatible deployment, interruption/replay and external outcomes | Engineering/integration owners |
| Public continuity | Domains, routes, redirects, metadata, search and measurement | Channel/delivery owners |
| Operation and recovery | Alerts, support cover, recovery procedure and authority | Service owner |
For content transfer, the team follows the current extraction/ingestion and top-up guidance, including prerequisites and the intended overwrite behavior. For identity, it uses group-migration documentation and explicitly verifies IMS-related setup rather than assume transferred content creates every required user relationship.
Suppose the rehearsal reports matching object counts but reveals a French page using an English fragment, an ordinary approver unable to inspect shared content, and duplicate external notifications during a repeated job. Existing pages render successfully. Those observations produce three distinct holds; a count match and successful rendering cannot close them.
The team repairs the reference mapping, intended reviewer authority and duplicate/replay handling. It repeats the affected fixtures plus the broader critical journeys. In the hypothetical continuation, the selected slice passes, supporting the next controlled rehearsal. It does not immediately authorize all remaining content or an untested traffic range.
Control changes during the transition
Scroll horizontally if needed.
| Condition | Agreement needed | Verification |
|---|---|---|
| Source content continues changing | Authoritative source, freeze/top-up plan and owner | Final delta is reconciled against the intended target |
| Code changes during migration | Compatible source/target revisions and release sequencing | Same acceptance fixtures on the intended combination |
| Target accepts new content | Ownership of new writes and possible reverse reconciliation | Recovery does not silently discard accepted work |
| Identity/group setup changes | Provisioning and permission owners | Actual user access after the relevant transfer/setup |
| External integrations run in both environments | Which environment may initiate which operation | No unintended duplicate or conflicting business updates |
| Domain changes | Routing, certificates, redirects, caching and observation | Real customer routes after the authorized switch |
Choose how to handle each condition before the window. A rollback can restore a route while leaving newer content or an external side effect unresolved. Record those consequences and the authority to accept them instead of relying on a generic rollback-available statement.
Make the final decision explicit
The migration lead assembles the scope, mandatory test results, open conditions, final content/code identities, operating cover and recovery evidence. The business owner accepts the customer/editorial result; technical owners accept compatibility, integration and operation. Record launch, limited launch, hold or redesign, including why that decision follows from the evidence.
For a limited launch, name the exact locales, channels, content types and integrations included. Specify how excluded traffic/work is handled and when expansion can be assessed. Keep stabilization observations and support authority in place after the switch.
Retirement follows verified continuity. Identify jobs, accounts, endpoints, retained archives and temporary migration permissions still present in the old environment. Remove or retain them through the approved ownership process, and make the improvement backlog reflect observed post-move outcomes rather than the original assumptions alone.
Retire deliberately and maintain a roadmap
Retire old endpoints, credentials, jobs, redirects and monitoring only after the required continuity period and owner approval. Preserve necessary evidence and record responsibility for retained archives. Confirm connected systems no longer send updates to the retired environment.
Complete W20 with compatibility, rehearsal/reconciliation, cutover, recovery and business/technical decisions. After stabilization, prioritize remaining improvements by observed impact, effort, dependencies and accountable ownership. Revisit the original benefit assumptions with actual results. An illustrative assessment/pilot/rollout sequence can help planning; the organization's rehearsal evidence must determine dates and staffing.
Finish with a recorded decision: launch, limited launch, hold for a named condition or redesign. Include accepted limitations, the person responsible for each open condition and the next review date. That decision closes the release or migration while keeping future improvement under an owned process.
W20 Migration and improvement decision
Use with chapter 20. Retain the rehearsal and reconciliation that justify a date.
Scroll horizontally if needed.
| Record | Entry |
|---|---|
| Reason, alternatives and source/target compatibility inventory | [enter] |
| Representative transfer, code adaptation and identity tests | [enter] |
| References, content changes, URLs, analytics and integration reconciliation | [enter] |
| Freeze/top-up/cutover plan, owners and hold conditions | [enter] |
| Recovery/rollback conditions and handling of newer content | [enter] |
| Launch/limited launch/hold/redesign decision and accepted scope | [enter] |
| Retirement, benefit review and prioritized improvement backlog | [enter] |
