ACS AEM Commons: The Complete Guide

ACS AEM Commons is installed on over 90% of enterprise AEM instances worldwide, yet most teams use less than 10% of its capabilities. This glaring disparity means that countless hours are wasted re-inventing the wheel, writing custom OSGi services, and building administrative tools that already exist—battle-tested and ready to use—within this single dependency. In an enterprise production setup, true mastery of ACS AEM Commons distinguishes a novice developer from a Staff-level architect. The reality is that blindly installing this package without deeply understanding its underlying architecture, particularly in the modern era of AEM as a Cloud Service, will actively harm your deployment pipelines, break your caching strategies, and introduce subtle security vulnerabilities.

This exhaustive guide is designed to dissect, explore, and demystify the entirety of the ACS AEM Commons ecosystem. We will cover the granular details of its implementation, from foundational architecture to advanced operational features. You will learn:

• Foundational deployment strategies and Maven integration across AEM 6.5 and Cloud Service.
• SEO, routing, and delivery optimizations including the Redirect Manager, Error Page Handler, and Versioned Clientlibs.
• Administration, audit, and operations frameworks like the Audit Log Search, Manage Controlled Processes (MCP), System Notifications, and Report Builder.
• Bulk content manipulation using the Fast Action Manager (FAM) with custom Java API examples.
• Content authoring accelerators including Generic Lists, Shared Component Properties, and the Component Error Handler.
• Developer tools such as the HTTP Cache, Dispatcher Flush Rules, and legacy "Ensure" tools.
• The definitive Cloud Service transition matrix, detailing what to keep, deprecate, or replace with native AEMaaCS features.

Before diving deep into the ACS Commons toolkit, I highly recommend brushing up on your core AEM architecture. Check out my Backend Development complete guide, the OSGi in AEM complete guide, and the Dispatcher complete guide to understand exactly where these tools fit into the larger technology stack. Furthermore, understanding the nuances of security is paramount, so ensure you review the Security and ACLs guide, along with the AEM Cloud Service complete guide, the AEM SEO complete guide, and the AEM Workflows complete guide for comprehensive context.

Setup and Architecture

Integrating ACS Commons via Maven

Integrating ACS AEM Commons into your project is not a simple drag-and-drop operation. In a modern AEM project built upon the AEM Project Archetype, it is critical to embed the all package. This strategy ensures that the ui.apps, ui.content, OSGi bundles, and necessary Oak index definitions are correctly deployed in the exact sequence expected by the AEM package manager. Failure to do so often results in missing OSGi configurations or unresolved bundle dependencies.

In your root pom.xml, define the dependency management. This centralizes the versioning and ensures that all sub-modules reference the exact same version of ACS Commons.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.adobe.acs</groupId>
            <artifactId>acs-aem-commons-all</artifactId>
            <version>6.4.0</version>
            <type>zip</type>
        </dependency>
    </dependencies>
</dependencyManagement>

Next, in your all module's pom.xml, you must embed the package via the FileVault Package Maven Plugin. This is the recommended approach for both AEM 6.5 and AEM as a Cloud Service.

<plugin>
    <groupId>org.apache.jackrabbit</groupId>
    <artifactId>filevault-package-maven-plugin</artifactId>
    <extensions>true</extensions>
    <configuration>
        <embeddeds>
            <embedded>
                <groupId>com.adobe.acs</groupId>
                <artifactId>acs-aem-commons-all</artifactId>
                <type>zip</type>
                <target>/apps/my-project-packages/application/install</target>
            </embedded>
        </embeddeds>
    </configuration>
</plugin>

It is also crucial to add the dependency to the dispatcher module if you are utilizing features that require specific rewrite rules, such as the Error Page Handler or Versioned Clientlibs.

Versioning and Compatibility Matrix

You must strictly match the ACS Commons version to your target AEM architecture. Deploying an outdated version on a modern Cloud Service instance will result in immediate deployment failures due to immutable /apps restrictions and restricted Oak index modifications.

