Upgrading Code and Customizations

When planning an upgrade the following areas of an implementation need to be investigated and addressed.


  1. Pattern Detector - Run the Pattern Detector as described in upgrade planning and described in detail in this page to get a pattern detector report that contains more details on areas that need to be addressed in addition to the unavailable APIs/bundles in the Target version of AEM. The Pattern Detection report should give you an indication of any incompatibilities in your code, if there are none then your deployment is already 6.5 compatible, you can still choose to do new development for utilizing 6.5 functionality, but you don’t need it just for maintaining compatibility. If there are incompatibilities reported then you can choose to either a) Run in compatibility mode and defer your development for new 6.5 features or compatibility, b) Decide to do development after upgrade, and move to step 2. Please see please see Backward Compatibility in AEM 6.5 for more details.

  2. **Develop Code Base for 6.5 **- Create a dedicated branch or repository for the code base for the Target version. Use info from Pre-Upgrade Compatibility to plan areas of code to update.

  3. **Compile with 6.5 Uber jar **- Update code base POMs to point to 6.5 uber jar and compile code against this.

  4. Update AEM Customizations* - *Any customizations or extensions to AEM should be updated/validated to work in 6.5 and added to the 6.5 code base. Includes UI Search Forms, Assets Customizations, anything using /mnt/overlay

  5. Deploy to 6.5 Environment - A clean instance of AEM 6.5 (Author + Publish) should be stood up in a Dev/QA environment. Updated code base and a representative sample of content (from current production) should be deployed.

  6. QA Validation and Bug fix - QA should validate the application on both Author and Publish instances of 6.5. Any bugs found should be fixed and committed to the 6.5 code base. Repeat Dev-Cycle as necessary until all bugs are fixed.

Before proceeding with an upgrade you should have a stable application code base that has been thoroughly tested against the target version of AEM. Based on observations made in testing there could be ways to optimize the custom code. This might include refactoring the code to avoid traversing the repository, custom indexing to optimize search, or use of unordered nodes in JCR, amongst others.

In addition to the option of upgrading your code base and customizations to work with the new AEM version, 6.5 also helps manage your customizations more efficiently with the Backward Compatibility feature as described on this page.

As mentioned above and shown in the diagram below,running the Pattern Detector in the first step will help you assess the overall complexity of the upgrade and whether you want to run in compatibility mode or update your customizations to use all the new AEM 6.5 features. Please see the Backward Compatibility in AEM 6.5 page for more details.

Upgrade the Code Base

Create a Dedicated Branch for 6.5 Code in Version Control

All code and configurations required for your AEM implementation should be managed using some form of version control. A dedicated branch in version control should be created for managing any changes needed for the code base in the target version of AEM. Iterative testing of the code base against the target version of AEM and subsequent bug fixes will be managed in this branch.

Update the AEM Uber Jar version

The AEM Uber jar includes all AEM APIs as a single dependency in your Maven project’s pom.xml. It is always a best practice to include the Uber Jar as a single dependency instead of including individual AEM API dependencies. When upgrading the code base the version of the Uber Jar should be changed to point to the target version of AEM. If your project was developed on a version of AEM prior to the existence of the Uber Jar all individual AEM API dependencies should be removed and replaced by a single inclusion of the Uber Jar for the target version of AEM. The code base should then be recompiled against the new version of the Uber Jar. Any deprecated APIs or methods should be updated to be compatible with the target version of AEM.


Phase out use of Administrative Resource Resolver

The use of an administrative session through SlingRepository.loginAdministrative() and ResourceResolverFactory.getAdministrativeResourceResolver() was quite prevalent in code bases prior to AEM 6.0. These methods have been deprecated for security reasons as they give too broad of a level of access. In future versions of Sling these methods will be removed. It is highly recommended to refactor any code to use Service Users instead. More information about Service Users and how to phase out administrative sessions can be found here.

Queries and Oak Indexes

Any use of queries in the code base needs to be thoroughly tested as part of upgrading the code base. For customers upgrading from Jackrabbit 2 (versions of AEM older than 6.0) this is especially important as Oak does not index content automatically and custom indexes may need to be created. If upgrading from an AEM 6.x version the out of the box Oak index definitions may have changed and could effect existing queries.

Several tools for tools for analyzing and inspecting query performance are available:

Classic UI Authoring

Classic UI authoring is still available in AEM 6.5 but is being deprecated. More information can be found here. If your application is currently running on the Classic UI author environment it is recommended to upgrade to AEM 6.5 and continue using the Classic UI. Migration to the Touch UI can then be planned as separate project to be completed over several development cycles. In order to use the Classic UI in AEM 6.5 several OSGi configurations are needed to be committed to the code base. More details on how to configure this can be found here.

Align with 6.5 Repository Structure

To make upgrades easier and ensure that configurations are not overwritten during an upgrade, the repository is restructured in 6.4 to separate content from configuration.

Therefore, a number of settings must be moved to no longer reside under /etc as had been the case in the past. To review the full set of repository restructuring concerns that must be reviewed and accomodated in the updated to AEM 6.4, see Repository Restructuring in AEM 6.4.

AEM Customizations

All customizations to the AEM authoring environment in the source version of AEM need to be identified. Once identified, it is recommended that each customizations be stored in version control or at a minimum backed up as a part of a content package. All customizations should be deployed and validated in a QA or Staging environment running the target version of AEM prior to a production upgrade.

