Welcome to CQBlueprints - A resource for your Adobe CQ 5.4, 5.5, 5.6 and AEM6 projects. Get your CQ project on the right track.


It is often desirable to serve static assets from an alternate server to reduce load on a primary server and to leverage parallel loading within the client browser.

The solution to achieve this in CQ has two parts:

  1. Create a mapping that defines what paths are mapped and what their equivalents are on the alternate server
  2. Create a custom implementation of the com.day.cq.rewriter.pipeline.RequestRewriter interface that will allow for links to any kind of resource to be rewritten

For the rest of this document assume that the use case we would like to achieve is to change any links to assets located in the DAM to be served from an alternate server. For example, for the PDF document located at:


in the repository, would normally result in a download URL like:


However, what we need is for any references to that PDF in our site to instead use the URL


Defining Mappings

Mappings can be defined in two different places:

  1. Using the Configuration Manager (ie. http://localhost:4502/system/console/configMgr) and changing the properties of the Apache Sling JCR Resource Resolver service.
  2. Defining configuration nodes under the /etc/map node in the repository.

For the 2nd option, we can simply create additional nodes under the /etc/map node that define the mappings we need. In the image below we have created a folder called http of type sling:Folder and we created a node of type sling:Mapping called static.example.com

Next we set a property on the sling:Mapping node called sling:internalRedirect and gave it the value /content/dam


Once we save these changes, we can check to see if everything is working as expected using the Sling Resource Resolver page in the System Console (ie. http://localhost:4502/system/console/jcrresolver).

In the image below you can see that our mapping has been recognized by the Resource Resolver and is part of the map.


We can also use the testing tool on the same page to validate that the mapping works as expected. For example, if we enter the path to the example PDF document as /content/dam/geometrixx/documents/GeoCube_Datasheet.pdf  into the Test field and then click Map, we can see that the resulting URL is the one we are looking for:


Create a Custom Request Rewriter

If you now create a page and place the Download component on the page and then configure it to make the example PDF available for downloading, you will notice that the URL used for the PDF has not changed. This is because even though we can define the necessary mappings (as we did above) and we can test them to make sure they work, the CQ runtime system by default only uses the mapping rules for URLs associated with HTML pages. So links to things like PDFs stored in the DAM never get rewritten.

This behavior can be overridden by deploying a custom implementation of the com.day.cq.rewriter.pipeline.RequestRewriter service into the OSGi container. If you do this, the CQ system will pick up the custom implementation and consult it when it comes to rewriting URLs in pages.

Luckily, there is a custom implementation of the RequestRewriter interface provided as part of the CQ Blueprints projects that enables links to all resources to be controlled by entries in the Resource Resolver map. To make use of it, simply download the latest version from the CQ Blueprints Nexus Repository, which is bundled as a standard CQ Package and install it on your server.

This module is provided under the apache commons license 2.0 and free to be used in any project.

The Result

Once the Resource Resolver mappings have been defined as above and the custom implementation of the RequestRewriter server has been deployed, any links to assets under the /content/dam path, will have their URLs rewritten inside of any HTML pages that are returned from CQ. Links to pages or to assets outside of the standard DAM path will not be affected, which includes renditions of images whose URL is relative to the page they are referenced from.

Author vs Publish

Serving static assets from an alternate URL is usually only necessary in a Publish environment. To ensure that the mapping settings only apply within a Publish environment and do not affect Authoring environments, the name of the /etc/map node should be changed to /etc/map.publish

Do you find the information on this site useful? Do you think we should add an article on a specific subject? We'd like to hear from you. Please drop us an email @ info@headwire.com

Search CQ Related Information