Upgrading Code and Customizations upgrading-code-and-customizations

When planning an upgrade, the following areas of an implementation must be investigated and addressed.

Overview overview

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. For example, it might include refactoring the code to avoid traversing the repository, custom indexing to optimize search, or use of unordered nodes in JCR, among others.

In addition to optionally 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 can help you assess the overall complexity of the upgrade. It can also help you decide whether you want to run in compatibility mode or update your customizations to use all the new AEM 6.5 features. See the Backward Compatibility in AEM 6.5 page for more details.

Upgrade the Code Base upgrade-code-base

Create a Dedicated Branch for 6.5 Code in Version Control 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 is managed in this branch.

Update the AEM Uber Jar version 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, change the version of the Uber Jar to point to the target version of AEM. If your project was developed on a version of AEM before the existence of the Uber Jar, remove all individual AEM API dependencies. Replace them with a single inclusion of the Uber Jar for the target version of AEM. Recompile the code base against the new version of the Uber Jar. Update any deprecated APIs or methods so they are compatible with the target version of AEM.

<dependency>
    <groupId>com.adobe.aem</groupId>
    <artifactId>uber-jar</artifactId>
    <version>6.5.0</version>
    <classifier>apis</classifier>
    <scope>provided</scope>
</dependency>

Phase out use of Administrative Resource Resolver phase-out-use-of-administrative-resource-resolver

The use of an administrative session through SlingRepository.loginAdministrative() and ResourceResolverFactory.getAdministrativeResourceResolver() was prevalent in code bases before 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 are going to 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 queries-and-oak-indexes

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

The following tools are available for analyzing and inspecting query performance:

Classic UI Authoring 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 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 a separate project to complete over several development cycles. To use the Classic UI in AEM 6.5, several OSGi configurations must be committed to the code base. More details on how to do the configuration can be found here.

Align with 6.5 Repository Structure align-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, several 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 accommodated in the updated to AEM 6.4, see Repository Restructuring in AEM 6.4.

AEM Customizations aem-customizations

All customizations to the AEM authoring environment in the source version of AEM must 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 before a production upgrade.

Overlays in general 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 (such as JS, JSP, HTL) is overlaid, Adobe recommends that you leave a comment on what functionality was 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 upgrading-custom-search-forms

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

Assets UI Customizations assets-ui-customizations

Instances that have customized Assets deployments must be prepared for the upgrade. This action is necessary 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:

Generating Asset IDs for Existing Assets 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 step 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. Adobe’s internal tests estimate roughly one hour for 125000 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 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 recovering-contexthub-configurations

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

Workflow Customizations workflow-customizations

It is a common practice to edit out of the box workflows to add or remove unneeded 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 editable-templates

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 must use the Responsive Nodes Clean Up Tool. The tool is meant to run after an upgrade to clean up content. Run it on both Author and Publish tiers.

CUG Implementation Changes 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 earlier, then instructions to migrate to the new CUG implementation can be found here.

Testing Procedure testing-procedure

A comprehensive test plan should be prepared for testing upgrades. Testing the upgraded code base and application must 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 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 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.

Document Test Plan and Results document-test-plan-and-results

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