Documentation AEM as a Cloud Service User Guide

Using Best Practices Analyzer

Last update: March 3, 2025

Topics:
Migration

CREATED FOR:

Admin

Important Considerations for Using Best Practices Analyzer

Follow the section below to understand the important considerations for running the Best Practices Analyzer (BPA):

The BPA report is built using the output of the Adobe Experience Manager (AEM) Pattern Detector. The version of Pattern Detector used by BPA is included in the BPA installation package.
BPA may only be run by the admin user or a user in the administrators group.
BPA is supported on AEM instances with version 6.1 and above.

NOTE
See Installing on AEM 6.1 for special requirements for installing BPA on AEM 6.1.
BPA can run on any environment, but it is preferred to have it run on a Stage environment.

NOTE
To avoid an impact on business critical instances, it is recommended that you run BPA 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 BPA 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 contents, they are 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 contents you may close your browser tab and return at a later time to view the report once its contents are available in the cache.

Availability

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

NOTE

Download the Best Practices Analyzer from the Software Distribution portal.

Source Environment Connectivity

The source AEM instance may be running behind a firewall where it can only reach certain hosts which have been added to an Allow List. To automatically upload the BPA generated report to Cloud Acceleration Manager successfully, the following endpoints need to be accessible from the instance that is running AEM:

The Azure blob storage service: casstorageprod.blob.core.windows.net

Viewing the Best Practices Analyzer Report

Adobe Experience Manager 6.3.0 and later

Follow this section to learn how to view the Best Practices Analyzer report:

Select Adobe Experience Manager and navigate to tools > Operations > Best Practices Analyzer.
Click Generate Report to execute the Best Practices Analyzer.

NOTE

Starting from BPA version 2.1.54, a new feature has been introduced to obtain the Lighthouse Score.

After clicking Generate Report, a pop-up will appear requesting the AEM Public Site URL for the Lighthouse Score. The user need to enter a valid URL in the provided field.
1. If the URL is valid, a success message will be displayed.
2. If the URL is invalid, an error message will be shown.
Provide the BPA upload key to automatically upload the generated BPA report to Cloud Acceleration Manager (CAM). To get the upload key, navigate to the Best Practices Analysis in CAM

NOTE

You have the option to skip the automatic upload to CAM by selecting Skip report auto upload to CAM. If you choose to skip, you will need to manually download the BPA report as a comma-separated value file and then upload the file in CAM. It is recommended to use the upload key option since it streamlines the operation.

IMPORTANT

When manually uploading to CAM, report sizes are restricted to approximately 200MB. For larger reports you will need to leverage the automatic upload.

The Generate button becomes active when a valid key is provided. Click on Generate to initiate report generation.
While the BPA is generating the report, you can see the progress made by the tool on the screen. It displays the progress in terms of percentage completed. It also displays the number of items analyzed and also displays the number of findings found.

NOTE

The BPA upload key expiration timestamp is displayed on the top right corner. You should renew the BPA upload key when it’s near its expiration. To renew the key, you can click on Renew to navigate to CAM to renew the key.

After the BPA 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 also have the option to view the report in CAM by clicking on Go to CAM. This will take you to the Best Practices Analysis page in CAM.

You may force the BPA to clear its cache and regenerate the report by clicking Refresh Report.

Refresh report

If the cache expires, you have the option of viewing the last generated report in CAM by clicking on View the last generated report in CAM or initiate a new report generation by clicking on Generate New Report.

No report

Using Filters in the Best Practices Analyzer Report

To filter out findings related to ACS Commons, follow the steps below:

Click the left rail icon on the left-hand side of the page. This will display the ACS Commons Filter. Click the ACS Commons Filter to display the interactive checkbox as shown in the image below.

NOTE
The left rail icon will appear only if the BPA detects usage of ACS Commons.
Unselect the box to filter out all findings related to ACS Commons. You should see a Filtered Finding Count on the report as shown in the image below. The filter is also applied to the report when it is exported in a comma-separated-value (CSV) format.

NOTE
The ACS Commons findings should not be ignored. See documentation to determine compatibility with AEM as a Cloud Service.

Interpreting the Best Practices Analyzer Report

When the Best Practices 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 time spent by the report contents generation process.
- Finding Count: The total number of findings included in the report.
System Overview: Information about the AEM system on which the BPA was run.
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.

Follow the table below to understand the importance levels:

Importance

Description

INFO

This finding is provided for informational purposes.

ADVISORY

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

MAJOR

This finding is likely to be an upgrade issue that should be addressed.

CRITICAL

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

Interpreting the Best Practices Analyzer CSV Report

When you click the CSV option from your AEM instance, the CSV format of the Best Practices 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 results.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 allthe 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
other: additional information about the finding
message: the message provided for the finding
moreInfo: a link which may be used to access online help about the category
context: a JSON string of finding data

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