On AEM as a Cloud Service, features that require writing to /apps at runtime or modifying Oak Indexes directly are fundamentally broken. The immutable /apps tree means tools like "Ensure Oak Index" will fail spectacularly. If you attempt to use them, the Cloud Manager pipeline will aggressively block the deployment during the code quality or build phases.

SEO, routing, and delivery

When it comes to SEO, caching, and request delivery, ACS Commons offers massive time-savers. However, understanding the performance implications of each tool is essential. For full context on organic search optimization in AEM, cross-reference this section with the AEM SEO complete guide.

Redirect Manager

The Redirect Manager allows content authors to manage 301 and 302 redirects directly from the AEM Tools UI, removing the need for daily IT tickets to update Apache/Dispatcher rewrite rules. This single feature has saved enterprise organizations countless hours of developer time.

How it works: Authors create a configuration page under /conf/my-site/settings/redirects. Within this UI, they define source paths (or regex patterns), target URLs, and the HTTP status code (typically 301 for permanent moves, or 302 for temporary campaigns). The ACS Commons Redirect Filter intercepts incoming requests early in the Sling resolution process. It queries these configurations, evaluates the rules in memory, and issues an HTTP redirect directly from the publisher if a match is found.

Regular Expression Support: The Redirect Manager supports full Java regular expressions, making it incredibly powerful for structural URL migrations. For example, to match an old category structure and map it to a new one while preserving the slug:

• Source: ^/content/my-site/old-category/(.*)$
• Target: /content/my-site/new-category/$1

You can also use regex to handle query parameters or capture specific numeric IDs. It is critical to test these expressions thoroughly, as a poorly written regex can cause catastrophic backtracking and bring down your publisher CPU.

Import/Export Capabilities: During a massive site migration (e.g., migrating an older CMS to AEM), authors need to ingest thousands of legacy redirects. The Redirect Manager supports importing and exporting redirects via CSV formats. The expected CSV format requires columns for Source, Target, Status Code, and an optional 'Until Date'.

Source,Target,StatusCode,UntilDate
/old-page,/content/my-site/us/en/new-page.html,301,
/campaign-2025,/content/my-site/us/en/campaigns/2025.html,302,2026-12-31T23:59:59.000Z

When importing, you can choose to append to the existing list or overwrite it entirely. This makes it trivial to manage huge sets of redirects via Excel before pushing them to the production environment.

Evaluation Order Gotchas: Rules are evaluated sequentially from top to bottom based on their order in the UI. A common enterprise mistake is placing a catch-all regex rule near the top of the list. If you have a rule matching ^/products/(.*)$ followed by a specific rule for /products/special-item, the specific rule will never execute. Always order your rules from most specific (exact matches) at the top, to most general (regex catch-alls) at the bottom.

Performance Limits: Do not rely on Redirect Manager for hundreds of thousands of redirects. The Apache mod_rewrite module at the Dispatcher level is significantly faster because it avoids hitting the AEM publisher entirely, thus bypassing JVM overhead. For huge datasets (>10,000 redirects), compile them into a rewrite map for Apache. Reserve the Redirect Manager for day-to-day authoring needs, such as marketing campaign vanity URLs or one-off page movements.

Error Page Handler

AEM's native error pages are notoriously difficult to style consistently, often resulting in generic white-label error screens that degrade the user experience. The ACS Commons Error Page Handler intercepts 404s (Not Found) and 500s (Internal Server Error) and dynamically renders a branded, authorable error page managed within the AEM site hierarchy.

To configure it, you must deploy an OSGi configuration for com.adobe.acs.commons.errorpagehandler.impl.ErrorPageHandlerImpl:

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    jcr:primaryType="sling:OsgiConfig"
    prop.error-page.path="/content/my-site/us/en/errors"
    prop.error-page.extension="html"
    prop.error-page.fallback.name="500"
    prop.error-images.enabled="{Boolean}true" />

