Manage Large Scale Redirects in AEM as a Cloud Service

Problem Statement

We were migrating an old Salesforce-style knowledge base (URLs like /apex/ArticleDetails?) into AEM as a Cloud Service. Everything looked fine… until the business came back with a hard requirement:

“We have ~300 legacy article links still floating around. None of them can break. Fix it.”

That immediately pointed to one place: dispatcher rewrite rules.

And if you’ve worked with Apache + AEMaaCS dispatcher, you already know it’s not as simple as dropping a few RewriteRule lines and calling it done.

First Attempt (and why it failed)

The naive approach looks like this:

RewriteCond %{REQUEST_URI} =/apex/ArticleDetails [NC]
RewriteCond %{QUERY_STRING} (^|&)article=WaysToOpenAnAccount(&|$) [NC]
RewriteRule ^ /content/data-centre/us/en/home/our-products/current-accounts/online-bank-account-opening.article.html [R=301,L,QSD]

It works… for a couple of redirects.

But for 300 entries?

* Maintaining hundreds of hardcoded rules becomes painful.
* Every new redirect requires a dispatcher redeploy.
* Business teams can’t manage it without engineering help.

That wasn’t going to scale.

Solution

Use RewriteMap.

Instead of writing hundreds of conditional rewrite rules, keep a lookup file and let Apache resolve redirects based on the article slug.

Local Setup

Here’s what the local setup looked like:

RewriteMap articles dbm=sdbm:/tmp/rewrites/articles.map

RewriteCond %{REQUEST_URI} ^/apex/(s/)?ArticleDetails$ [NC]
RewriteCond %{QUERY_STRING} (^|&)article=([^&]+)(&|$)
RewriteCond ${articles:%2|NOT_FOUND} !NOT_FOUND

RewriteRule ^ ${articles:%2}.article.html [R=301,L,QSD]

What’s happening here:

* Apache extracts the value of article= from the query string.
* It checks that value in the articles map.
* If it finds a match, it redirects.
* If it doesn’t, the request continues normally.

So the dispatcher config stays clean, and the redirect list lives outside the rewrite logic.

Making It Work in AEM as a Cloud Service

Local dev was straightforward: I used httxt2dbm to convert a text file into DBM format and mounted it under /tmp/rewrites.

On AEMaaCS, that approach doesn’t work because you can’t SSH into dispatcher instances and drop files wherever you want. That’s where managed rewrite maps become extremely useful.

Step 1: Create a DAM asset for the redirect list

Create a text file in DAM:

/content/dam/redirectmaps/articles.txt

The format is simple: one mapping per line.

WaysToOpenAnAccount our-products/current-accounts/online-bank-account-opening
UpdateDebitCardPIN  our-products/debit-cards/how-to-update-pin

(Keep it consistent: slug destination-path-without-extension.)

Step 2: Add managed rewrite map config in dispatcher repo

Add the config file here:

dispatcher/src/opt-in/managed-rewrite-maps.yaml

And include something like:

maps:
  - name: articles.map
    path: /content/dam/redirectmaps/articles.txt
    ttl: 300
    wait: true

What happens next is the best part:

* AEMaaCS fetches the DAM text file from Publish.
* It converts the file into DBM format.
* It places the generated DBM under /tmp/rewrites/articles.map on each dispatcher.
* Your RewriteMap directive now has a real file to read from.

So if you want to add a new redirect tomorrow, you don’t touch dispatcher code. You just update the DAM file, publish it, and within a few minutes (based on ttl) the dispatcher picks it up.

No pipeline run, no redeploy, no downtime.

Point to Remember

Make sure the articles.txt asset is published to the Publish/Preview environment before deployment (or ship it as part of your initial rollout strategy).
If dispatcher can’t fetch the DAM asset, the map won’t build and redirects won’t resolve.

Lessons Learned

1. Don’t hardcode 300 rewrite rules. Use a RewriteMap.
2. Local Docker: build DBM using httxt2dbm and mount under /tmp/rewrites.
3. Cloud: store redirect list in DAM + configure managed-rewrite-maps.yaml. Let AEMaaCS generate the DBM on dispatcher.
4. Use [QSD] (Apache 2.4.65+) to drop the old query string cleanly after redirect.

Final Thought

This started as a panic moment (“oh no, 300 redirects”) and ended up becoming a solid pattern.

Now redirect maintenance is just a DAM update—something even non-dev teams can handle—while dispatcher rules stay stable and predictable. Sometimes the best fix isn’t writing more config. It’s using the platform feature that was built for exactly this problem.

Reference

https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/pipeline-free-url-redirects