Things to Look Out for When Upgrading to AEM 6.3

If you have been using Adobe Experience Manager (AEM) to host your sites for a while, and are now looking to upgrade to AEM 6.3 (whether considering an in-place upgrade or a fresh new install), I am sure you’ve already found some good public documentation from Adobe. (If you are wondering if you should upgrade, here are some compelling reasons from Adobe, as well as my previous blog post.)
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 manager, dev manager, 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:

1. 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.)
2. maven-enforcer-plugin to use Java 1.8 (Although Java 1.7 still works in AEM 6.3, it is not supported by Adobe.)
3. maven-compiler-plugin to use Java 1.8
4. maven-surefire-plugin
5. maven-failsafe-plugin
6. maven-sling-plugin
7. content-package-maven-plugin
8. maven-bundle-plugin
9. maven-dependency-plugin
10. build-helper-maven-plugin
11. OSGI dependencies (osgi.core, osgi.cmpn, osgi.annotation) version
12. slf4j-simple and slf4j-api
13. junit
14. servlet-api
15. apache.sling.models.api (select the version you need since some are introduced in a later version)
16. commons-lang

You may want to ask to which of the above dependencies and plugins needs to be updated. Great question. Good news, Adobe just released AEM project archetype 12 for 6.3 a couple days ago! AEM project archetype 12 is created to generate a project structure template for AEM 6.3 and above. You can create a new AEM project and reference to the POM files generated from archetype 12 to see exactly what you need to update. That’s what I did for this blog’s purpose and I pushed my code to my Github project.
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

Inspired Digital Experiences for Manufacturing & Automotive

Whether you’re just beginning your digital transformation journey or are well on your way, we invite you to explore our partnership with Adobe and our diverse capabilities in manufacturing and automotive.

Download Lookbook

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 your bundles status is at “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:

1. RTE and RTE plugins: plugins in dialog are covering up text editing area, RTE box shrinks, inline editing is messed up. (please reference to this link for the fix)
2. Multifield: can’t load content, add field button doesn’t work. (please reference to this link for the fix)
3. Classic UI page properties: can’t open (deprecated in April 2018, removed in April 2019)
4. 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 reference 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:

*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 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 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 Adobe forum, so be mindful of that, look for updates of the tool and consult with 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)

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. 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.