AEM Tutorials for Beginners: Troubleshooting

Showing posts with label Troubleshooting. Show all posts

February 23, 2022
Estimated Post Reading Time ~

Is there any way to get a sly element to render inside a script element?

Question: Is there any way to get a <sly> element to render inside a <script> element?

URL: https://experienceleaguecommunities.adobe.com/t5/adobe-experience-manager/lt-sly-gt-element-in-lt-script-gt-tag-not-evaluating/m-p/260965

I have a problem similar to this one: Sightly in <script> tag not evaluating?

In that thread, the problem was that Sightly expressions inside a script element were not being rendered, and the solution was to add @ context = 'scriptString' to the expression.

My situation is a slightly different: Inside my HTML script element, I want to put a Sightly element:

<script id="availabilitiesTemplate" type="text/template" >
   <sly data-sly-include="availabilitiesTemplate.html"></sly>
</script>

But the included file is not rendered to the output.

I suspect this is also a context problem, but I can't find any docs on setting the context on a <sly> element, and none of my experiments have worked. I've tried setting the context:

<script id="availabilitiesTemplate" type="text/template" >
   <sly data-sly-include="${ availabilitiesTemplate.html @ context = 'scriptString'        }"></sly>
</script>

I've also tried assigning the template with a data-sly-use expression:
<sly data-sly-use.avail="availabilitiesTemplate.html"></sly>
<script id="availabilitiesTemplate" type="text/template" >
   ${avail @ context='scriptString'}
</script>

Neither of these approaches works either; in all cases the output is

<script id="availabilitiesTemplate" type="text/template" >
</script>

Solution:
You can try with handlebar use this line to include resource in script.
<script id="my-handlebar-template" type="text/x-handlebars-template" data-sly-include="handlebar.html">

</script>

Without separating this example into two distinct files, the expression of the example should have been written as follows:

${properties.jcr:title @ context='text'}

component.html
<script id="my-handlebar-template" type="text/x-handlebars-template" data-sly-include="handlebar.html">

</script>

handlebar.html
<body>
<p>${properties.jcr:title}</p>
</body>

Source:
https://gist.github.com/gabrielwalt/0f949175a5cc068b44a6

By aem4beginner

July 1, 2021
Estimated Post Reading Time ~

Groovy Script to update components with dialog property

/* this script is to update the Booking widget component "summarybarDisabled" and "slideOutEnabled"*/

def path = "/content/we-retail"
def pageCount = 0;
def summarybarDisabledProperty = "summarybarDisabled";
def slideOutEnabledProperty = "slideOutEnabled";

getPage(path).recurse { page ->
def content = page.node
def pagePath = page.path;

content?.recurse { node ->
def componentNode = node.get("sling:resourceType")
if(componentNode == "we-retail/components/content/image"){
def newNodePathtemp = node.path;

if(node.get(summarybarDisabledProperty)){
def summaryBarStr = getPropertyValueAsStr(node, summarybarDisabledProperty);

if (summaryBarStr == "true") {
nodePath = node.path;
if (nodePath.contains("slideouthero/findhotel")) {
//Inside Slide Out Hero Component
println page.path;

//Remove and set the property, uncomment this block to save the changes
/*
node.getProperty(summarybarDisabledProperty).remove();
node.set(slideOutEnabledProperty, "{Boolean}true");
session.save();
*/

pageCount++;

} else {
//Do not do anything
}

} else {
//println summaryBarStr +" " +page.path;
}

}
}
}
}

println "Total number pages : "+pageCount

def getPropertyValueAsStr(def content, def propertyName){
def propertyValStr = "";
if(content.get(propertyName)){
def propertyVal = content.getProperty(propertyName);
if(propertyVal){
if(!propertyVal.isMultiple()){
propertyValStr = propertyVal.getString();
}else{
values = propertyVal.getValues();
values.each {
if(propertyValStr.length() > 0){
propertyValStr = propertyValStr + " ; " + "$it";
}else{
propertyValStr = "$it";
}
}
}
}
}
return propertyValStr;
}

By aem4beginner

May 28, 2021
Estimated Post Reading Time ~

Problem accessing /system/console

HTTP ERROR: 403
Problem accessing /system/console. Reason:

Forbidden
Powered by Jetty://

Solution:
Navigate to /system/console/configMgr

and then search with "Apache Sling Web Console Security Provider"

Then add your user or your required users group so that you could resolve this issue.

By aem4beginner

Enabling CRXDE Lite in AEM

In order to ensure that AEM installations are as secure as possible, the security checklist recommends disabling WebDAV in production environments.

However, CRXDE Lite depends on the org.apache.sling.jcr.davex bundle to function properly, so disabling WebDAV will effectively disable CRXDE Lite as well.