Dispatcher Integration: For the Error Page Handler to function, your Dispatcher configuration must include DispatcherPassError 1. This directive instructs the Apache web server to pass error handling back to the AEM publisher, allowing the ACS Commons filter to execute and render the appropriate page. Without this, Apache will intercept the 404 and serve its own static error document.

Versioned Clientlibs

Cache-busting clientlibs natively relies on query strings (e.g., ?v=123), which some aggressive enterprise proxies and strict CDNs ignore. Versioned Clientlibs solves this by rewriting the HTML to inject an MD5 hash of the clientlib content directly into the URL path.

Instead of generating: /etc.clientlibs/my-site/clientlibs/clientlib-base.css The HTML is rewritten to: /etc.clientlibs/my-site/clientlibs/clientlib-base.ACSHASH8a7b6c5d4e3f.css

To enable this, you must configure the Sling Rewriter pipeline. First, configure the OSGi service com.adobe.acs.commons.rewriter.impl.VersionedClientlibsTransformerFactory. Then, update your project's rewriter pipeline configuration (usually located at /apps/my-site/config/rewriter/default) to include the versioned-clientlibs transformer type in the transformer chain. This ensures that every HTML response is parsed and updated before being sent to the client.

Sitemap Generator

ACS Commons provides a Sitemap Generator that crawls your content tree, evaluates page metadata (like noindex flags), and spits out a valid, XML-compliant sitemap.xml for search engines.

[!WARNING] AEMaaCS Warning: Do not use the ACS Commons Sitemap Generator on AEM as a Cloud Service. AEMaaCS now includes a native, highly optimized OSGi-based Sitemap service built into core components. The native tool is significantly faster, integrates flawlessly with the Cloud Service CDN, and is natively supported by Adobe. Transition away from the ACS implementation immediately if you are migrating to the cloud.

Administration, audit, and operations

For system administrators and devops engineers, the operations toolset in ACS Commons is indispensable. Be sure to review the Security and ACLs guide to ensure you grant access to these powerful tools securely, as granting them to broad author groups can result in massive accidental changes.

Audit Log Search

AEM natively tracks an enormous amount of background activity in the /var/audit repository structure. This includes page modifications, user logins, replication events, and DAM asset updates. However, reading this JCR structure manually using CRXDE Lite is virtually impossible because the nodes are hashed into deep chronological folders (e.g., /var/audit/com.day.cq.wcm.core.page/2026/10/28/15/22/abcxyz123).

The ACS Commons Audit Log Search provides a powerful, human-readable UI to query this data. Want to know who deleted that critical configuration page last Tuesday? Or who triggered a massive replication tree activation that clogged the queues? Audit Log Search will give you the answer.

Query Examples and Tracking: Through the UI, you can filter by:

• Event Type: cq:Page (modification/deletion), cq:Replication (activation/deactivation), or dam:Asset (uploads/metadata updates).
• User: Search for actions performed by a specific author ID.
• Path: Limit the search to a specific tree, such as /content/my-site/us/en/products.
• Date Range: Filter down to a specific maintenance window.

By leveraging this tool, tier-3 support teams can definitively prove exactly which user triggered a breaking change, dramatically reducing the time spent finger-pointing during an incident post-mortem.

Manage Controlled Processes (MCP)

The Manage Controlled Processes (MCP) framework is undeniably the most powerful administrative feature in ACS Commons. It is a robust system for executing complex, multi-step processes asynchronously, utilizing a rich UI that tracks job status, pauses execution if needed, and stores results persistently in the JCR.

Each tool within MCP is designed to handle enterprise-scale tasks that would otherwise require writing custom Servlets.

Page Relocator

