Update AEM Archetype using Repository Modernizer

Published
AEM Project Archetype is a Maven template creates a minimal, best-practices-based AEM project. Over the years, AEM Project Archetype has been revolutionized with significant advancements, introducing many new features and possibilities into AEM projects. The latest Archetype emphasizing the separation of content and code into discrete subpackages to maintain the distinction between mutable and immutable content. To align existing projects with AEM’s Cloud Service structure, the Repository Modernizer tool can be used to refactor and reorganize project packages, separating content and code into the appropriate packages.
AEM Cloud Compatible ArcheType
To use the Repository Modernizer, ensure that Node.js and Python are available on your computer. Follow these steps to set up:
  • Install Adobe I/O CLI: npm install -g @adobe/aio-cli
  • Install AEM Cloud Service Migration Plugin: aio plugins:install @adobe/aio-cli-plugin-aem-cloud-service-migration
In order to restructure an existing project's packages for compatibility with AEM as a Cloud Service, execute the aio aem-migration:repository-modernizer command. You'll need to create an aem-migration-config.yaml file, which can be stored either in your local file system or within the CLI configuration directory.
  • Local Project Location: ./.aio-cli
  • CLI Config Directory: ~/.config/@adobe/aio-cli
aem-migration-config.yaml
repositoryModernizer: # groupId to be used for newly created packages groupId: com.aem.demo # information about parent pom parentPom: # absolute path to the parent pom file path: /Users/XXXX/github/aem-demo/pom.xml # the artifactId to be set for the parent pom artifactId: aem-demo # the application title to be set for the parent pom appTitle: AEM Demo # version to be to be set for the parent pom version: 4.7.9-SNAPSHOT # information required for all and analyse packages all: # prefix that is to be used to set the artifactId for all and analyse packages artifactId: aem-demo # application title appTitle: AEM Demo # version to be set for all pom version: 4.7.9-SNAPSHOT # information about projects (expects an array of project information) # NOTE : For multiple projects create separate copies of the info section for each project projects: - # absolute path to the XYZ project folder projectPath: /Users/XXXX/github/aem-demo # Array of relative path(s) (w.r.t. the project folder) to the existing content package(s) that needs to be restructured. # NOTE : only content packages are expected here, NOT bundle/jar artifacts existingContentPackageFolder: - /ui.apps # relative path (w.r.t. the existing content package folder) to the filter.xml file # (If not specified, default path `/src/main/content/META-INF/vault/filter.xml` will be used.) relativePathToExistingFilterXml: # relative path (w.r.t. the existing content package folder) to the jcr_root directory # (If not specified, default path `/src/main/content/jcr_root` will be used) relativePathToExistingJcrRoot: # prefix that is to be used to set the artifactId for newly created ui.apps and ui.content packages artifactId: aem-demo # application title appTitle: AEM Demo # application ID (will be used for config and package folder names) appId: aem-demo # project specific version to be used for content packages version: 4.7.9-SNAPSHOT # Array of relative path(s) (w.r.t. the project folder) to the existing code bundles (will be embedded in the all package). coreBundles: - /core - /common.core # OSGi config folders that need to be renamed. # The existing/source OSGi config folder PATH (JCR path starting from '/apps') is expected as key # and the replacement OSGi folder NAME is expected as value. See examples below : # /apps/xyz/config.prod : config.publish.prod # /apps/system/config.author.dev1 : config.author.dev # /apps/system/config.author.dev2 : config.author.dev # NOTE : # 1. All OSGi config folders under the same path and with same replacement name will be MERGED # (as configured in above example). # 2. If there exists OSGi config files with the same pid/filename in more than one config folders # which are to be merged, they will not be overwritten. A warning regrading the same will be # generated in the summary report and result log file. User would need to manually evaluate # which config to persist osgiFoldersToRename: /apps/aem-demo/configs/config.publish: config.publish.prod
After running the repository-modernizer command, review the target folder for refactored code, updated configurations, a summary report, and the tool's execution logs.
The tool has some known limitations and certain tasks that will need to be handled manually.
  • Missing version info in core bundles will be reported; the version will also need to be added in the dependency section in the all/pom.xml.
  • Ensure that you add the Gson dependency before the AEM SDK API; otherwise, you might encounter java.lang.NoSuchMethodError during the testing phase.
  • The Core dependency is missing in the ui.apps/pom.xml; it needs to be added to the dependencies section.

Frequently Asked Questions (FAQ)

data-sly-test: avoid redundant constant value comparisons

Use data-sly-set when it's only needed to define a variable for later use.

Failed to execute goal com.adobe.aem:aemanalyser-maven-plugin0.0.12:analyse (default-analyse) on project: Unable to build resource for null: Importing java.* packages not allowed: java.io

Update aemanalyser.version to the latest version, e.g., v1.6.4

Bundle aem-demo.core:4.7.9-SNAPSHOT is importing package(s) in start level 20 but no bundle is exporting these for that start level

Ensure that these bundles are embedded in the container (all) project. If they aren't, the Cloud instance won't have access to them during runtime, leading to the errors you're encountering.

The POM for com.aem.demo:aem-demo.ui.apps.structure:zip:4.7.9-SNAPSHOT is missing, no dependency information available

Add <module>ui.apps.structure</module> to the pom.xml