How to use internal redirects in AEM?

Reading Time: 4 minutes

When migrating a Ruby on Rails-based Application to Adobe Experience Manager we needed to use internal redirects. In this blog post, we are going to show you how to create internal redirects in AEM. It is very easy. Keep reading!

When migrating a Ruby on Rails-based Application to Adobe Experience Manager, one of the requirements requested by the client was to take out the "content" word of the URL. We first thought of using vanity URLs, but we would have to set them one by one on all the pages. So, we decided to use internal redirects for three main reasons:

  1. They allow us to use regular expressions
  2. We can keep the rules in our codebase
  3. We can set different rules for different domains

Creating an internal redirect is very easy. In this blog post, we are going to show you how to create a very basic rule. If you require more information, visit the AEM page and look around the topic. Or, you can go to the Apache Sling documentation.

By the way, don't forget to try the second part of this blog post to learn how to use regular expressions and configure them for different domains.

Creating the mapping in the authoring instance

To create the mapping rules, we should create them under the /etc/map/http node. We have two options to create the node: we could use the namespace as the name e.g. “”, or we can use another custom name e.g. “localhost_any” in conjunction with the “sling:match” property. For this example, we will use the second approach and we are going to map the request for news.

  1. Create a node under /etc/map/http with the name “localhost_any” and type “sling:Mapping”.
  2. Click “Save All”
  3. Add the following properties:

* “sling:match” with a value of “localhost.4502/news/” (it’s not a typo you should use “.” instead of “:”)
* “sling:internalRedirect” with a value of “/content/news/”


The above means we are going to catch all the requests that “match” the “localhost:4502/news/”, and that we are going to redirect them internally to “/content/news/” so it will be transparent for the user. That means that users will still see something like “localhost:4502/news/somepage.html” but we are going to be rendering “/content/news/somepage.html”.

To verify our mapping it’s working we can go to http://localhost:4502/system/console/jcrresolver. Then, in the “Mapping Map Entries” (at the bottom of the page) we should be able to see our mapping.


Now, if we go to the URL: “http://localhost:4502/news/.html” it will work! We got rid of the “content” fragment in our URL.

Replicating for a publish instance

Well, now that we are sure our mapping is working on the authoring instance, let’s replicate it in the publish instance. For that we need to follow these steps:

  1. Create a node under /etc called map.publish of type “sling:folder”
  2. Create a node under /etc/map.publish called “http” of type “sling:folder”
  3. Copy the “localhost_any” node from /etc/map/http to /etc/map.publish/http
  4. Select the newly created /etc/map.publish folder, the select the “Replication” tab and press “Replicate”



NOTE: For the replication to be successful we need our publish instance running.

Now that we replicated our rules, we need to change some configuration in our publish instance. To do that:
1. Open http://localhost:4503/crx/de
2. Log in as admin or a user with an administrator role (if not, you won’t be able to see the /etc/ folder)
3. Now you should be able to see the /ect/map.publish folder we replicated in our authoring instance, if not you may need to replicate the whole /etc folder. Select the /etc/map.publish/http/localhost_any node and change the value in “sling:match” from “localhost.4502/news” to “localhost.4503/news”. As you can see we changed the port to the one we are using in our publish instance (4503)
4. Copy the /etc/map.publish/http/localhost_any node to /etc/map/http/
5. Click “Save All”


Now we should be able to see our mapping being added to the system console: http://localhost:4503/system/console/jcrresolver


So, now we should be able to navigate to pages with the form “http://localhost:4502/news/yourpage.html”.

That's it for now, thanks for reading!

You May Also Like