Upgrading Code and Customizations upgrading-code-and-customizations

When planning an upgrade the following areas of an implementation need to 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. 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.4 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.4 features. Please see the Backward Compatibility in AEM 6.4 page for more details.

Upgrade the Code Base upgrade-code-base

Create a Dedicated Branch for 6.4 Code in Version Control create-a-dedicated-branch-for-6-4-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 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.

<dependency>
    <groupId>com.adobe.aem</groupId>
    <artifactId>uber-jar</artifactId>
    <version>6.4.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 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 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

Classic UI authoring is still available in AEM 6.4 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.4 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.4 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.4 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, 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 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 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 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 assets-ui-customizations

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:

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.4. This is required to enable the Assets Insights feature. For more details, see Adding 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 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 effected 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 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 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 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 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 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 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. 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.