Migration, Modernization and Review

Why migration is a topic for you

Even on a greenfield project you will meet this material. Legacy patterns are everywhere in older documentation, Stack Overflow answers and any codebase more than a few years old. Knowing what changed and why is how you tell current advice from advice that will fail a pipeline.

The phases

1. Readiness — run the Best Practice Analyzer (BPA) against the existing instance. It reports incompatibilities and effort.
2. Planning — Cloud Acceleration Manager (CAM) turns BPA findings into a tracked plan across the project.
3. Implementation — refactor code and configuration with the modernisation tools.
4. Content transfer — move the content with the Content Transfer Tool (CTT).
5. Go-live — cut over, with a final content top-up.

The tools

• BPA — analyses a source instance and reports what will not work on Cloud Service.
• CAM — the planning and tracking hub, consuming BPA reports.
• CTT — extracts content into a migration set and ingests it into a Cloud Service environment. Supports top-up runs, so you can move the bulk early and sync the delta at cutover.
• Bulk Import — imports assets in volume from cloud storage, more efficient than CTT for large DAMs.
• Code Repository Modernizer — restructures a legacy project into the mutable/immutable package layout Cloud Service requires.
• Dispatcher Converter — transforms a legacy Dispatcher configuration into the Cloud Service structure (day 37).
• Index Converter — converts custom Oak index definitions to the Cloud Service naming and format (day 33).
• AEM Modernization Tools — convert static templates to editable ones, foundation components to Core Components, design configurations to policies, and classic UI dialogs to Touch UI.

Repository modernisation

Classic AEM scattered things across /etc: clientlibs, designs, templates, cloud service configuration, tags. Cloud Service's mutable/immutable split made that untenable — /etc mixed both kinds of content in one tree.

The moves you should recognise:

• /etc/designs → /apps clientlibs, with design configuration becoming policies in /conf.
• /etc/clientlibs → /apps, served via /etc.clientlibs (day 19).
• /etc/cloudservices → /conf as context-aware configuration.
• Static templates in /apps → editable templates in /conf.

This is also why so much older documentation looks wrong: it predates the split. When a page tells you to put something in /etc, check its "Applies to" banner.

Pulling the course together

Forty days in one paragraph, which is worth being able to say out loud:

AEM stores everything — content, code and configuration — as nodes in a JCR repository. Sling maps a URL to a node and uses that node's sling:resourceType to find the code that renders it. That code is HTL for markup and Sling Models for logic, packaged as OSGi bundles and content packages built by Maven from a project the archetype generated. Authors work on the author tier, composing pages from components that editable templates and their policies permit; publishing replicates content to publish, which sits behind the Dispatcher and a CDN. Everything reaches an environment through a Cloud Manager pipeline that enforces quality gates, and the boundary between immutable /apps and mutable /content and /conf is what makes that pipeline model possible.

If you can explain that, and you know where to look when a piece of it misbehaves, you have what the forty days were for. The final exam checks it.