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.
- Pre-Upgrade Compatibility Check - detectUsageOfUnavailableAPI Task will tell you which APIs / bundles are unavailable on Target version of AEM
- Develop Code Base for 6.3 - 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.3 Uber jar - Update code base POMs to point to 6.3 uber jar and compile code against this.
- Update AEM Customizations - Any customizations or extensions to AEM should be updated/validated to work in 6.3 and added to the 6.3 code base. Includes UI Search Forms, Assets Customizations, anything using /mnt/overlay
- Deploy to 6.3 Environment - A clean instance of AEM 6.3 (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.3. Any bugs found should be fixed and committed to the 6.3 code base. Repeat Dev-Cycle as necessary until all bugs are fixed.
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.
The pre-upgrade compatibility checks allow checking existing AEM instances for their upgradability by detecting APIs in use that are not compatible with 6.3 and might potentially break after upgrade. This could serve as an assessment of the development effort that might be involved in moving to the next version.
In order to use this feature, you need to install the latest version of the pre-upgrade-tasks-content content package on the instance you are upgrading from.
You can find links to download the package from Package Share in Pre-Upgrade Maintenance Tasks.
The checks can be invoked using the PreUpgradeTasksMBean MBean that is part of the JMX console.
The method to be invoked for the Pre Upgrade Compatibility check is detectUsageOfUnavailableAPI with the target version of AEM you want to check against passed as a parameter, as shown here:
The list of imported packages and bundles that use incompatible APIs and will not work after the upgrade will be returned in the response as shown below. The results will also be added to the upgrade.log file. Each of the incompatible APIs need to be addressed as part of the 6.3 code base.
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.3.0</version> <classifier>apis</classifier> <scope>provided</scope> </dependency>
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.
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 is still available in AEM 6.3 but will be deprecated in future versions. 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.3 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.3 several OSGi configurations are needed to be committed to the code base. More details on how to configure this can be found here.
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.
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.
Custom Search Facets require some manual adjustments after the upgrade in order to function properly. For more details, see Upgrading Custom Search Forms.
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.3 node structure.
You can prepare customizations to the Assets UI by doing the following:
To generate asset IDs for existing assets, upgrade the assets when you upgrade your AEM instance to run AEM 6.3. 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.
Any modifications to InDesign Script customizations will not be preserved after upgrade. Any changes made to files beneath /etc/dam/indesign/scripts in order to customize AEM and InDesign integration need to be tracked. More information about InDesign Script customizations can be found here.
ContextHub configurations are effected by an upgrade. Instructions on how to recover existing ContextHub configurations can be found here.
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.
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 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.
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 has been deprecated in 6.3 and the new implementation is only supported in the Touch UI. Instructions to migrate to the new CUG implementation can be found here.
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.
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.
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
|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.|
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.