Introduction
Migrating to Adobe Experience Manager (AEM) — whether from a legacy CMS, a homegrown platform,
or an older AEM version — is rarely just a technical lift-and-shift. It’s an organizational project disguised
as a software project. Teams that treat it purely as “move the content, swap the templates” tend to
discover the hard way that AEM has strong opinions about content structure, authoring workflows, and
delivery architecture. Below are the lessons that come up again and again, organized by the phase where
they tend to bite.
1. Discovery and Planning
Pitfall: Underestimating content complexity
Teams often scope migrations based on page counts, not content complexity. A site with 2,000 pages
built on simple templates is a very different project from one with 500 pages full of embedded
components, custom widgets, and inconsistent authoring patterns.
Lesson: Run a proper content audit before estimating anything. Catalog content types, component usage
patterns, metadata schemas, and — critically — content that’s actually still used. Migrating dead or
duplicate content just moves the mess to a new platform.
Pitfall: Skipping information architecture rework
It’s tempting to preserve the existing URL structure and page hierarchy “to keep things simple.” But
AEM’s page tree, template model, and component structure work best when content is organized to
match how AEM thinks about pages — not how the old CMS happened to organize things.
Lesson: Treat migration as an opportunity to fix IA debt, not just a chance to avoid it. This is also the
moment to define your SEO redirect strategy, since URL structures will likely shift.
Pitfall: Not defining the target architecture early
“We’re migrating to AEM” isn’t specific enough. AEM as a Cloud Service (AEMaaS), AEM 6.5 on-
prem/managed, headless via GraphQL, hybrid (headless + traditional) — these are meaningfully different
architectures with different constraints on custom code, dispatcher config, and deployment pipelines.
Lesson: Lock down the target deployment model and delivery pattern (traditional, headless, or hybrid)
before component design begins. Retrofitting a traditional-authoring site into headless delivery later is
expensive.
Related resource: For a deeper look at the transition from AEM On-Premises to AEM as a Cloud Service, see this AEM On-Premises to Cloud migration guide.
2. Component and Template Design
Pitfall: Over-engineering components too early
Some teams try to build a fully generic, infinitely reusable component library before they understand
real content patterns, resulting in components so abstract that authors can’t use them without a
developer’s help.
Lesson: Build components from real content patterns found in the audit, not hypothetical future needs.
Start with a solid core set (text, image, teaser, carousel, CTA) and expand deliberately. AEM’s Core
Components are a strong starting point — extend them rather than reinventing them.
Pitfall: Ignoring authoring experience
Developers often optimize for clean code and flexible APIs, while authors end up with dialogs that are
confusing, inconsistent, or missing validation. This leads to inconsistent content and a flood of support
tickets post-launch.
Lesson: Involve actual content authors in dialog and template design reviews before build-out, not just
at UAT. Authoring experience is a first-class requirement, not an afterthought.
Pitfall: Rigid templates that fight the editorial team
Locking templates down too tightly (to enforce brand consistency) often backfires when marketing needs
a one-off layout and has to file a dev ticket for every campaign page.
Lesson: Use AEM’s Editable Templates and template policies to strike a balance — enforce brand and
structural guardrails, but give authors flexibility within them via allowed components and layout
containers.
3. Content Migration Execution
Pitfall: Manual migration at scale
Copy-pasting or manually re-authoring hundreds of pages is slow, error-prone, and doesn’t scale — but
many teams default to it because “the content is too messy to automate.”
Lesson: Invest in migration tooling early — custom scripts using AEM’s APIs (JCR, Sling, Content Transfer
Tool), or third-party migration accelerators. Even messy content usually has enough structure (a CSV
export, an API, a database) to drive semi-automated transformation, with manual QA for edge cases
rather than manual authoring of everything.
Pitfall: No dry runs
Running the “real” migration for the first time in a pre-launch crunch means any transformation bugs get
discovered under maximum time pressure.
Lesson: Do multiple migration dry runs against a staging environment, well before launch. Each dry run
should get progressively closer to production data and surface issues (broken links, encoding problems,
missing assets, metadata mismatches) while there’s still time to fix the pipeline, not just the symptoms.
Pitfall: Treating DAM migration as an afterthought
Assets (images, PDFs, videos) often get migrated as a bulk file dump without proper metadata, tagging,
or renditions — leaving the DAM effectively unusable for search, reuse, or automated processing.
Lesson: Plan the DAM migration with the same rigor as page content: tagging taxonomy, metadata
schema, renditions, and folder structure should be defined before assets are bulk-uploaded, not cleaned
up after.
4. Technical and Infrastructure
Pitfall: Dispatcher misconfiguration
The dispatcher (or CDN config in AEMaaS) is often treated as a deployment detail handled late in the
project, when in fact caching rules, cache invalidation, and security filters materially affect performance
and security posture.
Lesson: Design dispatcher/CDN caching rules alongside the component architecture, not after. Load test
with realistic cache-miss scenarios, not just cache-hit happy paths.
Pitfall: Underestimating custom code debt from the old system
Legacy platforms often have years of accumulated custom logic — business rules, integrations,
personalization hacks — that isn’t documented anywhere except in code.
Lesson: Audit and explicitly decide the fate of every piece of custom logic: rebuild natively in AEM,
replace with an out-of-the-box capability, or deliberately deprecate it. “Just port it over” without this
decision leads to fragile code nobody understands in the new system either.
Pitfall: Weak or absent CI/CD and environment strategy
Especially with AEMaaS, teams migrating from on-prem workflows sometimes try to keep old
deployment habits (manual package installs, shared dev environments) that don’t fit the cloud-native
pipeline model.
Lesson: Adopt AEM’s Cloud Manager pipelines (or equivalent CI/CD discipline for on-prem) from day one
of development, not as a pre-launch scramble. This also surfaces code-quality and performance issues
(via built-in code quality gates) early rather than at the worst possible time.
5. People and Process
Pitfall: Training happens too late
Author training often gets scheduled right before launch, leaving no time for hands-on practice or
workflow adjustment, and no time to feed usability feedback back into dialog/template design.
Lesson: Start author training during UAT, using real (or realistic) content, so feedback can still influence
component and workflow design. Treat training as iterative, not a single event.
Pitfall: No content governance model post-launch
Migrations solve a moment-in-time content problem but don’t prevent the same mess from re-
accumulating if there’s no ongoing governance — naming conventions, tagging discipline, component
usage guidelines.
Lesson: Define content governance (ownership, review cadence, component usage guidelines, tagging
standards) as a deliverable of the migration project, not a “someday” task for after launch.
Pitfall: Underestimating stakeholder alignment work
Marketing, IT, and development teams often have different — sometimes conflicting — expectations of
what “migrated to AEM” means: pixel-perfect parity vs. modernized experience vs. minimum viable
launch.
Lesson: Get explicit, written alignment on migration goals and scope (parity vs. redesign, phased vs. big-
bang launch) before build begins. Revisit this alignment at each major milestone, since scope tends to
drift as stakeholders see the new platform’s capabilities.
Quick Reference: Pre-Migration Checklist
- Content audit completed, with dead/duplicate content flagged for exclusion
- Target architecture (AEMaaS / on-prem / headless / hybrid) confirmed
- IA and URL/redirect strategy finalized
- Core component library scoped from real content patterns
- Authors involved in dialog/template review
- Migration tooling built and dry-run tested against staging
- DAM taxonomy and metadata schema defined
- Dispatcher/CDN caching strategy designed alongside components
- Legacy custom code audited and triaged (rebuild/replace/deprecate)
- CI/CD pipeline established from the start of development
- Author training scheduled to start during UAT, not after
- Post-launch content governance model documented
- Stakeholder alignment on scope and goals documented in writing
Closing Thought
Most AEM migration pain doesn’t come from the platform itself — it comes from unresolved decisions
being deferred until they become emergencies: IA decisions deferred to “we’ll figure it out during build,”
authoring UX deferred to “developers know best,” governance deferred to “we’ll sort it out after
launch.” The teams that go smoothly are the ones that force these decisions early, even when the
answers are uncomfortable or require more upfront planning than the timeline seems to allow.
