Implementing pipeline-free URL redirects

Last update: March 23, 2025
  • Applies to:
  • Experience Manager as a Cloud Service

CREATED FOR:

  • Beginner
  • Intermediate
  • Developer
  • User

Learn how to implement pipeline-free URL redirects in AEM as a Cloud Service to enable the marketing team to manage the redirects without needing a developer.

There are multiple options to manage URL redirects in AEM, for more information, see URL redirects.

The tutorial focuses on creating URL redirects as key-value pairs in a text file like Apache RewriteMap and uses AEM as a Cloud Service specific configuration to load them into the Apache/Dispatcher module.

Prerequisites

To complete this tutorial, you need:

  • AEM as a Cloud Service environment with version 18311 or higher.

  • The sample WKND Sites project must be deployed onto it.

Tutorial use case

For the demo purpose, let’s assume that the WKND marketing team is launching a new ski campaign. They would like to create short URLs for the ski adventure pages and manage them on their own like how they manage the content. They decided to use the pipeline-free URL redirects approach to manage the URL redirects.

Based on the marketing team’s requirements, the following are the URL redirects that need to be created.

Source URLTarget URL
/ski/us/en/adventures.html
/ski/northamerica/us/en/adventures/downhill-skiing-wyoming.html
/ski/westcoast/us/en/adventures/tahoe-skiing.html
/ski/europe/us/en/adventures/ski-touring-mont-blanc.html

Now, let’s see how to manage these URL redirects and required one-time Dispatcher configurations in AEM as a Cloud Service environment.

How to manage URL redirects

To manage the URL redirects there are multiple options available, let’s explore them.

Text file in DAM

The URL redirects can be managed as key-value pairs in a text file and uploaded to the AEM Digital Asset Management (DAM).

For example, the above URL redirects can be saved in a text file named skicampaign.txt and uploaded to the DAM @ /content/dam/wknd/redirects folder. Upon review and approval, the marketing team can publish the text file.

# Ski Campaign Redirects separated by the TAB character
/ski      /us/en/adventures.html
/ski/northamerica  /us/en/adventures/downhill-skiing-wyoming.html
/ski/westcoast   /us/en/adventures/tahoe-skiing.html
/ski/europe          /us/en/adventures/ski-touring-mont-blanc.html

Text file in DAM

ACS Commons - Redirect Map Manager

The ACS Commons - Redirect Map Manager provides a user-friendly interface to manage the URL redirects.

For example, the marketing team can create a new Redirect Maps page named SkiCampaign and add the above URL redirects using the Edit Entries tab. The URL redirects are available at /etc/acs-commons/redirect-maps/skicampaign/jcr:content.redirectmap.txt.

Redirect Map Manager

IMPORTANT
The ACS Commons version 6.7.0 or higher is required to use the Redirect Map Manager, for more information, see the ACS Commons - Redirect Manager.

ACS Commons - Redirect Manager

Alternatively, the ACS Commons - Redirect Manager also provides a user-friendly interface to manage the URL redirects.

For example, the marketing team can create a new configuration named /conf/wknd and add the above URL redirects using the + Redirect Configuration button. The URL redirects are available at /conf/wknd/settings/redirects.txt.

Redirect Manager

IMPORTANT
The ACS Commons version 6.10.0 or higher is required to use the Redirect Manager, for more information, see the ACS Commons - Redirect Manager.

How to configure the Dispatcher

To load the URL redirects as a RewriteMap and apply them to the incoming requests, the following Dispatcher configurations are required.

Enable Dispatcher module for flexible mode

First, verify that the Dispatcher module is enabled for flexible mode. The presence of USE_SOURCES_DIRECTLY file in the dispatcher/src/opt-in folder indicates that the Dispatcher is in flexible mode.

Load URL redirects as RewriteMap

Next, create a new configuration file managed-rewrite-maps.yaml at dispatcher/src/opt-in folder with the following structure.

maps:
- name: <MAPNAME>.map # e.g. skicampaign.map
    path: <ABSOLUTE_PATH_TO_URL_REDIRECTS_FILE> # e.g. /content/dam/wknd/redirects/skicampaign.txt, /etc/acs-commons/redirect-maps/skicampaign/jcr:content.redirectmap.txt, /conf/wknd/settings/redirects.txt
    wait: false # Optional, default is false, when true, the Apache waits for the map to be loaded before starting
    ttl: 300 # Optional, default is 300 seconds, the reload interval for the map

During the deployment, the Dispatcher creates the <MAPNAME>.map file in the /tmp/rewrites folder.

IMPORTANT
The file name (managed-rewrite-maps.yaml) and location (dispatcher/src/opt-in) should be exactly as mentioned above, think of it as a convention to follow.

Apply URL redirects to incoming requests

Finally, create or update the Apache rewrite config file to use the above map (<MAPNAME>.map). For example, let’s use the rewrite.rules file from the dispatcher/src/conf.d/rewrites folder to apply the URL redirects.

...
# Use the RewriteMap to define the URL redirects
RewriteMap <MAPALIAS> dbm=sdbm:/tmp/rewrites/<MAPNAME>.map

RewriteCond ${<MAPALIAS>:$1} !=""
RewriteRule ^(.*)$ ${<MAPALIAS>:$1|/} [L,R=301]
...