Adovo

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

Assess

Inventory what must survive

Check content, extensions, identities and operating assumptions.

Rehearse

Transfer a representative slice

Reconcile references and prove ordinary-role tasks.

Decide

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.

Choose the migration boundary from the requirement: table 9
Proposed pathPrimary assessmentEvidence before authorizing cutover
Repair or service-pack/dependency changeCompatibility and the failing task on a supported configurationReproduction, regression and recovery
Move to 6.5 LTSApplicable source/target path, runtime and removed/changed dependenciesSupported release assessment, authoring and integration tests
Move on-premises/AMS content and code to Cloud ServiceCloud-compatible code, content/identity transfer and delivery operationRehearsed transfer, reconciliation, roles, APIs and cluster/retry behavior
Change authoring/delivery modelComposition, reuse, preview, frontend and content-consumer responsibilitiesRepresentative editorial and customer journeys on the new model
Retire a system or channelRemaining data, consumers, URLs, credentials and retention dutiesOwned 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.

Worked scenario of an AMS to Cloud Service move: table 12
WorkstreamRehearsal evidenceAcceptance owner
Content and assetsRequired objects, references, locale relationships and outputsContent/media owners
Authoring and workflowCreate / edit / compare / approve / withdraw with normal rolesEditorial owner
Identities and authorityActual users can perform intended actions and fail denied onesIdentity/platform owners
Code and integrationsCompatible deployment, interruption/replay and external outcomesEngineering/integration owners
Public continuityDomains, routes, redirects, metadata, search and measurementChannel/delivery owners
Operation and recoveryAlerts, support cover, recovery procedure and authorityService 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.

Control changes during the transition: table 15
ConditionAgreement neededVerification
Source content continues changingAuthoritative source, freeze/top-up plan and ownerFinal delta is reconciled against the intended target
Code changes during migrationCompatible source/target revisions and release sequencingSame acceptance fixtures on the intended combination
Target accepts new contentOwnership of new writes and possible reverse reconciliationRecovery does not silently discard accepted work
Identity/group setup changesProvisioning and permission ownersActual user access after the relevant transfer/setup
External integrations run in both environmentsWhich environment may initiate which operationNo unintended duplicate or conflicting business updates
Domain changesRouting, certificates, redirects, caching and observationReal 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.

W20 Migration and improvement decision: table 20
RecordEntry
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]

Continue exploring

Adobe Experience ManagerAEM Sites

AEM Sites Playbook, Chapter 1: Strategy, value, ownership and adoption

What outcome justifies the work, and who will operate it?

Read more
Adobe Experience ManagerAEM Sites

AEM Sites Playbook, Chapter 10: Preview, publication, scheduling and withdrawal

How do we release and remove the complete approved experience?

Read more
Adobe Experience ManagerAEM Sites

AEM Sites Playbook, Chapter 11: Delivery, Dispatcher, CDN, domains and caching

Which layer controls the request, redirect or stale response?

Read more
Explore data and analytics services →