Adobe Experience Manager (AEM) Link Transformer

I've been taught the wrong way to configure the Adobe Experience Manager (AEM) /etc/mappings in the past. There's zero documentation about how your URL, rendered from the Path Browser widget, gets Transformed to a relative URL hiding /content/sitename. Everyone says that the node name is important (it's not). So after spending an hour trying to sort this out, here's how it works.

You can create your own Link Rewriter by implementing the org.apache.sling.rewriter.Transformer interface. Adobe comes with one out-of-the-box that will use the Sling Mappings for Resource Resolution (a.k.a. /etc/mappings). The key is setting up your /etc/mapping correctly.

Here's an example of an /etc/mapping for a SSL (https) Site:


The OOTB Link Transformer will traverse your configured /etc/map directory from top to bottom, based on the node order. This is why setting the "jcr:primaryType" to "sling:OrderedFolder" is so important.

As it traverses the nodes, the first sling:internalRedirect regex that matches the link path will be used to rewrite the URL to what is set in the sling:match property. It uses the following values to rewrite the link:

• Protocol is selected based on the parent http or https;
• The regex grouping(s) that are created from the sling:internalRedirect property are used when rewriting the link; and
• The link will be rewritten using a combination of the protocol and the sling:match regex.

This is why using a sling:OrderedFolder is so important. As all sites should be https; if we have multiple sites and domains, and we offer linking via AEM Path Browser between them, we need to configure the sites to create fully qualified URLs with https. Without an Ordered Folder, http configurations would be ordered above https and this wouldn't work. Same with doing multiple mappings within a protocol node.

Finally, whatever domain is configured to at the Dispatcher will be used as part of Link Transformer to match and write a relative path. So...

• If your domain is bmxcode.com and that points to your reverse proxy;
• Your domain bmxcode.blogspot.com points at your AEM instance; then
• Set your "sling:match: property to "bmxcode.blogspot.com/$1" and this will rewrite your links as relative URLs (without the protocol and domain).

Hope this helps!