Assessing the Upgrade Complexity with the AEM Analyzer

Last update: March 7, 2025

Topics:
Upgrading

CREATED FOR:

Admin

Overview

The AEM 6.5 LTS Analyzer provides an assessment of your current AEM implementation by indicating areas that are required to update in order to provide a seamless upgrade experience to 6.5 LTS.

The tool generates a report that identifies areas of potential refactoring.

AEM 6.5 LTS Analyzer Report

The AEM 6.5 LTS Analyzer Report is used to gain a high level understanding of general upgrade readiness. The report consists of findings within categories of issues that must be addressed in order to ensure a successful upgrade to AEM 6.5 LTS.

The AEM 6.5 LTS Analyzer report includes the following categories:

Application functionality that must be refactored
Repository items that must be moved to a supported location
Configuration issues
AEM 6.5 features that have been removed by new functionality or that are currently not supported on AEM 6.5 LTS
Remove Java and Guava API usage

Additional information about the categories and possible implications and solutions associated with those categories are provided via links from within the AEM 6.5 LTS Analyzer Report.

Availability

The AEM Analyzer can be downloaded as a zip file from the Software Distribution portal. You can install the package via Package Manager on your source AEM instance.

Important Considerations for Using AEM Analyzer

Follow the section below to understand the important considerations for running the AEM Analyzer:

The Analyzer report is built using the output of the AEM Pattern Detector. The version of Pattern Detector used by Analyzer is included in the AEM Analyzer installation package
AEM Analyzer may only be run by the admin user or a user in the administrators group
Analyzer is supported on AEM instances with version 6.5 and above.

NOTE

To avoid an impact on business critical instances, it is recommended that you run AEM Analyzer on an Stage environment that is as close as possible to the Production environment in the areas of customizations, configurations, content and user applications. Alternatively, it can be run on a clone of the production Author environment.

The generation of AEM Analyzer report contents can take a significant amount of time, from several minutes to a few hours. The amount of time required is highly dependent on the size and nature of the AEM repository content, the AEM version, and other factors
Because of the significant time that may be required to generate the report content, it is generated by a background process and held in a cache. Viewing and downloading the report should be relatively fast because it utilizes the content cache until it expires or the report is explicitly refreshed. During the generation of report content you may close your browser tab and return at a later time to view the report once its contents are available in the cache.

Viewing the AEM Analyzer Report

Follow the steps below in order to view the AEM Analyzer report:

Select Adobe Experience Manager and navigate to Tools - Operations - 6.5 LTS Modernizer
Click AEM 6.5 LTS Analyzer to open it
Click Generate Report to execute the AEM Analyzer
While the AEM Analyzer is generating the report, you can see the progress made by the tool on the screen. It displays the progress in terms of the percentage completed. It also displays the number of items analyzed and the number of findings
After the 6.5 LTS Analyzer report is generated, it displays a summary and the number of the findings in a tabular format organized by the type of finding and the importance level. To get more details about a particular finding, you can click the number that corresponds to the type of finding in the table
You have the option of downloading the report in a comma-separated values (CSV) format by clicking on Export to CSV. You may force the Analyzer to clear its cache and regenerate the report by clicking Refresh Report. If the cache expires, you have to regenerate the report.

Interpreting the AEM Analyzer Report

When the 6.5 LTS Analyzer tool is run in the AEM instance, the report is displayed as results in the tool window.

The format of the report is:

Report Overview: Information about the report itself that includes the following information:
- Report Time: When the report contents were generated and first made available
- Expiration Time: When the report contents cache will expire
- Generation Time Period: The amount of time in which the report was generated
- Finding Count: The total number of findings included in the report
System Overview: Information about the AEM system on which the Analyzer was run on
Finding Categories: Multiple sections that each address one or more findings of the same category. Each section includes the following: Category name, sub-types, finding count and importance, summary, link to category documentation, and individual finding information.

An importance level is assigned to each finding to indicate a rough priority for action.

NOTE

To learn more about each Finding Category, see Pattern Detector Categories.

In order to understand the importance levels, follow the table below:

Importance

Description

INFO

This finding is provided for informational purposes.

ADVISORY

This finding is potentially an upgrade issue. Further investigation is recommended.

CRITICAL

This finding is very likely to be an upgrade issue that must be addressed to prevent loss of function or performance.

Interpreting the AEM 6.5 LTS Analyzer CSV Report

When you click the CSV option from your AEM instance, the CSV format of the Analyzer report is built from the content cache and returned to your browser. Depending on your browser settings, this report is automatically downloaded as a file with a default name of report.csv.

If the cache has expired, then the report is regenerated before the CSV file is built and downloaded.

The CSV format of the report includes information that is generated from the Pattern Detector output, sorted and organized by category type, sub-type, and importance level. Its format is suitable for viewing and editing in an application such as Microsoft Excel. It is intended to provide all the finding information in a repeatable format that can be helpful when comparing reports over time to measure progress.

The columns of the CSV format report are:

code: the category code
type: the category name
subtype: the category sub-type
importance: the importance level
identifier: the primary identifier of the finding
message: the message provided for the finding
context: a JSON string of finding data

A value of “\N” in a column for an individual finding indicates that no data was provided.

HTTP Interface

The 6.5 LTS Analyzer provides an HTTP interface that may be used as an alternative to its user interface within AEM. The interface supports both HEAD and GET commands. It may be used to generate the Analyzer report and return it in one of three formats: JSON, CSV, and tab-separated values (TSV).

The following URLs are available for HTTP access, where <host> is the hostname, alongside port if necessary, of the server on which the Analyzer is installed:

http://<host>/apps/aem66-analyzer/analysis/report.json for JSON format
http://<host>/apps/aem66-analyzer/analysis/report.csv for CSV format
http://<host>/apps/aem66-analyzer/analysis/report.tsv for TSV format

Executing an HTTP Request

One simple way to execute an HTTP request is to open a tab in the same browser in which you have already signed in to AEM as an administrator. You can enter the URL in the browser tab and have the results displayed or downloaded by the browser.

You may also use a command-line tool such as curl or wget and any HTTP client application. When not using a browser tab with an authenticated session, you must supply an administrative user name and password as part of the comment.

The following is an example of how this can be done:

curl -u admin:admin 'http://localhost:4502/apps/aem66-analyzer/analysis/report.csv' > report.csv.

Adjusting the Cache Lifetime

The default AEM 6.5 LTS Analyzer cache lifetime is 24 hours. With the option for refreshing a report, and regenerating the cache, in both the AEM instance and the HTTP interface, this default value is likely to be appropriate for most uses of the AEM 6.5 LTS Analyzer. If the report generation time is particularly long for your AEM instance, you may want to adjust the cache lifetime to minimize the regeneration of the report.

The cache lifetime value is stored as the maxCacheAge property on the following repository node:

/apps/aem66-analyzer/content/modernizer/analyzer/jcr:content

The value of this property is the cache lifetime in seconds. An administrator may adjust the cache lifetime using CRX/DE Lite.

Using Content Transformer

Availability

The Content Transformer is bundled with the AEM 6.5 LTS Analyzer that can be downloaded as a zip file from the Software Distribution Portal.

Important Considerations for Using Content Transformer

See the section below to understand the important considerations for using the Content Transformer (CT):

To use the Content Transformer, you must first run the AEM Analyzer on your AEM environment
Although you can run the Content Transformer on your Production environment, it is recommended that you run the Content Transformer on a clone of your Production environment. More importantly, you need to ensure that the AEM Analyzer and the CT are run on the same environment
You need to be an administrator on the environment where you want to run the Content Transformer
A remove operation which can change the source content will create a backup package of the source paths under /etc/packages/modernizer-content-transformation by default before the transformation. Although the remove operation dialog has an option to disable/enable the creation of the backup package, it is strongly recommended to always have the enable package creation selected
Each page in the Content Transformer is configured to list a maximum of 50 findings. Hence, a maximum of 50 findings can be transformed at a time. This is done to provide a timely response in the UI.

Opening the Content Transformer

Log in to the source AEM instance as an administrator and go to the start page at https://host:port/aem/start.htm
Navigate to Tools - Operations - 6.5 LTS Modernizer
Click on the Content Transformer for 6.5 LTS Analyzer report card
If the Analyzer report is not generated, the Transform Content page will display No Report. The same No Report message will also appear if all content-related findings have been removed
Below is an example of how the Content Transformer Overview page will look like if the creation of the AEM Analyzer report was successful and if it found content related issues.

The expiration time left for the AEM Analyzer report is shown on the side rail. It is recommended to run the Content Transformer with the latest AEM Analyzer report in order to avoid missing any content-related findings

Opening Content Transformer 4

You can filter the issues based on Pattern Code, Subtype, Importance, and Source

Removing Paths

You can select all or specific issues and selet Remove to resolve them

NOTE
A Remove operation creats a backup package of the source paths under /etc/packages/modernizer-content-transformation by default, before the transformation. Although the remove operation dialog has an option to disable/enable the creation of the backup package, it is strongly recommended to always have the enable package creation selected.
An example of a backup package created for the remove operation of the paths is shown below. You can click Install to bring back the source paths

CAUTION
Do not delete /etc/packages/modernizer-content-transformation, as this is the location where the backup packages reside. You can delete this location to reduce the repository size only when you are sure that you do not need these packages anymore.
Optionally, you can package selected content findings for future use. To do this, select the findings you want to include, then click Package from top left. Enter a package name, choose a package path, and click the Package button to complete the process.

Known Issues

Sometimes, the Remove operation may display the notification: "Some paths have not been removed successfully, please check the logs and try again.". However, if the paths were actually removed, you can safely ignore this message
Similarly, the Package operation may fail with the error: "Error while performing the desired operation, please check the logs and try again.". This is likely be due to session expiry. In such cases, retrying the operation should resolve the issue.

recommendation-more-help