An overview on ACS AEM Commons

ACS (Adobe Consulting Services) AEM Commons is an open-source library of pre-built AEM tools and functionalities that can help editors and developers to perform different operations on AEM servers, from deployment to cache management.

Operations done with ACS Commons can often be performed in other ways, however there are some advantages in using ACS Commons tools. For example a lot of operations can be done by simply going in the right ACS Commons page and set the needed configurations.

ACS Commons come in one package that can be installed on the AEM server in two ways:

embedding ACS Commons in the AEM project as a Maven dependency,
manually deploying the ACS Commons package with package manager.

The package contains all ACS Commons tools, so it’s not possibile to install only the needed features.

ACS Commons tools can be accessed in the tools menù, shown below.

The pages used for ACS Commons configurations are located under the path /etc/acs-commons/.

In this article we’ll do a quick overview for some ACS Commons tools, that can be used to perform operations in these scopes:

Deployment operations management
URL consistency management
Cache management
User permissions management
Repository content management

1. Deploy Operations

One useful feature to manage post-deploy operations is the On-Deploy Script tool. This tool can be used to create one-time scripts that automatically execute upon a deploy on an AEM server.
With this tool operations as massive content updates, structure changes in the project (e.g. changing the location of a component) or administrator updates (e.g. operations on user data) can be done authomatically on all AEM servers together with the deploy.

Running the scripts at the same time as the code deployment assures project consistency and reduces work and risks of human errors for developers. The state of every script is saved in the repository, so we can be sure that every script is executed only once on every AEM server. If a script fails, the execution of the script stops and the failed status of the script is saved. At the next deploy or restart of the AEM instance, the execution starts from the previously failed script.

To use On-Deploy Script developers only have to enable the feature by deploying an OSGi configuration file and provide the scripts that need to be executed.

2. URL Consistency

One tool we can use to ensure URL consistency is the Redirect Map Manager tool. This feature allows to mantain and publish Apache httpd redirect map files without requiring an Apache restart. These files are used to manage large lists of redirects and rewrites in the Apache Dispatcher.
Map files are created as new pages under the /etc/acs-commons/redirect-maps path. In these files we can configure the redirect rules in two ways:

as a list of source/target entries that can be set by interface or uploading a txt file,
configuring a query that automatically creates the redirect/rewrite rules based on a property of our choice in pages and assets inside the repository.

Map files must be created on the AEM publish server. After a map file is ready, we just need to add a Cron task on the dispatcher to automatically and periodically pull the file from the publish.

3. Cache Management

These three different ACS Commons features can help in cache management operations.

The Dispatcher Flush Rules tool is used to define simple yet powerful rules for targeted flushing of files cached by Dispatcher. This tool is useful to create a “smart” automated flush scheme that listens for replications and then invalidates logical pairings of content, leaving the rest of the web site’s content safely cached.
The tool need to be executed on the AEM publish server, which should have On Trigger Flush Agents set up. Then we just need to create a new sling:OsgiConfig node for each logical flush rule set.

The Dispatcher TTL tool allows Response Headers to be set instructing AEM Dispatcher to respect a TTL-based timeout. To use this tool we need to create a series of sling:OsgiConfig files each representing a Path and TTL-scheme.

The Versioned Clientlibs tool allows CSS and javascripts clientlibs to be cached client-side with long TTLs, ensuring that the client is able to download a new version of the clientlib when updated. To achieve this result, the hash of the file is included in the URI of the clientlib. When the clientlib file is updated, the URI of the clientlib will change so the client will download the new version of the clientlib regardless of the time set in the TTL.

4. User Permissions

Some ACS Commns tools are useful to manage operations on user permissions.

The Authorizable Packager tool facilitates the creation of Content Packages containing authorizables based on the authorizable IDs. Under the /etc/acs-commons/packagers folder we need to create a new page of template type “Authorizable Packager” in which configure the package definition. Then we can build and download the package in CRX Package Manager.

The Ensure Service User tool facilitates defining service users and their ACLs in OSGi configurations and will ensure they exist on the target AEM instances. To use this tool we need to create an OSGi configuration for each service user or group, with the corresponding PID and unique identifier.

5. Repository Content

ACS Commons offer several tools to manage operations on the repository content.

