Use of /etc/map on Publish Instance



[Thread Edited By Adobe]

/*Don’t forget to meet and greet your fellow peers virtually by telling them about yourself here

Go ahead and to it now: */


Actual Post:

I have a question related to best practices of /etc/mapping .

Following are two nodes under /etc/mapping for my Publisher


If I only add mapping  [1]  and access a page on publish instance,  I see all publisher urls on the page pointing to localhost:8087 (Dispatcher)  E.g. http://localhost:8087/equipment/swimming/abidjan-water.html

When I add the mapping [2] and access a page on Publish instance all URLs on the page are pointing to localhost:4503 E.g , http://localhost:4503/equipment/swimming/abidjan-water.html .

Is this a good practice to have etc/map  for publisher explicitly?

I am looking for a way so URLs on publisher would appear without any of the redirect rule.


Accepted Solutions (1)

Accepted Solutions (1)


Community Manager



Please refer to the article :-


URL Mapping and Deep Linking
A strength of Sling is the automatic and expected way that resources are structured and exposed in a logical, ordered manner. For example, AEM, by configuration allows page access through the /content/ directory. A typical page URL would be access with a browser visit to /content/projectname/pagename/subpagename.html. The minimal effort in maintaining this structure has its benefits, but changing that structure to fulfill business needs can be troublesome. Thankfully, AEM provides a number of tools and techniques to do so. This text will explore some of those options.

Root Mapping: The most common change is the need to hide the /content/ node or at least offer top-level pages at the root level. So, instead of a user typing “,” they should be able to type “” to reach the home page.

Normally, in a production environment, this is configured in front-facing web server like Apache with some configuration in the httpd.conf file using mod_rewrite. But it can also be done in AEM with some OSGi configuration:


Open Tools
Open OSGi Console
Search for and open Day CQ Root Mapping
Change the Traget (sic) Path property to whereever you'd like the redirect

Tip 1: If you like the old CQ5.5 dev landing page compared to AEM5.6, change projects.html to welcome.html

Tip 2: Other mechanisms for remapping URLs, which are discussed in this article, will break author instances because it interferes with things like authentication. Use the method above, which is safe, to remap the root node

Page Redirects: Sometimes pages are meant to simply be ways of grouping subpages, and not locations that a user should land on directly. These kind of pages can be set up as redirect component. A good example is the /content/geometrixx sample page.


To recreate this page redirect, either set it up when creating the page in AEM’s site builder (under New Page -> Advanced -> Redirect), or just change the properties of that page in CRX:

expand the content/{page} node
Click the ./jcr:content node
Change the sling:resourceType property to be foundation/components/redirect
Add a new String property called redirectTarget
Give redirectTarget a value of the new page (e.g. /content/myproject/mypage/mysubpage)

Tip 1: If a site is being built in one language, there’s no need to mimic the /en/ structure shown in the geometrixx example.

Tip 2: The sling extension (e.g. .html) will automatically carry over to the redirect page, and shouldn’t be specified

sling:Mapping Redirects: AEM’s most powerful URL-manipulation feature, a set of redirect components, is often overlooked because application servers don’t traditionally have this ability. But CQ’s built in Vanity URL support, namespace mangling, and internal tools all make use of this ability. A custom application can too, for instance, by remapping all /content project to /content/myproject

In CRX, navigate to the /etc/map node.
Open (or create) the http node of type sling:Folder
Create a node called content of type sling:Mapping
Add a property called sling:match and give it a value of localhost.4502/content/
Add a property called sling:internalRedirect and give it a value of /content/myproject

Now navigate to http://localhost:4502/content/mypage.html. The browser will display the URL that was entered, but internally AEM will be referencing the mapped directory structure.

Another way to test how CQ is handling mapping is by opening the Sling Resource Resolver tool. Log in with normal admin credentials (the default being admin/admin), enter http://localhost:4502/content/mypage.html into the test box, click Resolve and examine the “path” property that is output below the test box.

Problem: Remapping all of /content will also remap /content/dam, breaking current links

Solution: Override that particular mapping to point to itself

Within CRX, navigate to the /etc/map/http node.
Create a node called content_dam of type sling:Mapping
Add a property called sling:match and give it a value of localhost.4502/content/dam/
Add a property called sling:internalRedirect and give it a value of /content/dam/

This node will point to itself, and override the above /content/ mapping. The mapping rule resolution I believe is determined by string length and can be manipulated with sling:OrderedFolder. If readers have experience with this, please add comments below. It hasn’t been necessary to experiment with this feature for my projects.

