Externalizing URLs

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 AEM as a Cloud Service instance cannot know its externally visible URL 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 article explains how to configure the Externalizer service and how to use it. For technical details of the service, please refer to the Javadocs.

Default Behavior of the Externalizer and How to Override

Out-of-the box, the Externalizer service has values such as author-p12345-e6789.adobeaemcloud.com and publish-p12345-e6789.adobeaemcloud.com.

To override such values, use Cloud Manager environment variables as described in the article Configuring OSGi for AEM as a Cloud Service and setting the predefined AEM_CDN_DOMAIN_AUTHOR and AEM_CDN_DOMAIN_PUBLISH variables.

Configuring the Externalizer Service

The Externalizer service allows you to centrally define the domain that can be used to programmatically prefix resource paths. The Externalizer service should only be used for applications with a single domain.


As when applying any OSGi configurations for AEM as a Cloud Service, the following steps should be performed on a local developer instance and then committed to your project code for deployment.

To define a domain mapping for the Externalizer service:

  1. Navigate to the Configuration Manager via:


  2. Click Day CQ Link Externalizer to open the configuration dialog box.

    The Externalizer OSGi configuration


    The direct link to the configuration is https://<host>:<port>/system/console/configMgr/com.day.cq.commons.impl.ExternalizerImpl

  3. Define a Domains 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]


    • scheme is usually http or https, but can be another protocol.

      • It is recommended to use https to enforce https links.
      • It will be used if the client code does not override the scheme when asking for externalization of a URL.
    • server is the host name (either a domain name or ip address).

    • port (optional) is the port number.

    • contextpath (optional) is only set if AEM is installed as a webapp under a different context path.

    For example: production https://my.production.instance

    The following mapping names are predefined and must always be set as AEM relies on them:

    • local - the local instance
    • author - the authoring system DNS
    • publish - the public facing website DNS

    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. It is useful to avoid hard coding such URLs across different places in a project’s codebase.

  4. Click Save to save your changes.

Using the Externalizer Service

This section shows a few examples of how the Externalizer service can be used.


No absolute links should be created in the context of HTML. Therefore this utility should not be used in such cases.

  • 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.

On this page