There are exporter tools as the Tags Exporter and the User Exporter. Both can be used to export respectively tags and user data into CSV files.
Tags Exporter is available at the /etc/acs-commons/exporters/tag-to-csv-exporter.html page. Reports with User Exporters can be created as new pages under the /etc/acs-commons/exporters path.

Another feature useful to create report is the Report Builder tool, that allows to execute and download custom reports based on the content of the AEM repository. Reports can be customized with input parameters, result columns and the order in which the results are displayed.
Other than the Out-of-the-Box parameters and columns provided by the ACS Commons tool, the Report Builder can be extended to add custom report executors, column types and input parameter types.
Reports can be viewed, changed or created from the /ect/acs-commons/reports.html page.

ACS Commons offers two features to compare AEM pages or nodes.
The JCR Compare tool is used to compare specific node types across multiple AEM instances. Instances to be compared and comparison criteria are configured at the /etc/acs-commons/jcr-compare.html page.
The Page Compare tool compares two different pages or page versions on the same AEM instance. Pages to be compared are configured at the /etc/acs-commons/page-compare.html page.

The Ensure OAK Index tool allows Oak Index Definitions to be defined in a content package and then safely translated to real Oak Indexes. This avoid the risk to wipe out actual index data when deploying an application content package containing also the OAK Index definitions used by the application.

The Named Transform Image Servlet tool allows image transforms to be defined via OSGi configurations, so there’s no need to have specific image renditions saved in the AEM DAM. With this feature images in a page can be resized, cropped, rotated and greyscaled on-the-fly by simply using the appropriate image URI.
To use this tool developers need to define an OSGi configuration file representing a named transform and apply it by adding the extension .transform and the name of the transform to the image URI.
For exampe, with the URI …/myImage.transform/my-transform/image.jpg we can apply the rules set in the “my-transform” transform to the “myImage” image.

The Generic Lists tool is used to easily create and manage lists of title/value pairs. These lists can be used to populate selection widgets in component or page dialogs.
Lists are created as pages under the path /etc/acs-commons/lists.

6. Focus on Versioned Clientlibs

Versioned Clientlibs is a useful tool provided by ACS Commons. The purpose of use is to keep css and js files in cache for a long TTL.

How does it work?

Versioned Clientlibs uses a Sling Rewriter to rewrite the clientlib generated by AEM and appends a unique hash md5 at the end of the URL. So the clientlibs will be rewritten in the format /clientlib.md5hash.js and /clientlib.md5hash.css. This allows to re-cache only if there is a change in the files which in turn reduces the page load time and improve performance.

Unfortunately, as we can read from the website, the rewriter doesn’t support:

URIs embedded in CSS or JavaScript, including: background-images, web fonts, etc.
Relative URIs, e.g. etc/clientlibs/mysite/styles.css
URIs including a scheme, e.g. http://example.com/etc/clientlibs/mysite/styles.css and //example.com/etc/clientlibs/mysite/styles.css
URIs to non-AEM HtmlClientLibrary resources, e.g. /etc/designs/mysite.css
Tags contained in conditional comments.
ClientLibs included by Javascript (e.g. when leveraging the property channels)

Versioned Clientlibs Configuration:

Login to CRXDE http://localhost:4502/crx/de/index.jsp.
Go to /apps/<your-project>/config node and create a new folder called “rewriter”.
Then navigate to the default (OOTB) rewriter configurations from libs /libs/cq/config/rewriter.

Copy the default rewriter node under your “rewriter” folder
Select the default node and add versioned-clientlibs to transformerTypes, you can remove the other trasformer types (mobile, mobile-debug and contentsync)

Restart AEM instance for the changes to take effect
To check that the configuration was successful, navigate to http://localhost:4502/system/console/status-slingrewriter and you should see your resource path (in our case /apps/wereatail/config/rewriter/versioned-clientlib).

Now let’s configure Apache in order to set the correct header and keep the css and js files for a long time to live (TTL). So let’s add this in the httpd.conf file

SetEnvIf Request_URI “(\.min)?\.[a-f0-9]+\.js” long_expires=true

SetEnvIf Request_URI “(\.min)?\.[a-f0-9]+\.css” long_expires=true

Header set Cache-Control max-age=2592000 env=long_expires

To enable or disable versioned clientlibs navigate to http://localhost:4502/system/console/configMgr and search for “Versioned Clientlibs Trasformer Factory”