The above problem will be more apparent if, instead of /content/ being mapping to the content directory, the root directory is also mapped.

Tip: Do not remap the root directory using this technique. There is a better technique above

While I recommend against remapping the root directory on author instances, as it will break things like authentication and CRX, it can still be done. In which case, the following directories also need to be remapped to point to themselves:


This should allow most applications and features of AEM to still work. But some monitoring of the app should take place to make sure other locations are not inappropriately being remapped.

Tip: If there’s a question about which URLs are being accessed by browsers or CRX, a tool like Fiddler can monitor and report on it.

Dynamic Redirects: Thankfully, both the sling:match and sling:internalRedirect nodes use regular expressions, so that URL mapping can be more dynamic. So things like top-level links can be remapped to strip off the “.html” extension.

Within /etc/map/http
Create a new node named posts of type sling:Mapping
Add a property called sling:match with value localhost.4502/posts/([^/]+)$
Add a property called sling:internalRedirect with value /content/myproject/posts/$1.html

This will allow posts to be accessed without an extension. There are other ways of performing this particular task, such as adding a GET.jsp entry to the components, but mapping redirects are the best way to not interfere with the rest of the Sling resolution logic.

Deep Linking: When taking advantage of dynamic sling:Mappings with regular expressions, URL deep-linking can be implemented without the use of URL parameters or javascript. In some cases, SEO (Search Engine Optimization) experts will advise that sub-pages be reached from URLs and get loaded on the initial request. Other needs like analytics engines might preclude the use of hash tags or URL parameters. In this case, AEM can leverage URL mappings and selectors to pass information to a component and preload content.

In the posts node above, for instance, we can instead change the mapping from going to post sub pages to the posts page directly. Here, assume there is some component inside the post page that loads properties from its child page. But it needs to know which child page is being accessed.

Add a property called sling:match with value localhost.4502/posts/([^/]+)$
Add a property called sling:internalRedirect with value /content/myproject/posts.$1.html

The mapping above will take a request to /posts/child-page-name, and remap it to /posts.child-page-name.html. Essentially, this is the same as a posts.html call, with the addition of a component now being able to use the sling Resource API to extract that selector. The code within such a component would look something like this:


String defaultPostName = "";

//Below is logic to default posts based on page selectors.    
//e.g. posts.{post-name.}.html
String selectorPath = currentPage.adaptTo(Resource.class).getResourceMetadata().getResolutionPathInfo();
String selectors[] = selectorPath.split("\\.");
if (selectors.length > 2) {
  defaultPostName = selectors[1];
view rawposts.jsp hosted with ? by GitHub
Tip 1: The dollar sign ($) above tells the regex “this is the end of the string. AEM therefore won’t map any URL with additional characters in the URL. However, URL parameters and hash tags will be ignored for the purposes of mapping, and don’t need to be considered

Tip 2: The technique demonstrated above will extract selectors from a page. Multiple can be stacked with additions /([^/]+) references in the sling:match property, and $2, $3… variable references in the sling:match property

Tip 3: Selectors can also be added to components using sling:include tags. To get a parent resource containing that information, use componentContent.getResource() in place of the currentPage.adaptTo(Resource.class) reference above

Summary: CQ offers a number of techniques to remap pages and URLs. While most of this can and should be done on a proxy web server, some powerful mapping tools are available directly in CQ. The topic is only superficially covered here, and any shared experiences or tips from readers are welcome in the comments below.

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

Link 2 :-

I hope this would help you.

Thanks and Regards

Kautuk Sahni

Answers (6)

Answers (6)



Thanks kautuksahni​ for the valuable info. I've been using Apache redirects in the dispatcher to add '/content' back on to the path so it matches what is in the Publishers. But is seems from your post that this can also be done using Sling OSGi configurations as well. Is there an advantage to doing it one way over the other?



Thanks for links / resources. 

When I use the /etc/map nodes then mapping rules will also get applied to Publisher pages  ( Please correct me if this is wrong understanding). 

So if I have a html element like < a href="">Link</a> [ Assume there are certain sling:match rules which  hide "/content/a/b" under /etc/map/http/ ] so link on the Publisher Page would be displayed like < a href="">Link</a>. 

I think it would be confusable for some content previewers as links on Publish systems are pointing out to <> , or is this how it is supposed to work when you use /etc/map ?