AEM 6.4 has reached the end of extended support and this documentation is no longer updated. For further details, see our technical support periods. Find the supported versions here.
In AEM, the Externalizer is an OSGI service that allows you to programmatically transform a resource path (e.g. /path/to/my/page
) into an external and absolute URL (for example, https://www.mycompany.com/path/to/my/page
) by prefixing the path with a pre-configured DNS.
Because an instance can not know its externally visible URL if it is running behind a web layer, and because sometimes a link has to be created outside of the request scope, this service provides a central place to configure those external URLs and build them.
This page explains how to configure the Externalizer service and how to use it. For more details, please refer to the Javadocs.
The Externalizer service allows you to centrally define multiple domains that can be used to programmatically prefix resource paths. Each domain is identified by a unique name that is used to programmatically reference the domain.
To define a domain mapping for the Externalizer service:
Navigate to the configuration manager via Tools, then Web Console, or enter https://<host>:<port>/system/console/configMgr.
Click Day CQ Link Externalizer to open the configuration dialog box.
The direct link to the configuration is https://<host>:<port>/system/console/configMgr/com.day.cq.commons.impl.ExternalizerImpl
Define a domain mapping: a mapping consists of a unique name that can be used in the code to reference the domain, a space and the domain:
<unique-name> [scheme://]server[:port][/contextpath]
, where:
For example: production https://my.production.instance
The following mapping names are predefined and must always be set as AEM relies on them:
A custom configuration allows you to add a new category, such as “production,” “staging,” or even external non-AEM systems such as “my-internal-webservice” and is useful to avoid hardcoding such URLs across different places in a project’s codebase.
Click Save to save your changes.
Adobe recommends that you add the configuration to the repository.
This section shows a few examples of how the Externalizer service can be used.
To get the Externalizer service in a JSP:
Externalizer externalizer = resourceResolver.adaptTo(Externalizer.class);
To externalize a path with the ‘publish’ domain:
String myExternalizedUrl = externalizer.publishLink(resolver, "/my/page") + ".html";
Assuming the domain mapping " publish https://www.website.com
", myExternalizedUrl ends up with the value " https://www.website.com/contextpath/my/page.html
".
To externalize a path with the ‘author’ domain:
String myExternalizedUrl = externalizer.authorLink(resolver, "/my/page") + ".html";
Assuming the domain mapping " author https://author.website.com
", myExternalizedUrl ends up with the value " https://author.website.com/contextpath/my/page.html
".
To externalize a path with the ‘local’ domain:
String myExternalizedUrl = externalizer.externalLink(resolver, Externalizer.LOCAL, "/my/page") + ".html";
Assuming the domain mapping " local https://publish-3.internal
", myExternalizedUrl ends up with the value " https://publish-3.internal/contextpath/my/page.html
".
You can find more examples in the Javadocs.