Recently, I worked on accessing the AEM 6.2 to 6.3 upgrade along with my colleagues for our client, and I want to share some additional thoughts you may find useful when upgrading to 6.3. Although this blog is for 6.3, the pointers and idea should really be applicable for an AEM upgrade in general.
Plan for The Release
Thorough planning and assessment are critical when upgrading the AEM platform for a large enterprise with a multi-tenant project, like my client. It should involve architects, project managers, dev managers, infrastructure, deployment teams, and Adobe professionals to understand the scope, the impact, the approaches, the things that may break after the upgrade and the codes that need to be updated for each tenant, etc.
Thorough planning and assessment are critical when upgrading the AEM platform for a large enterprise with a multi-tenant project, like my client. It should involve architects, project managers, dev managers, infrastructure, deployment teams, and Adobe professionals to understand the scope, the impact, the approaches, the things that may break after the upgrade and the codes that need to be updated for each tenant, etc.
A dedicated dev environment is recommended to set up for the upgrade in order to access and test the environment and codes. Upgrade learning and findings should be well documented and shared with all parties. After planning and assessment, your dev manager should decide if a dedicated technical release is required for the upgrade, assuming tenant teams are continuing new feature development for their products.
POM File Updates
No matter how you created your project structure at first, probably from Adobe’s AEM maven archetype or ACS common’s lazybones AEM multi module project, you should update your POM files to use the latest and newest files, and to get deployed properly in AEM 6.3. Below is a list of dependencies and plugins that I found during my assessment that can be updated:
After the update, run the maven build and make sure the build is successful and bundles are active state. Fix any issues.
Also, a side note: WCM IO has an AEM dependencies tooling that will provide you all maven dependencies (including those that are not defined by Uber Jar) for a specific AEM version. This can provide a safety net for your project in case you miss any dependencies in your POM, but it will not overwrite the ones that you explicitly declare in your POM. Maybe it’s a good idea for Adobe/developer to write an automatic tool for POM updates?
No matter how you created your project structure at first, probably from Adobe’s AEM maven archetype or ACS common’s lazybones AEM multi module project, you should update your POM files to use the latest and newest files, and to get deployed properly in AEM 6.3. Below is a list of dependencies and plugins that I found during my assessment that can be updated:
- uber-jar (It’s recommended to place Uber jar at the bottom of the dependency list so that Maven will honor any newer versions of dependencies that is explicitly declared inside the project POM.)
- maven-enforcer-plugin to use Java 1.8 (Although Java 1.7 still works in AEM 6.3, it is not supported by Adobe.)
- maven-compiler-plugin to use Java 1.8
- maven-surefire-plugin
- maven-failsafe-plugin
- maven-sling-plugin
- content-package-maven-plugin
- maven-bundle-plugin
- maven-dependency-plugin
- build-helper-maven-plugin
- OSGI dependencies (osgi.core, osgi.cmpn, osgi.annotation) version
- slf4j-simple and slf4j-api
- junit
- servlet-api
- apache.sling.models.api (select the version you need since some are introduced in a later version)
- commons-lang
After the update, run the maven build and make sure the build is successful and bundles are active state. Fix any issues.
Also, a side note: WCM IO has an AEM dependencies tooling that will provide you all maven dependencies (including those that are not defined by Uber Jar) for a specific AEM version. This can provide a safety net for your project in case you miss any dependencies in your POM, but it will not overwrite the ones that you explicitly declare in your POM. Maybe it’s a good idea for Adobe/developer to write an automatic tool for POM updates?
Bundle Status
Even though your build might be successful, sometimes you can still find your application bundles in “resolved” status, most likely due to some of your bundles’ imported packages are outside of the supported range by OOTB AEM. While you are scratching your head to figure out why your application is not working, it’s always a good practice to validate that your bundle status is at an “active” state.
These Things May Break After the Upgrade
Below is a list of common components/features that break after we deploy our code to AEM 6.3:
RTE and RTE plugins: plugins in the dialog are covering up the text editing area, the RTE box shrinks, inline editing is messed up. (please refer to this link for the fix)
Multifield: can’t load content, add field button doesn’t work. (please refer to this link for the fix)
Classic UI page properties: can’t open (deprecated in April 2018, removed in April 2019)
Page comparison feature in AEM may not work properly with your custom component/CSS/JS
Even though your build might be successful, sometimes you can still find your application bundles in “resolved” status, most likely due to some of your bundles’ imported packages are outside of the supported range by OOTB AEM. While you are scratching your head to figure out why your application is not working, it’s always a good practice to validate that your bundle status is at an “active” state.
These Things May Break After the Upgrade
Below is a list of common components/features that break after we deploy our code to AEM 6.3:
RTE and RTE plugins: plugins in the dialog are covering up the text editing area, the RTE box shrinks, inline editing is messed up. (please refer to this link for the fix)
Multifield: can’t load content, add field button doesn’t work. (please refer to this link for the fix)
Classic UI page properties: can’t open (deprecated in April 2018, removed in April 2019)
Page comparison feature in AEM may not work properly with your custom component/CSS/JS
Deprecated APIs
As part of your technical upgrade assessment, you should look into your project codes and see if you are using any deprecated APIs in AEM 6.3.
Full deprecated API list can be referenced here: https://docs.adobe.com/docs/en/aem/6-3/develop/ref/javadoc/deprecated-list.html
API changes between AEM 6.2 and 6.3 can be referenced here: https://docs.adobe.com/docs/en/aem/6-3/develop/ref/diff-previous/changes.html
Deprecated and removed features list can be referenced here: https://docs.adobe.com/docs/en/aem/6-3/release-notes/deprecated-removed-features.html
Be aware that WCMUse has been deprecated since AEM6.1, so for component classes that need updating, it’s recommended to implement Sling Models instead of WCMUsePojo. How? You should refer to my How To Switch From WCMUsePojo To Sling Models blog series.
As part of your technical upgrade assessment, you should look into your project codes and see if you are using any deprecated APIs in AEM 6.3.
Full deprecated API list can be referenced here: https://docs.adobe.com/docs/en/aem/6-3/develop/ref/javadoc/deprecated-list.html
API changes between AEM 6.2 and 6.3 can be referenced here: https://docs.adobe.com/docs/en/aem/6-3/develop/ref/diff-previous/changes.html
Deprecated and removed features list can be referenced here: https://docs.adobe.com/docs/en/aem/6-3/release-notes/deprecated-removed-features.html
Be aware that WCMUse has been deprecated since AEM6.1, so for component classes that need updating, it’s recommended to implement Sling Models instead of WCMUsePojo. How? You should refer to my How To Switch From WCMUsePojo To Sling Models blog series.
Upgrade Tasks
To make your AEM upgrade a more seamless project, Adobe’s developed pre-upgrade and post-upgrade tasks that you can run, just follow the instructions from Adobe. We tried to run the pre-upgrade task on AEM6.2, but it had this error below:
To make your AEM upgrade a more seamless project, Adobe’s developed pre-upgrade and post-upgrade tasks that you can run, just follow the instructions from Adobe. We tried to run the pre-upgrade task on AEM6.2, but it had this error below:
*ERROR* [sling-threadpool-3a1e6c9e-47ac-4e73-8445-85babb95cf17-(apache-sling-job-thread-pool)-33-Pre Upgrade Tasks Queue(com/adobe/aem/preupgrade/job/RunAllPreUpgradeTasks)] com.adobe.aem.upgrade.prechecks.tasks.impl.RunAllPreUpgradeTasksImpl RunAllPreUpgradeTasks task failed.
Solution: configure workflow purge configuration and auditlog configuration in the configuration manager. (For more detail, see Prakash Venkatesh’s blog post.)
Solution: configure workflow purge configuration and auditlog configuration in the configuration manager. (For more detail, see Prakash Venkatesh’s blog post.)
Crx2oak Tool
This tool was firstly developed by Adobe to upgrade the CRX from Apache Jackrabbit 2 base (CRX2) to Apache Jackrabbit Oak base (CRX3). But don’t let the name fool you, it can actually be run as a standalone tool to migrate content from one repository to another, even they are the same version.
This tool is run in the command line, either as a new option when you start the 6.3 quickstart jar file or as a standalone Java program. There are many parameters you can pass in to customize content migration. The latest full list of parameters can be found here. One advantage of using crx2oak to migrate content, versus a content package, is that you can keep the version history data, even orphaned history data.
Sounds great, right? However, this tool is not that easy to use, with limited documentation and help pages. I’ve tried to use the tool (crx2oak-1.6.8-all-in-one.jar) as a standalone and migrate content from 6.3 to 6.3 and from 6.2 to 6.3, and both had different kinds of exceptions (see below). I have seen the same issues reported by different users in the Adobe forum, so be mindful of that, look for updates of the tool, and consult with the Adobe support team when you had difficulty using the tool on AEM 6.3.
I have seen the same issues reported by different users in the Adobe forum, so be mindful of that, and look for updates to the tool and consult with the Adobe support team if you have difficulty using the tool on AEM 6.3.
This tool was firstly developed by Adobe to upgrade the CRX from Apache Jackrabbit 2 base (CRX2) to Apache Jackrabbit Oak base (CRX3). But don’t let the name fool you, it can actually be run as a standalone tool to migrate content from one repository to another, even they are the same version.
This tool is run in the command line, either as a new option when you start the 6.3 quickstart jar file or as a standalone Java program. There are many parameters you can pass in to customize content migration. The latest full list of parameters can be found here. One advantage of using crx2oak to migrate content, versus a content package, is that you can keep the version history data, even orphaned history data.
Sounds great, right? However, this tool is not that easy to use, with limited documentation and help pages. I’ve tried to use the tool (crx2oak-1.6.8-all-in-one.jar) as a standalone and migrate content from 6.3 to 6.3 and from 6.2 to 6.3, and both had different kinds of exceptions (see below). I have seen the same issues reported by different users in the Adobe forum, so be mindful of that, look for updates of the tool, and consult with the Adobe support team when you had difficulty using the tool on AEM 6.3.
I have seen the same issues reported by different users in the Adobe forum, so be mindful of that, and look for updates to the tool and consult with the Adobe support team if you have difficulty using the tool on AEM 6.3.
ERROR c.a.g.c.c.MigrationSpecGenerator: I/O error during processing migration specification: org.apache.jackrabbit.oak.segment.file.InvalidFileStoreVersionException: Using oak-segment-tar, but oak-segment should be used
ERROR c.a.g.c.e.MigrationEngine: The internal error occurred during migration. The migration process has been aborted and it is not complete!
java.lang.RuntimeException: javax.jcr.RepositoryException: Failed to copy content
After many trials and errors, I finally found a combination of commands that worked and had a successful run to migrate content from my local AEM 6.2 to AEM 6.3. Thanks to this post from Adobe help and this post in Adobe forum.
This is the command I use, in case you need to reference: (and I place crx2oak-1.6.8-all-in-one.jar and logback.xml in the same directory as AEM 6.3 quickstart jar)
ERROR c.a.g.c.e.MigrationEngine: The internal error occurred during migration. The migration process has been aborted and it is not complete!
java.lang.RuntimeException: javax.jcr.RepositoryException: Failed to copy content
After many trials and errors, I finally found a combination of commands that worked and had a successful run to migrate content from my local AEM 6.2 to AEM 6.3. Thanks to this post from Adobe help and this post in Adobe forum.
This is the command I use, in case you need to reference: (and I place crx2oak-1.6.8-all-in-one.jar and logback.xml in the same directory as AEM 6.3 quickstart jar)
java -Dlogback.configurationFile=logback.xml \
-Xmx10g \
-jar crx2oak-1.6.8-all-in-one.jar \
segment-old:/Users/eddieyao/Projects/perficient/blog/author-aem-6.2/crx-quickstart/repository /Users/eddieyao/Projects/perficient/blog/author-aem-6.3-new/crx-quickstart/repository \
--include-paths=/content \
--datastore /Users/eddieyao/Projects/perficient/blog/author-aem-6.3-new/crx-quickstart/repository/datastore \
--copy-versions=true \
--copy-orphaned-versions=false
Overall, an AEM upgrade is not an easy task, especially when you have a multi-tenant project, many custom implementations, integrated with many solutions, and configured Mongo DB or node and data stores. It requires extensive assessment, strategic planning, thorough testing, strong collaboration, and technical implementation.
-Xmx10g \
-jar crx2oak-1.6.8-all-in-one.jar \
segment-old:/Users/eddieyao/Projects/perficient/blog/author-aem-6.2/crx-quickstart/repository /Users/eddieyao/Projects/perficient/blog/author-aem-6.3-new/crx-quickstart/repository \
--include-paths=/content \
--datastore /Users/eddieyao/Projects/perficient/blog/author-aem-6.3-new/crx-quickstart/repository/datastore \
--copy-versions=true \
--copy-orphaned-versions=false
Overall, an AEM upgrade is not an easy task, especially when you have a multi-tenant project, many custom implementations, integrated with many solutions, and configured Mongo DB or node and data stores. It requires extensive assessment, strategic planning, thorough testing, strong collaboration, and technical implementation.
It’s always a good idea to have your AEM experts around, form your team with a trusted Adobe solution partner, and consult with Adobe for custom recommendations when doing the upgrade.
No comments:
Post a Comment
If you have any doubts or questions, please let us know.