Overlays in general

It is a common practice to extend AEM out of the box functionality by overlaying nodes and/or files under /libs with additional nodes under /apps. These overlays should be tracked in version control and tested against the target version of AEM. If a file (be it JS, JSP, HTL) is overlayed, it is recommended to leave a comment on what functionality has been augmented for easier regression testing on the target version of AEM. More information about overlays in general can be found here. Instructions for specific AEM overlays can be found below.

Upgrading Custom Search Forms

Custom Search Facets require some manual adjustments after the upgrade in order to function properly. For more details, see Upgrading Custom Search Forms.

Assets UI Customizations


This procedure is required only for upgrades from versions older than AEM 6.2.

Instances that have customized Assets deployments need to be prepared for the upgrade. This is needed to ensure that all customized content is compatible with the new 6.4 node structure.

You can prepare customizations to the Assets UI by doing the following:

  1. On the instance that needs to be upgraded, open CRXDE Lite by going to https://server:port/crx/de/index.jsp

  2. Go to the following node:

    • /apps/dam/content
  3. Rename the content node to content_backup. You can do this by right clicking the explorer pane in the left hand side of the window and choosing Rename.

  4. Once the node has been renamed, create a new node named content under /apps/dam named content and set its node type to sling:Folder.

  5. Move all the children nodes of content_backup to the newly created content node. You can do this by right clicking each children node in the explorer pane and selecting Move.

  6. Delete the content_backup node.

  7. The updated nodes beneath /apps/dam with the correct node type of sling:Folder should ideally be saved into version control and deployed with the code base or at a minimum backed up as content package.

Generating Asset IDs for Existing Assets

To generate asset IDs for existing assets, upgrade the assets when you upgrade your AEM instance to run AEM 6.5. This is required to enable the Assets Insights feature. For more details, see Add embed code.

To upgrade assets, configure the Associate Asset IDs package in the JMX console. Depending on the number of assets in the repository, migrateAllAssets may take a long time. Our internal tests estimate roughly one hour for 125 thousand assets on TarMK.


If you require asset IDs for a subset of your entire assets, use the migrateAssetsAtPath API.

For all other purposes, use the migrateAllAssets() API.

InDesign Script Customizations

Adobe recommends putting custom scripts at /apps/settings/dam/indesign/scripts location. More information about InDesign Script customizations can be found here.

Recovering ContextHub Configurations

ContextHub configurations are affected by an upgrade. Instructions on how to recover existing ContextHub configurations can be found here.

Workflow Customizations

It is a common practice to update modify out of the box workflows to add or remove un-needed functionality. A common workflow that is customized is the DAM Update Asset workflow. All workflows required for a custom implementation should be backed up and stored in version control as they may be overwritten during an upgrade.

Editable Templates


This procedure is required only for Sites upgrades using Editable Templates from AEM 6.2

The structure for Editable templates changed between AEM 6.2 and 6.3. If you are upgrading from 6.2 or earlier and If your site content is built using editable templates you will need to use the Responsive Nodes Clean Up Tool. The tool is meant to run after an upgrade in order to clean up content. It will need to be run on both Author and Publish tiers.

CUG Implementation Changes

The implementation of Closed User Groups has changed significantly to address performance and scalability limitations in previous versions of AEM. The previous version of CUG was deprecated in 6.3 and the new implementation is only supported in the Touch UI. If you are upgrading from 6.2 or ealier then Instructions to migrate to the new CUG implementation can be found here.

Testing Procedure

A comprehensive test plan should be prepared for testing upgrades. Testing the upgraded code base and application will need to be done in lower environments first. Any bugs found should be fixed in an iterative fashion until the code base is stable, only then should higher level environments be upgraded.

Testing the Upgrade Procedure

The upgrade procedure as outlined here should be tested on Dev and QA environments as documented in your customized run book (see Planning Your Upgrade). The upgrade procedure should be repeated until all steps are documented in the upgrade run book and the upgrade process is smooth.

Implementation Test Areas

Below are critical areas of any AEM implementation that should be covered by your test plan once the environment has been upgraded and the upgraded code base has been deployed.

Functional Test Area Description
Published Sites Testing the AEM implementation and associated code on the publish tier
through the dispatcher. Should include criteria for page updates and
cache invalidation.
Authoring Testing the AEM implementation and associated code on the Author tier. Should include page, component authoring and dialogs.
Integrations with Marketing Cloud Solutions Validating integrations with products like Analytics, DTM, and Target.
Integrations with 3rd Party Systems Any 3rd party integrations should be validated on both Author and Publish tiers.
Authentication, Security and Permissions Any authentication mechanisms like LDAP/SAML should be validated.
Permissions and groups should be tested on both Author and Publish
Queries Custom indexes and queries should be tested along with query performance.
UI Customizations Any extensions or customizations to the AEM UI in the author environment.
Workflows Custom and/or out of the box workflows and functionality.
Performance Testing Load testing should be performed on both Author and Publish tiers that simulate real-world scenarios.

Document Test Plan and Results

A test plan should be created that covers the above implementation test areas. In many cases it will make sense to separate the test plan by Author and Publish task lists. This test plan should be executed on Dev, QA, and Stage environments prior to upgrading Production environments. Test results and performance metrics should be captured on lower environments to provide comparison when upgrading Stage and Production environments.

On this page