AEM CMS Plugin Debugging Tooling
With version 3.0.11 and later of the Adobe Experience Manger (AEM) CMS plugin debugging tooling should be installed as a part of the installation package. This tooling is intended to be used in combination with other troubleshooting efforts to help to debug some things we have found can cause issues with the AEM CMS plugin within AEM authoring environments. The tooling runs a series of checks in the AEM authoring environment the Siteimprove AEM CMS plugin is installed and configured on.
- Prerequisites, Version, and AEM User Requirements
- How to run the AEM CMS plugin debugging tooling checks
- Configuration of checks in debugging tooling
- Checks performed with the debugging tooling
Prerequisites, Version, and AEM User Requirements
There are some prerequisites and requirements that have to be in place in order to use this tooling to debug issues with the AEM CMS plugin.
- AEM Admin Access - You will need AEM Admin access to the AEM authoring environment that you are running into issues with the plugin on to utilize the AEM CMS Plugin Debugging Tooling.
- Install and configure the AEM CMS plugin on your CMS authoring environment - You will need to have version 3.0.11 or after of the AEM CMS plugin, which requires Java 11 or after, installed and configured on your AEM CMS authoring environment and you will need to ensure that you are scanning the Publisher pages for the site in the Siteimprove Platform. This debugging tooling should be installed as a part of the AEM CMS plugin starting with version 3.0.11 and versions after that.
Steps to follow if you have not installed and configured the AEM CMS plugin
If you have not already downloaded and installed the plugin you can download the latest version via the download buttons on the AEM CMS Plugin Marketing Site for the corresponding version of AEM that you have installed on your AEM CMS authoring environment: AEM Cloud, AEM version 6.4, or AEM version 6.5.
You will then need to follow the guides listed below to install and then configure the plugin.
General CMS plugin installation and testing guides
For general plugin installation or testing please read over the steps in these articles before going over the steps in the specific AEM CMS plugin installation and configuration guides.
- How to test the Siteimprove CMS Plugins for testing the plugin on a non-production environment that is scanned in the Siteimprove platform prior to installation on a production environment.
- How to install the Siteimprove CMS plugin for installing the plugin on a production instance of your CMS authoring environment for a site scanned in the Siteimprove platform.
AEM CMS plugin specific installation and configuration guides
- For On Prem (non-Cloud) versions of AEM please follow the installation and configuration steps in this AEM Plugin Installation Guide.
- For Cloud versions of AEM please follow this guide How to install CMS Plugin for AEM Cloud to install the plugin and continue to follow steps post installation in this AEM Plugin Installation Guide.
How to run the AEM CMS plugin debugging tooling checks
- To perform the checks you will need to login to the AEM authoring environment that you have the Siteimprove AEM CMS plugin installed on with Admin level credentials for the AEM.
- Then visit {{AEM Host}}/bin/siteimprove/healthcheck into the browser URL bar.
{{AEM Host}} = your AEM CMS authoring site domain.
For example, if the authoring URLs are something like this:
https://adobeaem_us-author.siteimprove.com/sites.html/content/we-retail/us/en/about-us
The author domain would be: https://adobeaem_us-author.siteimprove.com.
Then you would visit the following URL to perform the debugging tooling check:
https://adobeaem_us-author.siteimprove.com/bin/siteimprove/healthcheck
The results should return plain text results in the browser window with results from the checks preformed.
- For the CacheHealthCheck to display results you will need to add some configurations with the next steps to see results from that check.
- Enter {{AEM-host}}/system/console/configMgr/com.siteimprove.aem.plugin.impl.healthcheck.CacheHealthCheck into the browser URL bar while logged into AEM as an Admin for the AEM CMS authoring environment.
{{AEM Host}} = your AEM CMS authoring site domain.
For example, if the authoring URLs are something like this:
https://adobeaem_us-author.siteimprove.com/sites.html/content/we-retail/us/en/about-us
The author domain would be: https://adobeaem_us-author.siteimprove.com
Then you would visit the following URL to configure the check:
https://adobeaem_us-author.siteimprove.com/system/console/configMgr/com.siteimprove.aem.plugin.impl.healthcheck.CacheHealthCheck
- Update the necessary values listed to configure the CacheHealthCheck:
- Host (optional): host to test. By default host will be picked based on Externalizer settings. If there is suspicion that Externalized could be configured improperly or not configured at all - Host should be configured to override Externalizer. It’s important to set Host the same value end-users use to access AEM environment.
- Login + Password: credentials of user, on which behalf check will be conducted.
- Targets: list of endpoints to test. Should be in sync with MarkerFilter.targets. Typically this will be /editor.html or /sites.html, but you can also check under {{AEM-host}}/system/console/configMgr/com.siteimprove.aem.plugin.impl.healthcheck.MarkerFilter like shown below.
- Once the CacheHealthCheck is configured then visit the debugging health check URL again {{AEM-host}}/bin/siteimprove/healthcheck to see results for the debugging tool checks. If the CacheHealthCheck is configured correctly results should be shown for that check and should no longer should show "INFO : Configure check with credentials to enable."
- Once you have configured the CacheHealthCheck and receive results from all of the checks you should be able to save the data returned to a text file or print it to a PDF file to send to the support and development teams at Siteimprove to help to troubleshoot into issues further.
Configuration of checks in debugging tooling
To re-configure checks that are configurable complete the steps below.
- Login to the AEM authoring environment that you have the Siteimprove AEM CMS plugin installed on with Admin level credentials for the AEM if not already logged in.
- Enter {{AEM-host}}/system/console/configMgr/{{service-PID}} into the browser URL bar.
- Update necessary values.
- Select “Save.“
What do I enter for {{service-PID}}?
The PID values are listed under the “Configuration” area for each of the checks listed further down in this article. The CacheHealthCheck is the only check that requires configuration. The other checks shouldn't need to be configured but could potentially be configured if needed.
Checks performed with the debugging tooling
There are several individual checks that are part of the debugging tooling checks. We have listed each of the checks along with details about each check below. The details include what the check results look like, a description of the check, potential fixes that can be determined from the check, and configuration settings for the individual checks.
CacheHealthCheck
Results when not configured
Results when configured
Description
As plugin uses AEM permission model, it’s crucial to avoid caching of moving parts that could be affected by user’s permissions. This check helps to test if there is cache atop of selected set of resources.
Fix
Endpoints providing data based on user permissions shouldn’t be cached so to fix this if the endpoints are cached you will need to remove cache from highlighted endpoints. This would need to be done by the client's development team.
Configuration
NOTE: Requires configuration to function
PID: com.siteimprove.aem.plugin.impl.healthcheck.CacheHealthCheck
To add configurations for this check follow the steps below:
- Login to the AEM authoring environment that you have the Siteimprove AEM CMS plugin installed on with Admin level credentials for the AEM if not already logged in.
- Enter {{AEM-host}}/system/console/configMgr/com.siteimprove.aem.plugin.impl.healthcheck.CacheHealthCheck into the browser URL bar while logged into AEM as an Admin for the AEM CMS authoring environment.
{{AEM Host}} = your AEM CMS authoring site domain.
For example, if the authoring URLs are something like this:
https://adobeaem_us-author.siteimprove.com/sites.html/content/we-retail/us/en/about-us
The author domain would be: https://adobeaem_us-author.siteimprove.com
Then you would would visit the following URL to configure the check:
https://adobeaem_us-author.siteimprove.com/system/console/configMgr/com.siteimprove.aem.plugin.impl.healthcheck.CacheHealthCheck
- Update the necessary values listed:
- Host (optional): host to test. By default host will be picked based on Externalizer settings. If there is suspicion that Externalized could be configured improperly or not configured at all - Host should be configured to override Externalizer. It’s important to set Host the same value end-users use to access AEM environment.
- Login + Password: credentials of user, on which behalf check will be conducted.
- Targets: list of endpoints to test. Should be in sync with MarkerFilter.targets. Typically this will be /editor.html or /sites.html, but you can also check under {{AEM-host}}/system/console/configMgr/com.siteimprove.aem.plugin.impl.healthcheck.MarkerFilter like shown below.
- If the CacheHealthCheck if it is configured correctly results should be shown for that check under the full debugging tooling check under {{AEM-host}}/bin/siteimprove/healthcheck and no longer should show "INFO : Configure check with credentials to enable."
UserPermissionsHealthCheck
Description
User should have access to certain paths when using plugin. Check lists all paths in question, and all users with a report if each user’s permissions are enough to use plugin or list of issues, if not.
Fix
If a user should have access to the plugin, but they don't you will need to add the user to the siteimprove-users group in the AEM environment. This would be done by whomever manages user permissions in AEM to the CMS environment.
Configuration
PID: com.siteimprove.aem.plugin.impl.healthcheck.UserPermissionsHealthCheck
Paths: set of paths to test permissions against
OverrideHealthCheck
Description
As per Adobe recommendations, one should apply custom changes on AEM with path as detailed as possible, to not to override possible 3rd party changes. However, it’s just a recommendation, and not everyone sticks to it. Current check scans packages on the AEM instance, trying to determine, if there is a risk that something could override plugin paths and obviously broke it.
WARNING: Check is purely experimental, and all hints should be considered, not necessarily fixed.
Fix
Update artifact in question to not to override generic path, use precise path or different merge options instead. This would need to be done by the client's development team.
Configuration
PID: com.siteimprove.aem.plugin.impl.healthcheck.OverrideHealthCheck
Ignored: set of package groups which shouldn’t be reported (for the most cases, it’s Adobe service packages which do not pose risks to our functionality)
IntegrityHealthCheck
Example check result on On Prem version of AEM
Example of check result on Cloud Version of AEM
Description
Our plugin comes with set of AEM customizations to improve user experience. Each of such customizations are either a node or a property in the AEM repository. In case node or property removed or modified for any reason - plugin could work not as expected. Current check verifies plugin customizations inside of repository (against currently-installed plugin package).
WARNING: Check uses Siteimprove plugin package to check repository integrity, but AEMaaCS doesn’t store mutable packages. To make that check work - upload package to the instance manually (AEM won’t allow you to install it, there is another procedure for installation - but it isn’t required. Just upload).
Fix
Re-install plugin package.
Configuration
PID: com.siteimprove.aem.plugin.impl.healthcheck.IntegrityHealthCheck
OK Logging: should check log anything that is verified and correct? Useful only for check debugging purposes, not for the client.
InfoHealthCheck
Description
This check provides some debugging information - plugin OSGI configuration, AEM and Java versions, plugin Cloud configurations and their applications.
Configuration
PID: com.siteimprove.aem.plugin.impl.healthcheck.InfoHealthCheck
Siteimprove Service Config: This checks against the Siteimprove Service Configuration.
NetworkHealthCheck
Description
For some reason, requests from the AEM to Siteimprove could be blocked (a lot of reasons - NATs, proxys, firewalls, wire-chewing hamsters). The check reaches out to a set of endpoints on behalf of the server (using GET method), checking their accessibility.
Fix
If something is blocking requests the ideal fix would be to unblock what is blocked but the fix could differ depending on the cause.
Configuration
PID: com.siteimprove.aem.plugin.impl.healthcheck.NetworkHealthCheck
Paths: set of URLs to check
Did you find it helpful? Yes No
Send feedback