Externalizing URLs externalizing-urls
In AEM, the Externalizer is an OSGi service that lets you programmatically transform a resource path (for example, /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, see Javadocs.
Default Behavior of the Externalizer and How to Override default-behavior
Out-of-the box, the Externalizer service maps a handful of domain identifiers to absolute URL prefixes matching the AEM service URLs that have been generated for the environment, such as author https://author-p12345-e6789.adobeaemcloud.com
and publish https://publish-p12345-e6789.adobeaemcloud.com
. The base URLs for each of these default domains are read from environment variables defined by Cloud Manager.
For reference, the default OSGi configuration for com.day.cq.commons.impl.ExternalizerImpl.cfg.json
is effectively:
{
"externalizer.domains": [
"local $[env:AEM_EXTERNALIZER_LOCAL;default=http://localhost:4502]",
"author $[env:AEM_EXTERNALIZER_AUTHOR;default=http://localhost:4502]",
"publish $[env:AEM_EXTERNALIZER_PUBLISH;default=http://localhost:4503]",
"preview $[env:AEM_EXTERNALIZER_PREVIEW;default=http://localhost:4503]"
]
}
local
, author
, preview
, and publish
Externalizer domain mappings in the OSGi configuration must be preserved with the original $[env:...]
values listed above.com.day.cq.commons.impl.ExternalizerImpl.cfg.json
file to AEM as a Cloud Service that omits any of these out-of-the-box domain mappings may result in unpredictable application behavior.To override the preview
and publish
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_PUBLISH
and AEM_CDN_DOMAIN_PREVIEW
variables.
Configuring the Externalizer Service configuring-the-externalizer-service
The Externalizer service lets you 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.
To define a domain mapping for the Externalizer service:
-
Navigate to the Configuration Manager via:
https://<host>:<port>/system/console/configMgr
-
Click Day CQ Link Externalizer to open the configuration dialog box.
note note NOTE The direct link to the configuration is https://<host>:<port>/system/console/configMgr/com.day.cq.commons.impl.ExternalizerImpl
-
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]
Where:
-
scheme
is usually http or https, but can be another protocol.- Adobe recommends using https to enforce https links.
- It is 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 instanceauthor
- the authoring system DNSpublish
- the public facing website DNS
note note NOTE A custom configuration lets you add a new category, such as production
,staging
or even external non-AEM systems such asmy-internal-webservice
. It is useful to avoid hard coding such URLs across different places in a project’s codebase. -
-
Click Save to save your changes.
Using the Externalizer Service using-the-externalizer-service
This section shows a few examples of how the Externalizer service can be used.
-
To externalize a path with the ‘publish’ domain:
code language-java 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:
code language-java 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:
code language-java 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
-