Manually moving a page in AEM is fine. Moving an entire tree of 5,000 product pages will freeze your browser, lock up the server, and inevitably fail halfway through. The MCP Page Relocator handles massive structural shifts flawlessly. It processes the move in chunks, updates all incoming references (so links on other pages don't break), handles live copy relationships, and optionally triggers replication to the publish tier once the move is complete.

Tag Creator

Taxonomy updates are a frequent request from marketing teams. Instead of manually creating hundreds of tags in the UI, the Tag Creator ingests a simple Excel spreadsheet. The spreadsheet defines the namespace, parent tags, child tags, and localized titles. The tool instantly reconstructs the complex hierarchical taxonomy in the /content/cq:tags space.

Data Importer

When migrating structured content (like hundreds of store locations or generic list items), the Data Importer is invaluable. It ingests tabular data from an Excel or CSV file and maps the columns to JCR properties on target nodes. You can specify a template to use for new nodes, making it a poor-man's headless data ingestion pipeline that requires zero custom code.

Asset Ingestor

Migrating massive amounts of assets into the DAM often overwhelms the system if uploaded via the standard browser interface. The Asset Ingestor bypasses this by pulling directly from an S3 bucket, an SFTP server, or a local file system (on on-premise servers). It intelligently throttles the ingestion to prevent the AEM Asset Compute workers or legacy Workflow engine from crashing under the load.

Report Builder

AEM's native reporting is often inadequate for specific business needs. The ACS Commons Report Builder allows developers to define custom reports using SQL2 or Query Builder syntax. Authors can then execute these reports from the UI and export the results to Excel.

To create a custom report, you define a configuration page that dictates the base query. You can add configurable parameters (like date ranges or path selectors) that users fill out before running the report. The engine dynamically evaluates the query and formats the output into a downloadable CSV, bridging the gap between raw JCR queries and marketing-friendly reports.

System Notifications

When executing a massive deployment or preparing for a scheduled maintenance window, communicating with logged-in authors is critical. The System Notifications tool allows administrators to publish a banner message that appears at the top of the AEM interface for all active users.

You configure this by creating a notification page under /etc/acs-commons/notifications. You can specify the message text, the severity (Info, Warning, Error), and an expiration date. Once activated, any user navigating the Touch UI will see the banner, preventing them from starting long-running tasks right before a server restart.

The Fast Action Manager (FAM)

The Fast Action Manager (FAM) is the silent engine that powers the entirety of the MCP framework. It is a Java API specifically engineered to execute multi-threaded, bulk operations against the JCR without crashing the repository.

If you are a backend developer tasked with writing a custom Sling Servlet or Groovy script that modifies 100,000 nodes, stop immediately. Writing a single-threaded for loop that calls resourceResolver.commit() every 1,000 nodes is an archaic, error-prone pattern. Instead, you must use the FAM API. It handles transaction chunking, thread pooling, session refresh, and retry logic automatically.

Writing a Custom FAM Action

To leverage FAM, you inject the ActionManagerFactory into your OSGi service. You then create an ActionManager instance, give it a name, and feed it a stream of tasks. FAM will distribute these tasks across a managed thread pool, handling the JCR session binding for each thread.

Here is a concrete example of an OSGi service utilizing FAM to update a specific property across an enormous list of paths:

import com.adobe.acs.commons.fam.ActionManager;
import com.adobe.acs.commons.fam.ActionManagerFactory;
import com.adobe.acs.commons.fam.actions.Actions;
import org.apache.sling.api.resource.ResourceResolver;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Reference;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import javax.jcr.Session;
import java.util.List;

@Component(service = BulkUpdateService.class)
public class BulkUpdateService {
    
    private static final Logger log = LoggerFactory.getLogger(BulkUpdateService.class);

    @Reference
    private ActionManagerFactory actionManagerFactory;

    public void processMassiveUpdate(ResourceResolver resolver, List<String> pathsToUpdate) {
        try {
            // Create a new ActionManager, providing a unique name and the initial session.
            ActionManager actionManager = actionManagerFactory.createTaskManager(
                "My Custom Bulk Update Job", 
                resolver, 
                1 // Number of retry attempts
            );

            // Iterate over the massive list and defer execution to FAM
            for (String path : pathsToUpdate) {
                actionManager.deferredWithResolver(action -> {
                    
                    // The 'action' provides a thread-safe ResourceResolver specifically for this execution
                    Resource resource = action.getResource(path);
                    if (resource != null) {
                        ModifiableValueMap properties = resource.adaptTo(ModifiableValueMap.class);
                        if (properties != null) {
                            properties.put("migratedProperty", "true");
                        }
                    }
                });
            }

            // Instruct FAM to commit the changes periodically, rather than per-node.
            // This massively improves performance.
            actionManager.addCleanupTask();

        } catch (Exception e) {
            log.error("Failed to execute bulk update job via FAM", e);
        }
    }
}

Notice how we do not explicitly call session.save() or resolver.commit() inside the loop. The deferredWithResolver method delegates the work to a background thread, and the internal FAM framework intelligently batches the commits based on system configuration. This prevents OutOfMemoryErrors and OakState0001 exceptions that plague manual bulk processing scripts.

Content Authoring Accelerators

Empowering authors while reducing developer overhead is the ultimate goal of any AEM implementation. ACS Commons provides several critical tools to achieve this.

Generic Lists

Generic Lists allow content authors to define simple key/value data structures (such as a dropdown list of US States, country codes, or product categories) directly in the AEM UI. This completely eliminates the need for developers to maintain hardcoded JSON files or complex OSGi configurations just to populate a component dialog.

How to use Generic Lists:

1. An author navigates to Tools > ACS AEM Commons > Generic Lists.
2. They create a new list, for example, at /etc/acs-commons/lists/us-states.
3. They populate the list with items, providing a "Title" (the user-facing label) and a "Value" (the backend data).

Using Generic Lists in Touch UI Dropdowns: You can directly bind a Touch UI dialog dropdown to a Generic List using the datasource property in your cq:dialog XML:

<state
    jcr:primaryType="nt:unstructured"
    sling:resourceType="granite/ui/components/coral/foundation/form/select"
    fieldLabel="State"
    name="./state">
    <datasource
        jcr:primaryType="nt:unstructured"
        sling:resourceType="acs-commons/components/utilities/genericlist/datasource"
        path="/etc/acs-commons/lists/us-states"/>
</state>

When the author opens the dialog, the dropdown automatically populates with the latest values managed by the business team.

Java API and HTL Usage: If you need to access this data directly within a component's backend logic, ACS Commons provides a clean Java API. You can adapt the list page to a GenericList object.

import com.adobe.acs.commons.genericlists.GenericList;
import com.adobe.acs.commons.genericlists.GenericList.Item;
import org.apache.sling.api.resource.ResourceResolver;
import java.util.ArrayList;
import java.util.List;

public List<String> getStateOptions(ResourceResolver resolver) {
    PageManager pageManager = resolver.adaptTo(PageManager.class);
    Page listPage = pageManager.getPage("/etc/acs-commons/lists/us-states");
    
    GenericList genericList = listPage.adaptTo(GenericList.class);
    List<String> options = new ArrayList<>();
    
    if (genericList != null) {
        for (Item item : genericList.getItems()) {
            options.add(item.getTitle() + " - " + item.getValue());
        }
    }
    return options;
}

In your HTL (Sightly), if you expose the options list via a Sling Model, iterating over it is trivial:

<ul data-sly-list.state="${model.stateOptions}">
    <li>${state}</li>
</ul>

Shared Component Properties

In enterprise architectures, you frequently encounter scenarios where a property must be available globally across a site, but is not appropriate to store on every single page property dialog. Examples include a global Google Maps API Key, a site-wide disclaimer text, or a third-party tracking ID.

Shared Component Properties allows you to define these global values at the site root. ACS Commons utilizes a custom Sling Resource Provider that intercepts resource resolution. When a component attempts to read its properties, the Resource Provider dynamically injects the shared properties into the component's ValueMap. To the component's underlying code or Sling Model, the property appears as if it was authored directly on the component itself.

Component Error Handler

If a custom component throws an unhandled exception (e.g., a NullPointerException within a Sling Model's @PostConstruct method, or an HTL syntax error), AEM's default behavior is catastrophic. The rendering engine crashes at that specific node, outputting a massive Java stack trace directly into the HTML response, and entirely skipping the rendering of the rest of the page. This breaks the site layout and destroys the user experience.

The Component Error Handler elegantly solves this by wrapping component execution in a secure try/catch mechanism.

Configuration and Behavior: To enable it, deploy the OSGi configuration com.adobe.acs.commons.wcm.impl.ComponentErrorHandlerImpl:

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    jcr:primaryType="sling:OsgiConfig"
    prop.edit.enabled="{Boolean}true"
    prop.publish.enabled="{Boolean}true" />

• On an Author instance: When a component breaks, the handler catches the exception and renders a distinct red error box containing the stack trace. The rest of the page continues to render normally. This visually alerts the author that the component is broken without destroying the authoring interface.
• On a Publish instance: The handler catches the exception, logs it to error.log, and silently outputs nothing. The broken component is hidden from the end user, but the surrounding layout, header, footer, and other components render flawlessly. This is a critical defensive programming pattern for production environments.

Developer Tools and Optimizations

While operations teams love MCP, developers rely heavily on ACS Commons for backend performance optimization and legacy automated provisioning.

HTTP Cache

AEM's primary caching layer is the Apache Dispatcher. However, there are scenarios where the Dispatcher cannot cache a request effectively—such as authenticated personalized data, complex search queries, or Sling Servlets acting as proxy endpoints to third-party REST APIs (like a live pricing engine or weather service). If every user hits the Servlet, the JVM CPU will max out.

The ACS Commons HTTP Cache provides an in-memory caching mechanism that operates directly inside the AEM JVM. It intercepts requests before they hit the expensive Sling resolution lifecycle.

Configuration and Cache Key Generation: You must configure the HttpCacheEngine and define specific HttpCacheConfig factories. The core of the HTTP Cache is the Cache Key Generation. You configure rules defining how a request is identified as unique.

For example, if you have a Servlet answering at /bin/weather, you can configure the HTTP cache to key off of the query parameter zipCode.

1. Request A: /bin/weather?zipCode=10001 (Cache Miss - executes Servlet, caches result against key 10001).
2. Request B: /bin/weather?zipCode=10001 (Cache Hit - returns cached JSON instantly).
3. Request C: /bin/weather?zipCode=90210 (Cache Miss - executes Servlet, caches against key 90210).

You can configure caching based on resource paths, specific file extensions, HTTP headers, or authentication requirements. The cache can be stored entirely in memory (RAM), backed by the JCR, or utilizing the Ehcache library.

Warning: Do not use the HTTP Cache for standard HTML pages. Always rely on the Dispatcher or your CDN (Cloudflare, Akamai, Fastly) for page-level caching. AEM memory is incredibly expensive compared to CDN edge memory.

Dispatcher Flush Rules

Managing cache invalidation in AEM is notoriously difficult. When an author publishes a shared Experience Fragment (XF), how does the Dispatcher know to invalidate all the HTML pages across the site that include that specific fragment? Native AEM only flushes the path of the specific resource activated.

Dispatcher Flush Rules solve this by allowing administrators to define hierarchical dependency relationships. If a resource at Path A is activated, force the Dispatcher to flush Path B.

OSGi Configuration Example: Deploy the configuration com.adobe.acs.commons.replication.dispatcher.impl.DispatcherFlushRulesImpl:

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    jcr:primaryType="sling:OsgiConfig"
    prop.rules.hierarchical="[
        /content/experience-fragments/my-site/.*=/content/my-site/us/en/.*
    ]" />

In this relationship graph, any activation event matching the regex for the Experience Fragment folder will be intercepted by the ACS Commons replication event listener. It will then automatically synthesize a new flush request targeting the entire US/EN site tree, guaranteeing that the cache is properly invalidated.

Ensure Authorizable vs. RepoInit (Legacy Patterns)

Historically, AEM developers relied heavily on the "Ensure" tools provided by ACS Commons. "Ensure Service User", "Ensure Authorizable", and "Ensure Oak Index" allowed developers to define OSGi configurations that automatically created system users, assigned ACL permissions, and built search indexes when the bundle started.

[!WARNING] DEPRECATED AND DANGEROUS: Do not use Ensure Service User, Ensure Authorizable, or Ensure Oak Index on modern AEM architectures.

The standard, Adobe-supported, and AEMaaCS-compatible methodology to create users, groups, and ACLs is Sling RepoInit. RepoInit executes directly at the JCR repository level long before the OSGi framework begins activating component bundles. This guarantees that your system users exist before your custom services attempt to log in.

Furthermore, on AEM as a Cloud Service, the immutable architecture strictly prevents runtime modifications to the /apps tree or Oak Indexes. Attempting to deploy "Ensure Oak Index" will result in catastrophic failure during your Cloud Manager deployment pipeline.

Review the OSGi in AEM complete guide for the correct syntax for implementing Sling RepoInit scripts.

The Cloud Service Transition Matrix

Migrating a legacy AEM 6.5 application to AEM as a Cloud Service fundamentally alters how you must utilize ACS Commons. The shift from a mutable on-premise model to an immutable, containerized CI/CD architecture means many beloved tools are now obsolete or actively harmful. Read the full AEM Cloud Service complete guide for overarching strategy.

If you are undertaking a migration, you will likely spend significant time refactoring out deprecated ACS Commons features. Ensure you audit your codebase thoroughly against this matrix.

Cheat Sheet

Best Practices

1. Adopt RepoInit for Everything Security-Related: Fully abandon all ACS Commons "Ensure" tools for provisioning users and ACLs. Sling RepoInit is the only modern, secure, and cloud-compatible way forward.
2. Scrutinize OSGi Configurations: ACS Commons features are largely opt-in via OSGi. Do not blindly enable features like the Error Page Handler or Versioned Clientlibs without rigorously testing the impact on your Dispatcher and CDN caching strategies.
3. Train Lead Authors on MCP: The Page Relocator is an absolute superpower for site management. Train your lead authors to use it instead of manually dragging and dropping 50 pages in the AEM UI, a practice which inevitably leaves broken links and orphaned references.
4. Utilize FAM for All Bulk Custom Code: If you are tasked with writing a maintenance script that touches more than a few hundred JCR nodes, mandate the use of the Fast Action Manager during code reviews.

Do's & Don'ts

• DO use the Fast Action Manager (FAM) API to handle transaction chunking and thread pooling for any custom bulk processing scripts.
• DO configure the Component Error Handler on production environments to prevent a single bad HTL script or missing property from taking down your entire homepage layout.
• DO leverage Generic Lists to empower authors and reduce the amount of trivial configuration code developers must maintain.
• DON'T use the ACS Sitemap Generator on AEM as a Cloud Service; rely entirely on the native implementation.
• DON'T rely on the HTTP Cache if you can cache the request at the Dispatcher or CDN level instead. CDN edge memory is infinitesimally cheaper than AEM JVM memory.
• DON'T use Redirect Manager as a crutch for structural URL architecture flaws; rely on Apache for massive, systemic routing changes.

Enterprise AEM engineering requires precision. By mastering these specific, high-value components of ACS AEM Commons, you can drastically reduce technical debt, empower your content authors, and guarantee your architecture is prepared for the rigors of AEM as a Cloud Service.