When this happens, browsing to https://serveraddress:4502/crx/de/index.jsp will display an empty root node, and all HTTP requests to CRXDE Lite resources will fail:

404 Resource at '/crx/server/crx.default/jcr:root/.1.json' not found: No resource found

While this recommendation is intended to reduce attack surfaces as much as possible, system administrators might sometimes need access to CRXDE Lite in order to browse content or debug issues on production instances.

If disabled, you can turn CRXDE Lite on by following the below procedure:

Go to the OSGi Components console at http://localhost:4502/system/console/components
Search for the following component:

org.apache.sling.jcr.davex.impl.servlets.SlingDavExServlet

Click the wrench icon next to it in order to see its configuration options:

4. Create the following configuration:

Root path: /crx/server
Tick the box under Use absolute URIs.

5. When finished using CRXDE Lite, make sure you disable WebDAV again.

You can also enable CRXDE Lite via cURL, by running this command:

curl -u admin:admin -F "jcr:primaryType=sling:OsgiConfig" -F "alias=/crx/server" -F "dav.create-absolute-uri=true" -F "dav.create-absolute-uri@TypeHint=Boolean" http://localhost:4502/apps/system/config/org.apache.sling.jcr.davex.impl.servlets.SlingDavExServlet

By aem4beginner

March 22, 2021
Estimated Post Reading Time ~

How to Debug/ Troubleshoot Sling Context Aware Configuration AEM

If we are using Sling Context-Aware configurations in AEM and something went wrong it's difficult to debug/know from where these values or pulling. We know this in the AEM Web console.

After open AEM Web console click on the sling tab, you will find the "Context-Aware Configuration" option

After Navigate Context-Aware Configuration web console page you will see a form. You can enter the "Content Path" and "Config name" which you want to debug and click on resolve. if you are debugging a collection config check the checkbox "Resouce Collection"

Note: if "cq:conf" property set to your jcr:content node of page sometimes it will read configurations for the path. So keep an eye on "cq:conf" and "sling:configRef" properties.

To know how to develop with Sling context configurations refer to my post Sling Context Aware Configuration AEM 6.5 Examples.

By aem4beginner

February 2, 2021
Estimated Post Reading Time ~

Efficiently load JavaScript with defer and async

When loading a script on an HTML page, you need to be careful not to harm the loading performance of the page. Depending on where and how you add your scripts to an HTML page will influence the loading time

When loading a script on an HTML page, you need to be careful not to harm the loading performance of the page.

A script is traditionally included in the page in this way:
<script src="script.js"></script>

whenever the HTML parser finds this line, a request will be made to fetch the script, and the script is executed.

Once this process is done, the parsing can resume, and the rest of the HTML can be analyzed.

As you can imagine, this operation can have a huge impact on the loading time of the page.

If the script takes a little longer to load than expected, for example, if the network is a bit slow or if you’re on a mobile device and the connection is a bit sloppy, the visitor will likely see a blank page until the script is loaded and executed.

The position matters
When you first learn HTML, you’re told script tags live in the <head> tag:
<html>

<head>

<title>Title</title>

<script src="script.js"></script>

</head>

<body>

...

</body>

</html>

As I told you earlier, when the parser finds this line, it goes to fetch the script and executes it. Then, after it’s done with this task, it goes on to parse the body.

This is bad because there is a lot of delays introduced. A very common solution to this issue is to put the script tag at the bottom of the page, just before the closing </body> tag.

In doing so, the script is loaded and executed after all the page is already parsed and loaded, which is a huge improvement over the head alternative.

This is the best thing you can do if you need to support older browsers that do not support two relatively recent features of HTML: async and defer.

Async and Defer
Both async and defer are boolean attributes. Their usage is similar:

<script async src="script.js"></script>

<script defer src="script.js"></script>

if you specify both, async takes precedence on modern browsers, while older browsers that support defer but not async will fallback to defer.

For the support table, check caniuse.com for async https://caniuse.com/#feat=script-async and for defer https://caniuse.com/#feat=script-defer

These attributes only make sense when using the script in the head portion of the page, and they are useless if you put the script in the body footer like we saw above.

Performance comparison
No, defer or async, in the head
Here’s how a page loads a script without either defer or async, put in the head portion of the page:

The parsing is paused until the script is fetched, and executed. Once this is done, parsing resumes.

No, defer or async, in the body
Here’s how a page loads a script without defer or async, but at the end of the body tag, just before it closes:

The parsing is done without any pauses, and when it finishes, the script is fetched and executed. Parsing is done before the script is even downloaded, so the page appears to the user way before the previous example.

With async, in the head
Here’s how a page loads a script with async, put in the head tag:

The script is fetched asynchronously, and when it’s ready the HTML parsing is paused to execute the script, then it’s resumed.

With defer, in the head
Here’s how a page loads a script with defer, put in the head tag:

The script is fetched asynchronously, and it’s executed only after the HTML parsing is done.

Parsing finishes just like when we put the script at the end of the body tag, but overall the script execution finishes well before because the script has been downloaded in parallel with the HTML parsing.

So this is the winning solution in terms of speed 🏆

Blocking parsing
async blocks the parsing of the page while defer does not.

Blocking rendering
Neither async nor defer guaranteeing anything on blocking rendering. This is up to you and your script (for example, making sure your scripts run after the onLoad) event.

domInteractive
Scripts marked defer are executed right after the domInteractive event, which happens after the HTML is loaded, parsed and the DOM is built.

CSS and images at this point are still to be parsed and loaded.

Once this is done, the browser will emit the domComplete event, and then onLoad.

domInteractive is important because its timing is recognized as a measure of perceived loading speed. See the MDN for more.

Keeping things in order
Another case pro defer: scripts marked async are executed in casual order when they become available. Scripts marked defer are executed (after parsing completes) in the order in which they are defined in the markup.

Just tell me the best way
The best thing to do to speed up your page loading when using scripts is to put them in the head, and add a defer attribute to your script tag:
<script defer src="script.js"></script>

This is the scenario that triggers the faster domInteractive event.

Considering the pros of defer is seems a better choice over async in a variety of scenarios.

Unless you are fine with delaying the first render of the page, make sure that when the page is parsed the JavaScript you want is already executed.

Download my free JavaScript Beginner's Handbook

More browser tutorials:

Source:

https://flaviocopes.com/javascript-async-defer/

By aem4beginner

January 23, 2021
Estimated Post Reading Time ~

How can I list only project specific workflow in dropdown list of "start workflow"

I am using AEM 6.4 want to list only project specific workflow in drop down list of "start workflow" and hide the out of the box workflows. Please suggest the best possible approach.

Solution:

Just add Workflow: System tag in the page properties of the OOTB workflow models. So it will hide all the OOTBS workflows from the drop-down list of Start Workflow option and it will only show the workflow models which do not contains workflow:System tag.

http://localhost:4502/libs/cq/workflow/admin/console/content/models.html

Here is the official documentation from Adobe in case if you want more on this https://helpx.adobe.com/in/experience-manager/kb/hide-workflow-models-start-workflow-list.html

By aem4beginner

Unable to create content fragment model in AEM 6.5 throws server error

I'm unable to create content fragment model in one of our environments even when i'm logged in with admin. It throws server error.
Attaching screenshot and stack trace in the comments below.

22.05.2020 04:23:03.064 *ERROR* [10.30.60.206 [1590139383053] POST /mnt/overlay/dam/cfm/models/console/content/createmodelwizard.html/conf/dam/cfm/models/console/content/createmodelwizard/_jcr_content HTTP/1.1] org.apache.sling.engine.impl.SlingRequestProcessorImpl service: Uncaught SlingException

java.lang.NullPointerException: null

at org.apache.jsp.apps.cq.Page.POST_jsp._jspService(POST_jsp.java:208)

at org.apache.sling.scripting.jsp.jasper.runtime.HttpJspBase.service(HttpJspBase.java:70) [org.apache.sling.scripting.jsp:2.3.6]

at javax.servlet.http.HttpServlet.service(HttpServlet.java:725) [org.apache.felix.http.servlet-api:1.1.2]

at org.apache.sling.scripting.jsp.jasper.servlet.JspServletWrapper.service(JspServletWrapper.java:502) [org.apache.sling.scripting.jsp:2.3.6]

at org.apache.sling.scripting.jsp.jasper.servlet.JspServletWrapper.service(JspServletWrapper.java:449) [org.apache.sling.scripting.jsp:2.3.6]

at org.apache.sling.scripting.jsp.JspScriptEngineFactory.callJsp(JspScriptEngineFactory.java:339) [org.apache.sling.scripting.jsp:2.3.6]

Troubleshoot
You need to do two things
1) If you have installed the Service pack recently-There might possibilities that you core package affected and its not Active state. Please verify it and try to restart the AEM.

2) If the issue persist, then uninstall the SP and install it again with other browser except chrome and see all bundles are getting Active state or not.

Once your all bundles are active then you good to go.

By aem4beginner

How to hide the workflow models for certain groups or a user in AEM 6.5?

Question:

Any Idea How to hide the workflow models for certain groups or a user in AEM 6.5?
runtime workflows are updated in /var/workflow/models,
In useradmin console I am unable to set permission to specific workflow model because workflowmodel is in /var/workflow/model is xml file and NOT having
mixnTypes: rep:AccessContrallable property.
Adding the system tag to workflowmodel hides the workflow model for all users but to specific group

my use case is I want hide workflow name in the dropdown option in start workflow when specific group members trigger workflow

Solution:

1. creating custom workflow under /conf/global/setting/workflow/model/projectname/workflowmodel(projectname is sling:folder with mixinType: rep:AccessControllable

2. create workflow model above folder and sync

3. created runtime workflow under /var/workflow/model/projectname/workflowmodel

4. goto useradmin console update permission specific group(allow/deny) to workflowmodel in /var/workflow/model/projectname/workflowmodel

By aem4beginner

What is the best practise/Approach for upgrade to AEM 6.5 from AEM 6.3 SP2

Solution:

The best approach for upgrade is in-place upgrade just like you said.

Please review the all the links of doc - > Upgrading to AEM 6.5
The main upgrade steps are mentioned here Performing an In-Place Upgrade

Note:
In addition to that its good to check the following document:
Post Upgrade Checks and Troubleshooting

By aem4beginner

January 18, 2021
Estimated Post Reading Time ~

What is the alternative method to download HeapDump log files?

How to Download generate and download Heapdumps?

In order to generate the Heapdumps please navigate to below URL

http://localhost:4502/system/console/memoryusage

and click on the "Dump Heap", once it is generated please download by click on the zipped file

With respect to the alternative method to download the Heapdump logs

We can use the below-mentioned curl commands

curl -O -u admin:admin http://localhost:6520/system/console/memoryusage/heap.1610826599418.hprof.zip

But it stops after 200MBs then I try to resume:

curl -C - -O -u admin:admin http://localhost:6520/system/console/memoryusage/heap.1610826599418.hprof.zip

By aem4beginner

AEM 6.5 Upgrade to 6.5.7 CFP Causing Unresponsive Instances

Question:

AEM 6.5 Upgrade to 6.5.7 CFP Causing Unresponsive Instances

We've recently upgraded AEM from 6.5.1 to 6.5.7.

Since we've upgraded from SP 6.5.1 to 6.5.7 we've noticed really poor performance, author and publish instance needing restarts nearly every 2-3 days because of becoming unresponsive. No heap dumps or OutOfMemory exceptions.

Logs:

17.01.2021 09:20:02.286 *INFO* [10.142.72.17 [1610900402282] GET /mnt/overlay/granite/ui/content/shell/header/actions/pulse.data.json HTTP/1.1] org.apache.sling.engine.impl.SlingRequestProcessorImpl service: Resource /mnt/overlay/granite/ui/content/shell/header/actions/pulse.data.json not found

Solution:

Checking the thread dumps and further researching internally, It seems you are running into a known issue(CQ-4312194) with SP7 where numerous threads get blocked due to a Timer with the Component Registry (org.apache.felix.scr.impl.ComponentRegistry). This causes the instance to become unresponsive.

Follow the steps below to resolve the issue:
- Install the attached hotfix package (Hotfix-CQ-4312194-FELIX-6252-1.0.zip)
- This will trigger a restart of a couple of bundles. So, need to wait 3-5 mins
- Go to <host>:<port>/system/console and make sure the "org.apache.felix.scr" version is updated to 2.1.20

By aem4beginner

January 11, 2021
Estimated Post Reading Time ~

Touch UI RTE Dialog Color Picker Plugin - Throwing Handlebars.compile error in XF pages

Question:

We are using the Color Picker plugin (Refer ) developed and provided by Sreekanth. The plugin works fine in our pages, but while using the color-picker in the XF pages, it is not loading in the RTE and we are getting Handlebars.compile is not a function issue in the console.

Solution:

The color-picker doesn't work in Experience Fragment (XF) pages since the Handlebar js is not available there and underscore (clientlibs added as a dependency in the picker) doesn't have Handlebar.compile module. I was trying with handlebars as dependency all the time after reading it somewhere, but after some debugging, I could figure out that the dependency which had handlebar in AEM is cq.handlebars.

So anybody facing Handlebars.compile is not a function issue in the future, please add cq.handlebars as an additional dependency to your clientlibs

Source:

https://experienceleaguecommunities.adobe.com/t5/adobe-experience-manager/aem-65-touch-ui-rte-rich-text-editor-dialog-color-picker-plugin/qaq-p/392705/comment-id/84334#

By aem4beginner

January 6, 2021
Estimated Post Reading Time ~

"Handlebars.compile is not a function" reported after upgrading from AEM 6.5.2 to AEM 6.5.6

I have recently upgraded from AEM 6.5 SP 2 to AEM 6.5 SP 6.

Since upgrading, the Select Font button on Rich Text Content Fragment editor has stopped working, and I am seeing the error "Handlebars.compile is not a function" in console output.

Solution:
It looks like AEM 6.5 SP 6 may have updated the handlebars version within /libs/clientlibs/social/thirdparty/handlebars. What you need to do is find out which version AEM 6.5 SP 2 uses, and Override the client library for the correct version. The clientlib.category should be cq.handlebars.

By aem4beginner

Upgrade from 6.3 to 6.5

Adobe documentation captures all the scenarios for the AEM upgrade. Please refer to it at [1]. On a high level, the changes are

1. Upgrading the AEM instance - you can do either an in-place upgrade or fresh install approach based on your content size and
2. Upgrade your artifacts by compiling against 6.5 uber jar.
3. Test and fix any issues due to deprecated features/overlaid capabilities change.
4. From 6.4, as part of the sustainable upgrades process, there is a repository restructuring that can be done (not mandatory). Refer to it at [2]
5. Process on how to roll out the changes to production.

If this is hard, adobe offers a backward compatibility mode from 6.3 with which you can run a 6.3 AEM artifact on a 6.5 instance. Read more at [3]

Pattern detector is a mechanism provided by Adobe to easy identification of possible problems that will come up during upgrade by validating against deprecated features and overlays. Refer more at [4]

AEM 6.5 is compatible with Java 8. Refer to [5]

[1] - https://docs.adobe.com/content/help/en/experience-manager-65/deploying/upgrading/upgrade.html
[2] - https://docs.adobe.com/content/help/en/experience-manager-65/deploying/restructuring/repository-rest...
[3] - https://docs.adobe.com/content/help/en/experience-manager-65/deploying/upgrading/backward-compatibil...
[4] - https://docs.adobe.com/content/help/en/experience-manager-65/deploying/upgrading/pattern-detector.ht...
[5] - https://docs.adobe.com/content/help/en/experience-manager-65/deploying/introduction/technical-requir...

By aem4beginner

Issues with AEM Upgrade from 6.2 to 6.3

We are upgrading our AEM from version 6.2 to 6.3. we are facing issues when we run pre-upgrade-tasks from the JMX console.

below are the steps we followed and the issues faced.
1. Took the backup of the complete instance.

2. downloaded the pre-upgrade-tasks-content-cq62-1.2.4.zip package from package share and installed.

3. we ran runAllPreUpgradeTasks() from the JMX Web Console prechecks.

4. when we ran the above we see the below information in the logs

Startup mode is RESTART, nothing to do

/var/upgrade/status/preUpgradeBackup.force does not exist, backup will not be forced

UPGRADE NOT NEEDED - StartupMode is RESTART

5. to run the instance in the upgrade mode we restarted the instance with the below command

java -jar -Xmx3072m -Dorg.apache.sling.launchpad.startupmode=update aem-author-p4502.jar

6. when we restarted the instance in the update run mode and ran runAllPreUpgradeTasks() from the JMX Web Console, we could see in the logs it is preparing for the upgrade with the below errors:

1. com.day.cq.compat.codeupgrade.impl.mergebackup.CqMergeBackupUpgrade Exception in CqMergeBackupUpgrade.run()

javax.jcr.AccessDeniedException: OakAccess0000: Access denied

2. and we see in the pre-upgrade popup msg 'disabling replication agents' and the file preUpgradeHCStatus.properties have below content

areAllPreUpgradeHealthChecksOK=false
Maintenance\ Task\ WorkflowPurgeTask=OK
Maintenance\ Task\ RevisionCleanupTask=OK
Modified\ Deprecated\ Indexes=OK
Maintenance\ Task\ com.day.cq.audit.impl.AuditLogMaintenanceTask=OK

Replication\ Agents\ Disabled=HEALTH_CHECK_ERROR

Couldn't figure out the root cause of the issue. Need help and the steps to be followed with an upgrade.

Solution:

6.3 includes pre-upgrade checks that need to pass for the upgrade to complete successfully.

You need to disable all the replication agents on your system and make sure the audit log maintenance is configured correctly (“Audit Log Purge Scheduler” in ConfigMgr) so it could be executed pre-upgrade.

By aem4beginner

Pre-Upgrade Maintenance Tasks

Before beginning your upgrade, it is important to follow these maintenance tasks to ensure that the system is ready and can be rolled back should an issue occur:

Ensure Sufficient Disk Space
When executing the upgrade, in addition to the content and code upgrade activities, a repository migration will need to be performed. The migration will create a copy of the repository in the new Segment Tar format. As a result, you will need enough disk space to retain a second, potentially larger, version of your repository.

Fully Back Up AEM
AEM should be fully backed up before beginning the upgrade. Make sure to back up your repository, application installation, datastore, and Mongo instances if applicable. For more information on backing up and restoring an AEM instance, see Backup and Restore.

Back Up Changes to /etc
The upgrade process does a good job of maintaining and merging existing content and configurations from under the /apps and /libs paths in the repository. For changes made to the /etc path, including Context Hub configurations, it is often necessary to re-apply these changes after the upgrade. While the upgrade will make a backup copy of any changes that it cannot merge under /var, we recommend backing up these changes manually before beginning the upgrade.

Generate The quickstart.properties File
When starting AEM from the jar file, a quickstart.properties file will be generated under crx-quickstart/conf. If AEM has only been started with the start script in the past, this file will not be present and the upgrade will fail. Make sure to check for the existence of this file and restart AEM from the jar file if it is not present.

Configure Workflow and Audit Log Purging
The WorkflowPurgeTask and com.day.cq.audit.impl.AuditLogMaintenanceTask tasks require separate OSGi configurations and will not work without them. If they fail during pre-upgrade task execution, missing configurations is the most likely reason. Therefore, make sure to add OSGi configurations for these tasks or remove them altogether from the pre-upgrade optimization tasks list if you do not wish to run them. Documentation for configuring workflow purging tasks can be found at Administering Workflow Instances and audit log maintenance task configuration can be found at Audit Log Maintenance in AEM 6.

For workflow and audit log purging on CQ 5.6 as well as audit log purging on AEM 6.0, see Purge workflow and audit nodes.

Install, Configure, and Run The Pre-Upgrade Tasks
Because of the level of customization AEM allows, environments usually do not adhere to a uniform way of performing upgrades. This makes creating a standardized procedure for upgrades a difficult process.

In previous versions, it was also difficult for AEM upgrades that were stopped or that have failed to be safely resumed. This led to situations where restarting the full upgrade procedure was necessary or where defective upgrades were carried out without triggering any warnings.

In order to address these issues, Adobe has added several enhancements to the upgrade process, making it more resilient and user friendly. Pre-upgrade maintenance tasks that before had to be performed manually are being optimized and automated. Also, post-upgrade reports have been added so that the process can be fully scrutinized in the hope that any issues are found more easily.

Pre-upgrade maintenance tasks are currently spread over various interfaces which are partially or completely performed manually. The pre-upgrade maintenance optimization introduced in AEM 6.3 enables a unified way to trigger these tasks and be able to inspect their result on demand.

All tasks included in the pre-upgrade optimization step are compatible with all versions from AEM 6.0 onwards.

How to Set It Up
In AEM 6.3 and later, the pre-upgrade maintenance optimization tasks come included in the quickstart jar. If you are upgrading from an older version of AEM 6, they are made available through separate packages that you can download from the Package Manager. You can find the packages at these locations:

How to Use It

The PreUpgradeTasksMBean OSGI component comes preconfigured with a list of pre-upgrade maintenance tasks that can be run all at once. You can configure the tasks by following the below procedure:

Go to the Web Console by browsing to https://serveraddress:serverport/system/console/configMgr

Search for “preupgradetasks”, then click on the first matching component. The full name of the component is com.adobe.aem.upgrade.prechecks.mbean.impl.PreUpgradeTasksMBeanImpl

Modify the list of maintenance tasks that need to run as shown below:

The task list differs depending on the run mode that is being used to start the instance. Below is a description of the run mode each maintenance task is designed for.

Task Run Mode Notes
`TarIndexMergeTask` crx2
`DataStoreGarbageCollectionTask` crx2 Will run mark and sweep. For shared datastores, remove this step and run
manually or properly prepare instances before executing.
`ConsistencyCheckTask` crx2
`WorkflowPurgeTask` crx2/crx3 Must configure the Adobe Granite Workflow Purge Configuration OSGi before running.
`GenerateBundlesListFileTask` crx2/crx3
`RevisionCleanupTask` crx3 For TarMK instances on AEM 6.0 to 6.2, manually run Offline Revision Cleanup instead.
`com.day.cq.audit.impl.AuditLogMaintenanceTask` crx3 Must configure the Audit Log Purge Scheduler OSGi configuration before running.

CAUTION
DataStoreGarbageCollectionTask is calling a Datastore Garbage Collection operation with the mark and sweep phase if used. For deployments that use a shared datastore make sure to either reconfigure it or properly or prepare the instance to avoid deletion of items referenced by another instance. This might require running the mark phase manually on all instances before triggering this pre-upgrade task.

Default Configuration of the Pre-Upgrade Health Checks
The PreUpgradeTasksMBeanImpl OSGI component comes pre-configured with a list of pre-upgrade health check tags to execute when the runAllPreUpgradeHealthChecks method is called:

system - the tag used by the granite maintenance health checks

pre-upgrade - this is a custom tag that could be added to all the health checks that you can set to run before an upgrade

The list is editable. You can use the plus (+) and minus (-) buttons besides the tags to add more custom tags, or remove the default ones.

MBean Methods
The managed bean functionality can be accessed using the JMX Console.

You can access the MBeans by:
Going to the JMX Console at https://serveraddress:serverport/system/console/jmx

Search for PreUpgradeTasks and click the result

Select any method from the Operations section and select Invoke in the following window.

Below is a list of all the available methods that the PreUpgradeTasksMBeanImpl exposes:

Method Name	Type	Description
`getAvailablePreUpgradeTasksNames()`	INFO	Displays the list of available pre-upgrade maintenance tasks names.
`getAvailablePreUpgradeHealthChecksTagNames()`	INFO	Displays the list of pre-upgrade health checks tag names.
`runAllPreUpgradeTasks()`	ACTION	Runs all the pre-upgrade maintenance tasks in the list.
`runPreUpgradeTask(preUpgradeTaskName)`	ACTION	Runs the pre-upgrade maintenance task with the name given as the parameter.
`isRunAllPreUpgradeTaskRunning()`	ACTION_INFO	Checks if the `runAllPreUpgradeTasksmaintenance` task is currently running.
`getAnyPreUpgradeTaskRunning()`	ACTION_INFO	Checks if any pre-upgrade maintenance task is currently running and returns an array containing the names of currently running tasks.
`getPreUpgradeTaskLastRunTime(preUpgradeTaskName)`	ACTION	Displays the exact running time of the pre-upgrade maintenance task with the name given as the parameter.
`getPreUpgradeTaskLastRunState(preUpgradeTaskName)`	ACTION	Displays the last running state of the pre-upgrade maintenance task with the name given as the parameter.
`runAllPreUpgradeHealthChecks(shutDownOnSuccess)`	ACTION	Runs all the pre-upgrade health checks and saves their status in a file named `preUpgradeHCStatus.properties` that is located in the sling home path. If the `shutDownOnSuccess` parameter is set to `true`, the AEM instance will be shut down, but only if all the pre-upgrade health checks have an OK status. The properties file will be used as a precondition for any future upgrade and the upgrade process will be stopped if the pre-upgrade health check execution failed. If you want to ignore the result of the pre-upgrade health checks and launch the upgrade anyway, you can delete the file.
`detectUsageOfUnavailableAPI(aemVersion)`	ACTION	Lists all the imported packages that will no longer be satisfied when upgrading to the specified AEM version. The target AEM version must be given as parameter.

NOTE
The MBean methods can be invoked via:
The JMX Console
Any external application that connects to JMX
cURL

Disable Custom Login Modules
NOTE
This step is only required if you are upgrading from an AEM 5 version. It can be skipped entirely for upgrades from older AEM 6 versions.

The way custom LoginModules are configured for authentication at the repository level has fundamentally changed in Apache Oak.

In AEM versions that used CRX2 configuration was placed in the repository.xml file, while from AEM 6 onwards it is done in the Apache Felix JAAS Configuration Factory service via the Web Console.

Therefore, any existing configurations will have to be disabled and re-created for Apache Oak after the upgrade.

To disable the custom modules defined in the JAAS configuration of repository.xml, you need to modify the configuration to make use of default LoginModule, as in this example:

<Security >
             ....
          <!--
                 Use LoginModule authenticating against repository itself
                 -->
                 <LoginModule class = "com.day.crx.core.CRXLoginModule" >
                     <param name = "anonymousId" value = "anonymous" />
                     <param name = "adminId" value ="admin" />
                     <param name = "disableNTLMAuth" value = "true" />
                     <param name = "tokenExpiration" value = "43200000" />
                     <!-- param name="trust_credentials_attribute" value="d5b9167e95dad6e7d3b5d6fa8df48af8"/
                -->
                 </LoginModule >
         </ Security>

NOTE
For more information, see Authentication with the External Login Module.
For an example of LoginModule configuration in AEM 6, see Configuring LDAP with AEM 6.

Remove Updates From The /install Directory

NOTE
Only remove packages from the crx-quickstart/install directory AFTER shutting down the AEM instance. This will be one of the last steps before starting the in-place upgrade procedure.

Remove any service packs, feature packs or hotfixes that have been deployed through the crx-quickstart/install directory on the local file system. This will prevent the inadvertent installation of old hotfixes and service packs on top of the new AEM version after the update has completed.

Stop Any Cold Standby Instances
If using TarMK cold standby, stop any cold standby instances. These will guarantee an efficient way to come back online in case of issues in the upgrade. After the upgrade has completed successfully, the cold standby instances will need to be rebuilt from the upgraded primary instances.

Disable Custom Scheduled Jobs
Disable any OSGi scheduled jobs that are included in your application code.

Execute Offline Revision Cleanup

NOTE
This step is only necessary for TarMK installations

If using TarMK, you should execute Offline Revision Cleanup before upgrading. This will make the repository migration step and subsequent upgrade tasks execute much faster and will help to ensure that Online Revision Cleanup can execute successfully after the upgrade has completed. For information on running Offline Revision Cleanup, see Performing Offline Revision Cleanup.

Execute Datastore Garbage Collection
NOTE
This step is only necessary for instances running crx3

After running revision cleanup on CRX3 instances, you should run Datastore Garbage Collection to remove any unreferenced blobs in the data store. For instructions, see the documentation on Data Store Garbage Collection.

Upgrade the Database Schema If Needed
Usually, the underlying Apache Oak stack AEM uses for persistence will take care of upgrading the database schema if needed.

However, cases might arise when the schema cannot be upgraded automatically. These are mostly high security environments where the database is running under a user with very limited priviledges. If this happens, AEM will continue to use the old schema.

In order to prevent this from happening, you need to upgrade the schema by following the below procedure:

Shut down the AEM instance that needs to be upgraded.
Upgrade the database schema. Please consult the documentation for your database type in order to see what is the tooling you need to use in order to achieve this.

For more information on how Oak handles schema upgrades, see this page on the Apache website.

Proceed with upgrading AEM.
Delete Users that Might Hinder the Upgrade

NOTE
This pre-upgrade maintenance task is only necessary if:
You are upgrading from AEM versions older than AEM 6.3
You encounter any of the errors mentioned below during the upgrade.

There are exceptional cases when service users might end up in an older AEM versions being improperly tagged as regular users.

If this happens, the upgrade will fail with a message like this one:ERROR [Apache Sling Repository Startup Thread] com.adobe.granite.repository.impl.SlingRepositoryManager Exception in a SlingRepositoryInitializer, SlingRepository service registration aborted java.lang.RuntimeException: Unable to create service user [communities-utility-reader]:java.lang.RuntimeException: Existing user communities-utility-reader is not a service user.

In order to work around this issue, make sure you do the following:

Detach the instance from production traffic
Create a backup of the user(s) causing the problem. You can do this via Package Manager. For more information, see How to Work with Packages.
Delete the user(s) causing the problem. Below is a list of users that might fall under this category:

dynamic-media-replication
communities-ugc-writer
communities-utility-reader
communities-user-admin
oauthservice
sling-scripting

Rotate Log Files
We recommend archiving your current log files before beginning your upgrade. This will make it easier to monitor and scan your log files during and after the upgrade to identify and resolve any issues that may occur.

By aem4beginner

Task	Run Mode	Notes
`TarIndexMergeTask`	crx2
`DataStoreGarbageCollectionTask`	crx2	Will run mark and sweep. For shared datastores, remove this step and run manually or properly prepare instances before executing.
`ConsistencyCheckTask`	crx2
`WorkflowPurgeTask`	crx2/crx3	Must configure the Adobe Granite Workflow Purge Configuration OSGi before running.
`GenerateBundlesListFileTask`	crx2/crx3
`RevisionCleanupTask`	crx3	For TarMK instances on AEM 6.0 to 6.2, manually run Offline Revision Cleanup instead.
`com.day.cq.audit.impl.AuditLogMaintenanceTask`	crx3	Must configure the Audit Log Purge Scheduler OSGi configuration before running.

February 23, 2022 Estimated Post Reading Time ~

July 1, 2021 Estimated Post Reading Time ~

May 28, 2021 Estimated Post Reading Time ~

March 22, 2021 Estimated Post Reading Time ~

February 2, 2021 Estimated Post Reading Time ~

January 23, 2021 Estimated Post Reading Time ~

January 18, 2021 Estimated Post Reading Time ~

January 11, 2021 Estimated Post Reading Time ~

January 6, 2021 Estimated Post Reading Time ~

How to Use It

February 23, 2022
Estimated Post Reading Time ~

July 1, 2021
Estimated Post Reading Time ~

May 28, 2021
Estimated Post Reading Time ~

March 22, 2021
Estimated Post Reading Time ~

February 2, 2021
Estimated Post Reading Time ~

January 23, 2021
Estimated Post Reading Time ~

January 18, 2021
Estimated Post Reading Time ~

January 11, 2021
Estimated Post Reading Time ~

January 6, 2021
Estimated Post Reading Time ~