Upgrading Code and Customizations
When planning an upgrade, the following areas of an implementation must be investigated and addressed.
Overview
-
Pattern Detector - Run the Pattern Detector as described in upgrade planning, and described in detail on the Assessing the Upgrade Complexity with the Pattern Detector page. You get a pattern detector report that contains more details on areas that must be addressed in addition to the unavailable APIs/bundles in the Target version of AEM. The Pattern Detection report gives you an indication of any incompatibilities in your code. If none exists, then your deployment is already 6.5 compatible. You can still choose to do new development for using 6.5 functionality, but you do not need it just for maintaining compatibility. If there are incompatibilities reported, you can choose run in compatibility mode and defer your development for new 6.5 features or compatibility. Or, you can decide to do development after upgrade, and move to step 2. See Backward Compatibility in AEM 6.5 for more details.
-
**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.
-
**Compile with 6.5 Uber jar **- Update code base POMs to point to 6.5 uber jar and compile code against it.
-
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
-
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.
-
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. 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 Backward Compatibility in AEM 6.5.
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
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
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
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. For information about Service Users and how to phase out administrative sessions see Service Users in Adobe Experience Manager (AEM).
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 is still available in AEM 6.5 but is being deprecated. See Deprecated and removed features for more information. 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 under Enabling Access to Classic UI.
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, 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
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
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. See Overlays for generic information. Instructions for specific AEM overlays can be found below.
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
NOTEInstances 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:
-
On the instance that is getting upgraded, open CRXDE Lite by going to https://server:port/crx/de/index.jsp
-
Go to the following node:
/apps/dam/content
-
Rename the content node to content_backup by right-clicking the explorer pane in the left-hand side of the window, and choosing Rename.
-
Once the node has been renamed, create a node named content under
/apps/damnamed content and set its node type to sling:Folder. -
Move all the children nodes of content_backup to the newly created content node by right-clicking each children node in the explorer pane and selecting Move.
-
Delete the content_backup node.
-
The updated nodes beneath
/apps/damwith the correct node type ofsling:Foldershould 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 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
Adobe recommends putting custom scripts at /apps/settings/dam/indesign/scripts location. More information about InDesign Script customizations can be found under Integrate Adobe Experience Manager Assets with Adobe InDesign Server.
Recovering ContextHub Configurations
ContextHub configurations are affected by an upgrade. See Configuring ContextHub for instructions on how to recover existing ContextHub configurations.
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
NOTEThe 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
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.
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
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.
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.
Experience Manager
