Blog
What to check before migrating an AEM 6.5 project to AEM as a Cloud Service.
In short. Before moving a single page, review five fronts: code compatibility with an immutable repository and current APIs; the size and structure of content and assets; the Dispatcher configuration; integrations and networking; and the cutover plan. Adobe provides tools for most of this assessment, but remediation decisions, and the order in which they happen, still belong to the team.
What changes in AEM as a Cloud Service
The migration is not a version upgrade: the operating model changes. These are the differences with the biggest impact on a project coming from AEM 6.5:
- Adobe applies updates continuously; there are no more upgrade projects, but the code has to tolerate them.
- /apps and /libs are immutable at runtime: whatever used to be changed on the server now has to arrive through code.
- Every deployment goes through Cloud Manager pipelines, with code quality gates that can stop it.
- Run modes are limited to author and publish combined with the dev, stage, and prod environments.
- OSGi configurations are written as JSON (.cfg.json).
- Replication agents are gone; publishing uses Sling Content Distribution.
- Asset processing moves to asset microservices, so customizations of the DAM Update Asset workflow need to be rethought.
- Classic UI is no longer available.
The Adobe tools worth using
Adobe documents the migration journey on Experience League and provides specific tools. They do not replace the team’s judgment, but they give you an objective inventory from day one:
- Best Practices Analyzer: runs on the 6.5 instance and lists patterns that are incompatible with Cloud Service.
- Cloud Acceleration Manager: organizes the findings and supports migration planning.
- Content Transfer Tool: moves repository content and supports later incremental transfers.
- Repository Modernizer: restructures the project’s packages into the layout Cloud Service expects.
- Dispatcher Converter and Index Converter: adapt the Dispatcher configuration and custom Oak indexes.
- AEM Modernization Tools: help move from static to editable templates and from foundation components to Core Components.
What to review in the code
The Best Practices Analyzer report is usually long. To prioritize, these are the questions we ask about a project’s code before estimating:
- Is there code that writes to /apps or /libs at runtime, or configuration that used to be edited by hand on the server?
- Which deprecated or removed APIs does it use, and which third-party dependencies do not build on the Java version Cloud Manager supports?
- Are there scheduled jobs or long-running processes that assume a single instance? In the cloud, instances scale and get replaced.
- What customizations exist on asset workflows, and which of them can be handled with processing profiles?
- Does the project use static templates or foundation components that are worth modernizing now rather than later?
- How much test coverage is there? Without it, every fix is a gamble.
Content and assets
Content is where effort gets underestimated the most. Measure the size of the repository and the asset library up front, purge old versions and audit logs that add nothing, and decide which content will not be migrated at all.
Plan the transfer in at least two stages: an initial load with time to test, and one or more incremental loads close to cutover. Between the last load and launch, agree on a content freeze that is short and known to every author. Users and groups change too: in Cloud Service identity is managed through Adobe IMS, and mapping permissions is a task in its own right.
Dispatcher and CDN
The Dispatcher configuration takes on a new structure: some files are fixed by Adobe and others can be changed by the project, and everything is validated with the SDK tools before deploying. Testing it locally from the start avoids finding out in the pipeline that a cache rule or a filter is invalid.
Cloud Service includes an Adobe-managed CDN. Cache headers that used to be tuned on the web server now have to be designed for that layer, and it is worth reviewing what content needs to be invalidated, and when.
Integrations and networking
If AEM connects to systems that filter by IP address, such as an ERP, an internal API, or a third-party service with an allowlist, you need Cloud Service advanced networking for a dedicated egress IP or a VPN. It involves coordination with other teams, so identify it at the start, not in the week of cutover.
How we sequence the plan
With the assessment in hand, this is the order we follow:
- Inventory: Best Practices Analyzer, content size, and integrations.
- Code remediation and project restructuring.
- A working Cloud Manager pipeline in the development environment.
- First content transfer and functional testing with real authors.
- Performance and Dispatcher testing in stage.
- Incremental transfer, content freeze, and cutover.
Mistakes worth avoiding
The most common stumbles are about planning, not technology: leaving code remediation for the end, estimating content by page count instead of actual repository size, testing Dispatcher for the first time in the pipeline, and not leaving time for authors to validate their content before cutover.
If your AEM project is already hard to maintain on 6.5, the migration is also a chance to fix it. An audit beforehand separates what must be remediated to migrate from what is worth rebuilding.