Content Migration with AEM Guides

🚀 Content Migration with AEM Guides

Migrating content between CMS platforms is never just a technical task—it’s a journey filled with unexpected challenges, learning curves, and creative problem-solving.

In one of my recent projects, I worked on migrating web content from Sitecore to AEM.
While many teams have done similar migrations, this implementation was different because
the content was migrated in the form of AEM Guides (DITA Maps and DITA Concepts).

🔧 Prerequisites

  • AEM 6.5.13
  • JDK 11
  • AEM Groovy Console 15.1.0
  • fmdita package 6.5.4.1.159

🏗️ Migration Architecture Overview

The migration was not a simple content transfer. It followed a structured pipeline approach
to ensure scalability, transformation, and consistency of content across systems.

  • Source System: Sitecore (Content APIs)
  • Transformation Layer: Custom Java-based processing
  • Processing Logic: JSON → XML transformation aligned with DITA standards
  • Target System: AEM Guides (DITA Maps & Concepts)

The architecture ensured that content was not only migrated but also normalized to meet
AEM Guides XML and DTD constraints.

📘 Key Concepts in AEM Guides

DITA Maps

DITA Maps can be considered as indexes of a book, where all chapters and page numbers are defined.

DITA Concepts

DITA Concepts are like book chapters where actual content resides.

Both use unique identifiers such as UUID and FMID which play a critical role during migration.

⚠️ Challenges Faced

1. DITA Map & Concept Creation APIs

There are no publicly available APIs for CRUD operations on DITA Maps and Concepts.
We explored fmdita bundles and used internal com.adobe.fmdita.* APIs.

Since these APIs are not public, we included the required JAR manually:

utils-4.0.1.jar

This required deeper debugging of fmdita code due to lack of documentation.

2. XML Editor Source View Behavior

The XML editor source view does not show actual content. Instead, it shows GUID references.

Example issue:

  • Original reference path is hidden
  • GUID is displayed instead
  • Required multiple logic updates

3. Referencing Between DITA Assets

AEM Guides uses a unique referencing mechanism:

<Referenced-Asset-fmdita-ID>#<Referenced-Section-ID>

This applies for:

  • DITA Map → DITA Concept
  • DITA Concept → DITA Concept

4. Unsupported HTML Tags & Characters

AEM Guides is XML-based, so many HTML tags are not supported.

Unsupported elements:

  • \n, \r, \t
  • & and special characters
  • <br>
  • <strong>
  • <img>
  • <abbr>

Transformation strategy:

  • Removed line breaks
  • Encoded special characters
  • Converted tags:
    • <strong> → <b>
    • <img> → <fig>
    • <abbr> → <abbreviated-form>
  • Removed <br>

This turned migration into a content transformation process.

5. HTML Nesting Limitations

Certain valid HTML tags are not allowed within others due to fmdita DTD constraints.

6. Custom Tags Not Allowed

Client required custom tags like:

  • <demoMap>
  • <demoConcept>
  • <demoReferences>

Solution:

  • Created custom DTD
  • Worked with content expert team

💡 Key Takeaways

  • Migration involves transformation, not just data transfer
  • Understanding XML constraints is critical
  • Internal APIs may be required
  • Team collaboration is essential

🎯 Final Thoughts

This project highlighted real-world challenges where documentation is limited and solutions
require deep exploration. AEM Guides implementations demand both technical and content-level understanding.

 

Happy Learning!
Ankur Chauhan