HTTP Interface

The BPA 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 BPA 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, and port if necessary, of the server on which the BPA is installed:

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

Executing an HTTP Request

The HTTP interface may be used in a variety of methods.

One simple way is to open a browser 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/best-practices-analyzer/analysis/report.csv' > report.csv.

Headers and Parameters

The following HTTP headers are used by this interface:

Cache-Control: max-age=<seconds>: Specifies the cache freshness lifetime in seconds. (See RFC 7234.)
Prefer: respond-async: Specifies that the server should respond asynchronously. (See RFC 7240.)
Prefer: return=minimal: Specifies that the server should return a minimal response. (See RFC 7240.)

The following HTTP query parameters are available as a convenience for when HTTP headers might not be easily used:

max-age (number, optional): Specifies the cache freshness lifetime in seconds. This number must be 0 or greater. The default freshness lifetime is 86400 seconds. Without this parameter or the corresponding header, a fresh cache is used to serve requests for 24 hours, at which point the cache must be regenerated. Using max-age=0 will force the cache to be cleared and initiate a regeneration of the report, using the previous non-zero freshness lifetime for the newly generated cache.
respond-async (boolean, optional): Specifies that the response should be provided asynchronously. Using respond-async=true when the cache is stale will cause the server to return a response of 202 Accepted without waiting for the cache to be refreshed and for the report to be generated. If the cache is fresh then this parameter has no effect. The default value is false. Without this parameter or the corresponding header the server will respond synchronously, which may require a significant amount of time and require an adjustment to the maximum response time for the HTTP client.
may-refresh-cache (boolean, optional): Specifies that the server may refresh the cache in response to a request if the current cache is empty, stale, or soon to be stale. If may-refresh-cache=true, or if it is not specified, then the server may initiate a background task which will invoke the Pattern Detector and refresh the cache. If may-refresh-cache=false then the server will not initiate any refresh task that would otherwise have been done if the cache is empty or stale, in which case the report is empty. Any refresh task which is already in process will not be affected by this parameter.
return-minimal (boolean, optional): Specifies that the response from the server should only include the status containing the progress indication and cache status in the JSON format. If return-minimal=true, then the response body is limited to the status object. If return-minimal=false, or if it is not specified, then a complete response is provided.
log-findings (boolean, optional): Specifies that the server should log the contents of the cache when it is first built or refreshed. Each finding from the cache is logged as a JSON string. This logging will only occur if log-findings=true and the request generates a new cache.

When both an HTTP header and corresponding query parameter are present, the query parameter will take precedence.

A simply way to initiate the generation of the report via the HTTP interface is with the following command:
curl -u admin:admin 'http://localhost:4502/apps/best-practices-analyzer/analysis/report.json?max-age=0&respond-async=true'.

Once a request has been made, the client need not remain active for the report to be generated. The report generation could be initiated with one client using an HTTP GET request and, once the report has been generated, viewed from the cache with another client or with the BPA tool in the AEM user interface.

Responses

The following response values are possible:

200 OK: Indicates that the response contains findings from the Pattern Detector which were generated within the freshness lifetime of the cache.
202 Accepted: Used to indicate that the cache is stale. When respond-async=true and may-refresh-cache=true this response indicates that a refresh task is underway. When may-refresh-cache=false this response simply indicates that the cache is stale.
400 Bad Request: Indicates that there was an error with the request. A message in Problem Details format (see RFC 7807) provides more details.
401 Unauthorized: Indicates that the request was not authorized.
500 Internal Server Error: Indicates that an internal server error occurred. A message in Problem Details format provides more details.
503 Service Unavailable: Indicates that the server is busy with another response and cannot service this request in a timely manner. This is only likely to occur when synchronous requests are made. A message in Problem Details format provides more details.

Administrator Information

Cache Lifetime Adjustment

The default BPA 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 BPA. 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/best-practices-analyzer/content/BestPracticesReport/jcr:content

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

Installing on AEM 6.1

BPA utilizes a system service user account named repository-reader-service to execute the Pattern Detector. This account is available on AEM 6.2 and later. On AEM 6.1, this account must be created prior to installation of BPA by taking the following steps:

Follow the instructions at Creating a new service user to create a user. Set the UserID to repository-reader-service and leave the Intermediate Path empty and then click the green checkmark.
Follow the instructions at Managing Users and Groups, specifically the instructions for Adding Users to a Group to add the repository-reader-service user to the administrators group.
Install the BPA package via Package Manager on your source AEM instance. (This will add the necessary configuration amendment to the ServiceUserMapper configuration for the repository-reader-service system service user.)

recommendation-more-help