Ad Code

Sunday, January 5, 2020

Handing 301 Redirection in AEM using Redirect Map Manager

Hello Everyone,

In one of my previous blog, I explained about 301 Redirection and how to manage 301 redirects in AEM via page properties.

Ideally when we need 301 redirection?
1. When you are completely changing the website with a new hierarchy of Pages and Assets, 301 redirection is needed.The idea is the old users who were using the website will never get 404 and still can be redirected to the correct place.
2. If you want 301 redirection of  internal URL’s to External Sites.

Does the approach of 301 Redirection via page properties really solve the issue if not
then why?
1. Let's suppose we have a old website /content/we-retail/en/home.html and now the new home page is /content/we-retail/home.html, we won't manage the old hierarchy in our AEM, then having 301 redirection in page properties won’t really help.

2. The page properties 301 can only work, if you have a page just to create the hierarchy but you always want user to redirect to some other place.For instance: you have a page /content/we-retail/en and you want to 301 redirect to this page to home page.

Conclusion: Having 301 redirection in page properties can not solve all the use cases of 301 redirection.

If we are managing single/multiple websites in AEM, we really want a full fledged solution to
handle 301 redirection.
ACS Commons Redirect Map Manager is really able to solve all the above mentioned
issues And we can manage all the 301 redirection at the Apache level itself.

How to configure Redirect Map Manager for your project in AEM.
1. Go to miscadmin console. Go to Tools->acs commons->Redirect Maps.
2. Create a new Page.
Fig1: Create a page for Redirect Maps
3. Enter the Title/Name of your redirect map and click Create.
4.Upload a Redirect Map base file (optional). This can be useful for specifying miscellaneous or external redirects which aren’t found for pages in the AEM repository. For example, redirecting a particular URL to an external application.
5. If you don't want to upload a file, Go to "Edit entries" Tab and “Add Entry” by entering Source and Target. Use source as relative path and target you can configure the relative path if you want 301 redirection at the same domain or can configure the full external domain to redirect.
Fig2: Add entries for 301 Redirection
6. You can preview the list of all 301 redirection.In the “Download Preview”, you got the URL through which Apache server can access this file from AEM.
Fig3: Preview will show the link to access redirect map.
7. Publish the Redirect Map Pages.

Handling Configuration in Apache
1. Add a bash script (redirect-map.txt) to pull the redirect Map file from publisher.You can put it anywhere but i placed it in “/etc/httpd/conf.d/redirects/redirect-map.txt”. [The extension of the script can be .sh or .txt]

Below is the explanation of bash script line by line.
line No 4: need to change with the publish private IP to which apache should able to connect.(Can be tested via telnet)
line No 5:Need to define the log directory of the apache server
line No 7:This is the name of the redirect map you created in your AEM. If there are multiple redirect map to handle multiple sites, you can add all the redirect Map pages name here.
line No 12: This line will start loop for all the map files one by one.Let’s see the execution of we-retail map file.
line No 15: Will remove the file from /tmp/we-retail.txt 
line no 16:It will fetch the file from the publisher and put it in “/tmp/we-retail” and log this activity in a log file named “update-redirect-map.log”.
line No 17: convert the /tmp/we-retail file to a DBM file and place the newly db files(.pag file and dir file) in conf directory. So the files gets created are /conf/httpd/conf/tmp-we-retail.pag and /etc/httpd/conf/tmp-we-retail.dir and log this activity in log file.
line No 18,Move the file from /etc/httpd/conf/tmp-we-retail.dir to /etc/httpd/conf/we-retail.dir
line No 19,Move the file from /etc/httpd/conf/tmp-we-retail.pag to /etc/httpd/conf/we-retail.pag
From Line 12 to Line 19 will execute for geometrixx also and for all the websites you will define in the above script.

2.Add a rewrite rule in the /etc/conf.d/rewrites/we_retail_base_rewrites.rules
# Rewrite rules
RewriteMap map.legacy dbm:/etc/httpd/conf/
RewriteCond ${map.legacy:$1} !=""
RewriteRule ^(.*)$      ${map.legacy:$1|/} [L,R=301,NE]
If you are managing multiple sites, in every domain redirect.rules file you need to change the /etc/httpd/conf/ file to the corresponding domain map file.

3. How to set cron expression to execute the above script on an hourly basis.
To open the cron file run the command:
sudo crontab -e
sudo /bin/crontab -e
A file gets opened and you can add your cron expression like shown below.I have set the cron expression on hourly basis. 
0 * * * * sh /etc/httpd/conf.d/redirects/redirect-map.txt  2>&1 /var/log/httpd/map-update-cron.log

Fig: Screenshot for the cron expression in apache

When you do all the configuration, you need to manually run the bash script one time by running the command “sh redirect-map.txt”

Because the rewrite rule try to fetch map file which doesn’t gets created by then, may be your cron job will create it in an hour. So run one time manually to restart the Apache server and later cron job can take care of this activity on an interval.

Vanity URL Issue: As you know that vanity URL’s can not be duplicated within the whole AEM. AEM can only have one unique vanity and in the case of Multiple sites, we may have requirements of having the same vanity for two domains. In this case also in place of vanity, you can manage this in 301 redirect map file for both domains and as every website map file is different so there won't be any conflict.

Limitations of 301 Redirects in Redirect Map Manager:
301 Redirect Map is really a cool feature but it has some limitations.
1. This is one to one mapping and we can not manage a regex here. So if we have 1000 of URL’s need to redirect in a particular pattern you can not manage in Redirect Map. For this, you have to manage it in Apache level.So create a file and add all the regex redirect URL’s like shown below.
RewriteRule ^/en/index(.*)html$  /en/home.html [R=301,L]
Include the file in the rewrite file of a particular website.

Note: All the directories I mentioned above are as per AMS Servers directory structure.
If you have different folder structure you can manage as per your need.

Note: Redirect Map Manager is not an AEM Feature but an ACS Commons feature.
So you need to install ACS Commons package in your AEM Server.

Note: When you made any change in Apache configuration, don’t directly restart.
Run a command “httpd-t” to check all the syntax first. If “Syntax Ok” then
only restart otherwise the Apache will go down if the syntax is not OK.

shivani@dispatcher2apsoutheast1:~ httpd -t
Syntax OK

Conclusion and Benefits of Using Redirect Map Manager
1. If you are managing 301 redirects like this, you don't need to manage 301 redirects at the page properties level. If there is any page in AEM, which you want to redirect just configure the page in the redirect Map Manager.

2. Through this approach you can give an author the privilege that if they miss out any 301 redirection, they can do it anytime they want.

3. If there are many vanity URL’s and because so many vanity URL’s impact the performance of the server, you can use 301 redirection in place of vanities.
4. You can use same vanities for different domains sharing the same AEM Server.

Hope it will help you guys !!
Thanks and Happy Learning.


  1. Awesome Job, Shivani! Great explanation !! Really helpful !!!

  2. Hi Shivani,
    Can we have the data from following path "/etc/acs-commons/redirect-maps/${MAP_FILE}/jcr:content.redirectmap.txt" cached in the dispatcher?

  3. Hi,

    I have around 1000 pages which is something like this-

    source page- content/abc/content/at/de/test/insights/articles/equity/2020/robotics-automation-at.html

    I want to implement 301 redirect 

    target page- content/abc/content/at/de/test/insights/articles/equity/2020/robotics-automation.html

    how can I implement this.

    1. If you know the answer please sahre it with me....bcz I have to implement the same in my project at dispatcher/apache.