{"id":596,"date":"2026-04-10T14:50:01","date_gmt":"2026-04-10T14:50:01","guid":{"rendered":"https:\/\/lhotsetechnologies.com\/blog\/?p=596"},"modified":"2026-04-10T14:57:57","modified_gmt":"2026-04-10T14:57:57","slug":"content-migration-with-aem-guides","status":"publish","type":"post","link":"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/","title":{"rendered":"Content Migration with AEM Guides"},"content":{"rendered":"\t\t
\n\t\t\t\t
\n\t\t\t\t\t
\n\t\t\t\t
\n\t\t\t\t\t\t\t\t\t

\ud83d\ude80 Content Migration with AEM Guides<\/h3>

Migrating content between CMS platforms is never just a technical task\u2014it\u2019s a journey filled with unexpected challenges, learning curves, and creative problem-solving.<\/p>

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)<\/strong>.<\/p>

\ud83d\udd27 Prerequisites<\/h4>
  • AEM 6.5.13<\/li>
  • JDK 11<\/li>
  • AEM Groovy Console 15.1.0<\/li>
  • fmdita package 6.5.4.1.159<\/li><\/ul><\/div>

    \ud83c\udfd7\ufe0f Migration Architecture Overview<\/h4>

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

    • Source System:<\/strong> Sitecore (Content APIs)<\/li>
    • Transformation Layer:<\/strong> Custom Java-based processing<\/li>
    • Processing Logic:<\/strong> JSON \u2192 XML transformation aligned with DITA standards<\/li>
    • Target System:<\/strong> AEM Guides (DITA Maps & Concepts)<\/li><\/ul>

      The architecture ensured that content was not only migrated but also normalized to meet
      AEM Guides XML and DTD constraints.<\/p><\/div>

      \ud83d\udcd8 Key Concepts in AEM Guides<\/h4>

      DITA Maps<\/h5>

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

      DITA Concepts<\/h5>

      DITA Concepts are like book chapters where actual content resides.<\/p>

      Both use unique identifiers such as UUID and FMID which play a critical role during migration.<\/p><\/div>

      \u26a0\ufe0f Challenges Faced<\/h4>

      1. DITA Map & Concept Creation APIs<\/h5>

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

      Since these APIs are not public, we included the required JAR manually:<\/p>

      utils-4.0.1.jar<\/code><\/p>

      This required deeper debugging of fmdita code due to lack of documentation.<\/div>

      2. XML Editor Source View Behavior<\/h4>

      The XML editor source view does not show actual content. Instead, it shows GUID references.<\/p>

      Example issue:<\/p>

      • Original reference path is hidden<\/li>
      • GUID is displayed instead<\/li>
      • Required multiple logic updates<\/li><\/ul>

        3. Referencing Between DITA Assets<\/h4>

        AEM Guides uses a unique referencing mechanism:<\/p>

        <Referenced-Asset-fmdita-ID>#<Referenced-Section-ID><\/code><\/p>

        This applies for:<\/p>

        • DITA Map \u2192 DITA Concept<\/li>
        • DITA Concept \u2192 DITA Concept<\/li><\/ul>

          4. Unsupported HTML Tags & Characters<\/h4>

          AEM Guides is XML-based, so many HTML tags are not supported.<\/p>

          Unsupported elements:<\/strong><\/p>

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

            Transformation strategy:<\/strong><\/p>

            • Removed line breaks<\/li>
            • Encoded special characters<\/li>
            • Converted tags:
              • <strong> \u2192 <b><\/li>
              • <img> \u2192 <fig><\/li>
              • <abbr> \u2192 <abbreviated-form><\/li><\/ul><\/li>
              • Removed <br><\/li><\/ul>

                This turned migration into a content transformation process<\/strong>.<\/p>

                5. HTML Nesting Limitations<\/h4>

                Certain valid HTML tags are not allowed within others due to fmdita DTD constraints.<\/p>

                6. Custom Tags Not Allowed<\/h4>

                Client required custom tags like:<\/p>

                • <demoMap><\/li>
                • <demoConcept><\/li>
                • <demoReferences><\/li><\/ul>

                  Solution:<\/p>

                  • Created custom DTD<\/li>
                  • Worked with content expert team<\/li><\/ul><\/div>

                    \ud83d\udca1 Key Takeaways<\/h4>
                    • Migration involves transformation, not just data transfer<\/li>
                    • Understanding XML constraints is critical<\/li>
                    • Internal APIs may be required<\/li>
                    • Team collaboration is essential<\/li><\/ul><\/div>

                      \ud83c\udfaf Final Thoughts<\/h4>

                      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.<\/p>

                      \u00a0<\/p><\/div>

                      Happy Learning!
                      Ankur Chauhan<\/strong><\/div>\t\t\t\t\t\t\t\t<\/div>\n\t\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t","protected":false},"excerpt":{"rendered":"

                      \ud83d\ude80 Content Migration with AEM Guides Migrating content between CMS platforms is never just a technical task\u2014it\u2019s a journey filled […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-596","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"yoast_head":"\nContent Migration with AEM Guides - AEM Blog | Lhotse Technologies<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Content Migration with AEM Guides - AEM Blog | Lhotse Technologies\" \/>\n<meta property=\"og:description\" content=\"\ud83d\ude80 Content Migration with AEM Guides Migrating content between CMS platforms is never just a technical task\u2014it\u2019s a journey filled […]\" \/>\n<meta property=\"og:url\" content=\"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/\" \/>\n<meta property=\"og:site_name\" content=\"AEM Blog | Lhotse Technologies\" \/>\n<meta property=\"article:published_time\" content=\"2026-04-10T14:50:01+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2026-04-10T14:57:57+00:00\" \/>\n<meta name=\"author\" content=\"admin\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"admin\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"3 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"Article\",\"@id\":\"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/#article\",\"isPartOf\":{\"@id\":\"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/\"},\"author\":{\"name\":\"admin\",\"@id\":\"https:\/\/lhotsetechnologies.com\/blog\/#\/schema\/person\/d1daa7081420d3cf2a02c309ee3f5800\"},\"headline\":\"Content Migration with AEM Guides\",\"datePublished\":\"2026-04-10T14:50:01+00:00\",\"dateModified\":\"2026-04-10T14:57:57+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/\"},\"wordCount\":492,\"commentCount\":0,\"publisher\":{\"@id\":\"https:\/\/lhotsetechnologies.com\/blog\/#organization\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"CommentAction\",\"name\":\"Comment\",\"target\":[\"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/#respond\"]}]},{\"@type\":\"WebPage\",\"@id\":\"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/\",\"url\":\"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/\",\"name\":\"Content Migration with AEM Guides - AEM Blog | Lhotse Technologies\",\"isPartOf\":{\"@id\":\"https:\/\/lhotsetechnologies.com\/blog\/#website\"},\"datePublished\":\"2026-04-10T14:50:01+00:00\",\"dateModified\":\"2026-04-10T14:57:57+00:00\",\"breadcrumb\":{\"@id\":\"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/lhotsetechnologies.com\/blog\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Content Migration with AEM Guides\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/lhotsetechnologies.com\/blog\/#website\",\"url\":\"https:\/\/lhotsetechnologies.com\/blog\/\",\"name\":\"AEM Blog | Lhotse Technologies\",\"description\":\"\",\"publisher\":{\"@id\":\"https:\/\/lhotsetechnologies.com\/blog\/#organization\"},\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/lhotsetechnologies.com\/blog\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-US\"},{\"@type\":\"Organization\",\"@id\":\"https:\/\/lhotsetechnologies.com\/blog\/#organization\",\"name\":\"AEM Blog | Lhotse Technologies\",\"url\":\"https:\/\/lhotsetechnologies.com\/blog\/\",\"logo\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/lhotsetechnologies.com\/blog\/#\/schema\/logo\/image\/\",\"url\":\"https:\/\/lhotsetechnologies.com\/blog\/wp-content\/uploads\/2019\/07\/lhotse-logo.png\",\"contentUrl\":\"https:\/\/lhotsetechnologies.com\/blog\/wp-content\/uploads\/2019\/07\/lhotse-logo.png\",\"width\":539,\"height\":172,\"caption\":\"AEM Blog | Lhotse Technologies\"},\"image\":{\"@id\":\"https:\/\/lhotsetechnologies.com\/blog\/#\/schema\/logo\/image\/\"}},{\"@type\":\"Person\",\"@id\":\"https:\/\/lhotsetechnologies.com\/blog\/#\/schema\/person\/d1daa7081420d3cf2a02c309ee3f5800\",\"name\":\"admin\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/lhotsetechnologies.com\/blog\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/secure.gravatar.com\/avatar\/829547de0cecf5477afeaf7ff2a49fc87a026be43cb5403fa54d0fd419192479?s=96&d=mm&r=g\",\"contentUrl\":\"https:\/\/secure.gravatar.com\/avatar\/829547de0cecf5477afeaf7ff2a49fc87a026be43cb5403fa54d0fd419192479?s=96&d=mm&r=g\",\"caption\":\"admin\"},\"url\":\"https:\/\/lhotsetechnologies.com\/blog\/author\/admin\/\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Content Migration with AEM Guides - AEM Blog | Lhotse Technologies","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/","og_locale":"en_US","og_type":"article","og_title":"Content Migration with AEM Guides - AEM Blog | Lhotse Technologies","og_description":"\ud83d\ude80 Content Migration with AEM Guides Migrating content between CMS platforms is never just a technical task\u2014it\u2019s a journey filled […]","og_url":"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/","og_site_name":"AEM Blog | Lhotse Technologies","article_published_time":"2026-04-10T14:50:01+00:00","article_modified_time":"2026-04-10T14:57:57+00:00","author":"admin","twitter_card":"summary_large_image","twitter_misc":{"Written by":"admin","Est. reading time":"3 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/#article","isPartOf":{"@id":"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/"},"author":{"name":"admin","@id":"https:\/\/lhotsetechnologies.com\/blog\/#\/schema\/person\/d1daa7081420d3cf2a02c309ee3f5800"},"headline":"Content Migration with AEM Guides","datePublished":"2026-04-10T14:50:01+00:00","dateModified":"2026-04-10T14:57:57+00:00","mainEntityOfPage":{"@id":"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/"},"wordCount":492,"commentCount":0,"publisher":{"@id":"https:\/\/lhotsetechnologies.com\/blog\/#organization"},"inLanguage":"en-US","potentialAction":[{"@type":"CommentAction","name":"Comment","target":["https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/#respond"]}]},{"@type":"WebPage","@id":"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/","url":"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/","name":"Content Migration with AEM Guides - AEM Blog | Lhotse Technologies","isPartOf":{"@id":"https:\/\/lhotsetechnologies.com\/blog\/#website"},"datePublished":"2026-04-10T14:50:01+00:00","dateModified":"2026-04-10T14:57:57+00:00","breadcrumb":{"@id":"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/lhotsetechnologies.com\/blog\/content-migration-with-aem-guides\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/lhotsetechnologies.com\/blog\/"},{"@type":"ListItem","position":2,"name":"Content Migration with AEM Guides"}]},{"@type":"WebSite","@id":"https:\/\/lhotsetechnologies.com\/blog\/#website","url":"https:\/\/lhotsetechnologies.com\/blog\/","name":"AEM Blog | Lhotse Technologies","description":"","publisher":{"@id":"https:\/\/lhotsetechnologies.com\/blog\/#organization"},"potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/lhotsetechnologies.com\/blog\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"},{"@type":"Organization","@id":"https:\/\/lhotsetechnologies.com\/blog\/#organization","name":"AEM Blog | Lhotse Technologies","url":"https:\/\/lhotsetechnologies.com\/blog\/","logo":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/lhotsetechnologies.com\/blog\/#\/schema\/logo\/image\/","url":"https:\/\/lhotsetechnologies.com\/blog\/wp-content\/uploads\/2019\/07\/lhotse-logo.png","contentUrl":"https:\/\/lhotsetechnologies.com\/blog\/wp-content\/uploads\/2019\/07\/lhotse-logo.png","width":539,"height":172,"caption":"AEM Blog | Lhotse Technologies"},"image":{"@id":"https:\/\/lhotsetechnologies.com\/blog\/#\/schema\/logo\/image\/"}},{"@type":"Person","@id":"https:\/\/lhotsetechnologies.com\/blog\/#\/schema\/person\/d1daa7081420d3cf2a02c309ee3f5800","name":"admin","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/lhotsetechnologies.com\/blog\/#\/schema\/person\/image\/","url":"https:\/\/secure.gravatar.com\/avatar\/829547de0cecf5477afeaf7ff2a49fc87a026be43cb5403fa54d0fd419192479?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/829547de0cecf5477afeaf7ff2a49fc87a026be43cb5403fa54d0fd419192479?s=96&d=mm&r=g","caption":"admin"},"url":"https:\/\/lhotsetechnologies.com\/blog\/author\/admin\/"}]}},"_links":{"self":[{"href":"https:\/\/lhotsetechnologies.com\/blog\/wp-json\/wp\/v2\/posts\/596","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/lhotsetechnologies.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/lhotsetechnologies.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/lhotsetechnologies.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/lhotsetechnologies.com\/blog\/wp-json\/wp\/v2\/comments?post=596"}],"version-history":[{"count":5,"href":"https:\/\/lhotsetechnologies.com\/blog\/wp-json\/wp\/v2\/posts\/596\/revisions"}],"predecessor-version":[{"id":601,"href":"https:\/\/lhotsetechnologies.com\/blog\/wp-json\/wp\/v2\/posts\/596\/revisions\/601"}],"wp:attachment":[{"href":"https:\/\/lhotsetechnologies.com\/blog\/wp-json\/wp\/v2\/media?parent=596"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/lhotsetechnologies.com\/blog\/wp-json\/wp\/v2\/categories?post=596"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/lhotsetechnologies.com\/blog\/wp-json\/wp\/v2\/tags?post=596"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}