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.
Please 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.
In order to avoid an impact on business critical instances, it is recommended that you run BPA on an Author 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.
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.
Download the Best Practices Analyzer from the Software Distribution portal.
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 on Generate Report to execute the Best Practices Analyzer.
While the BPA is generating the report, you can see the progress made by the tool on the screen. It displays the number of items analyzed and also displays the number of findings found.
Once 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 on the number that corresponds to the type of finding in the table.
The above action will automatically scroll to the location of that finding in the report.
You have the option of downloading the report in a comma-separated values (CSV) format by clicking on Export to CSV, as shown in the figure below.
You may force the BPA to clear its cache and regenerate the report by clicking Refresh Report.
While the report is being regenerated, it displays the progress in terms of percentage completed as shown in the image below.
To filter out findings related to ACS Commons, follow the steps below:
Click on the left rail icon on the left-hand side of the page. This will display the ACS Commons Filter. Click on the ACS Commons Filter to display the interactive checkbox as shown in the image below.
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.
The ACS Commons findings should not be ignored. Refer to documentation to determine compatibility with AEM as a Cloud Service.
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:
An importance level is assigned to each finding to indicate a rough priority for action.
To learn more about each Finding Category, refer to Pattern Detector Categories.
Follow the table below to understand the importance levels:
|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.|
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 will be automatically downloaded as a file with a default name of
If the cache has expired then the report will be 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 of 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:
A value of “\N” in an column for an individual finding indicates that no data was provided.
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.jsonfor JSON format
http://<host>/apps/best-practices-analyzer/analysis/report.csvfor CSV format
http://<host>/apps/best-practices-analyzer/analysis/report.tsvfor TSV format
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
wget as well as 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.
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 will be used to serve requests for 24 hours, at which point the cache must be regenerated. Using
max-age=0will 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=truewhen the cache is stale will cause the server to return a response of
202 Acceptedwithout 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=falsethen 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 will be 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 will be limited to the status object. If
return-minimal=false, or if it is not specified, then a complete response will be 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 will be logged as a JSON string. This logging will only occur if
log-findings=trueand 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.
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
may-refresh-cache=truethis response indicates that a refresh task is underway. When
may-refresh-cache=falsethis 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.
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 wish to adjust the cache lifetime in order to minimize the regeneration of the report.
The cache lifetime value is stored as the
maxCacheAge property on the following repository node:
The value of this property is the cache lifetime in seconds. An administrator may adjust the cache lifetime using CRX/DE Lite.
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
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.)