Hacking Sitecore and Life one pipeline at a time!

Hostname Mapper: Making URL’s Properly

Link Generation In Sitecore

Without this post getting long winded, and off topic, Sitecore Email Experience Manager uses Sitecore’s own API for figuring out and building links that are contained in emails generated by EXM.

This process is called LinkManager and there are several blogs out in the wild that help with augmenting this process and understanding it.  However, the root of how LinkManager figures out URL’s is by utilizing Sitecore’s Site definition. However, because of where the EXM Manager Root might reside, LinkManager might have a really hard time understanding how to resolve it.

Link Generation in EXM

To fully understand how link creation works in EXM, one will need to examine the pipeline that determines it. This pipeline is called the <modifyHyperlnk> pipeline. This pipeline serves a couple of purposes:

  • Mapping the Correct Hostname
    • For both Preview Links as well as Dispatched Links
  • Creating a Redirect Link
    • For tracking, email opens and click tracking
  • Encrypting the link
    • To ensure that identifying information is not readable.

To fully understand this, we would need to inspect the <modifyHyperlink> pipeline.  Oh look, it’s right there!

<modifyHyperlink patch:source="Sitecore.EmailExperience.Core.config">
	<processor type="Sitecore.Modules.EmailCampaign.Core.Pipelines.GenerateLink.Hyperlink.SkipAnchorLinks, Sitecore.EmailCampaign"/>
	<processor type="Sitecore.Modules.EmailCampaign.Core.Pipelines.GenerateLink.SetServerUrl, Sitecore.EmailCampaign" resolve="true"/>
	<processor type="Sitecore.Modules.EmailCampaign.Core.Pipelines.GenerateLink.Hyperlink.SkipAlreadyProcessedHyperlink, Sitecore.EmailCampaign">
	<processor type="Sitecore.Modules.EmailCampaign.Core.Pipelines.GenerateLink.MapHostname, Sitecore.EmailCampaign" resolve="true"/>
	<processor type="Sitecore.Modules.EmailCampaign.Core.Pipelines.GenerateLink.Hyperlink.SetAnalyticsQueryStringParameters, Sitecore.EmailCampaign"/>
	<processor type="Sitecore.Modules.EmailCampaign.Core.Pipelines.GenerateLink.Hyperlink.HandleInternalLink, Sitecore.EmailCampaign"/>
	<processor type="Sitecore.Modules.EmailCampaign.Core.Pipelines.GenerateLink.GeneratePreviewLink, Sitecore.EmailCampaign"/>
	<processor type="Sitecore.Modules.EmailCampaign.Core.Pipelines.GenerateLink.Hyperlink.GenerateHyperlink, Sitecore.EmailCampaign">
		<UrlQueryKey ref="settings/setting[@name='QueryStringKey.RedirectUrl']/@value"/>
	<processor type="Sitecore.Modules.EmailCampaign.Core.Pipelines.GenerateLink.Hyperlink.EncryptQueryString, Sitecore.EmailCampaign">
		<param ref="queryStringEncryption" desc="queryStringEncryption"/>

There are two processors specifically that are important here: SetServerUrl and MapHostname. The reason these are important is that they begin to drive the basis for the URL that is created as part of the Redirect Link. It starts by taking the hostname of the server that EXM can identify. This becomes the URL of the CM server that the author is on.  This becomes problematic in complex scenarios, such as multi-site environments as well as multiple dispatch servers.

To facilitate more control over this process, Sitecore has introduced the Hostname Mapper

Hostname Mapper

This brings us to introducing the Hostname Mapper. This is a pattern that was built out of a complicated scenario where one could have multiple sites, running multiple language domain sites, and all of this was complicated further when an email message was previewed.  There needed to be a way to control these host names a bit more manually. 

In a nutshell, a Hostname Mapper item takes an original URL/Domain. This is the URL that Sitecore will use to match against to determine if it found the right configuration.  Then, if in Preview mode, Sitecore will use the Preview domain, and if dispatching the message, Sitecore will utilize the Public domain.

The Detailed Process

Sitecore has provided a lot of documentation around this new feature, first introduced in Sitecore EXM 3.5 and carried through to Sitecore 9.1. That documentation provides the following:

EXM checks and generates hyperlinks according to the following process that is specified in the modifyHyperlinkpipeline:

  • Ignore links that start with #, javascript: or mailto:

  • Determine the current ServerUrl, for example, https://cms.domain.com.

  • If the link is not absolute, prefix the ServerUrl to make it absolute.

  • Check the hostname against the following hostname mappings and if necessary, EXM replaces the hostname, for example, https://preview.domain.com for a test or https://www.domain.com for a dispatch.

    EXM checks the hostnames by using the following hostname mappings:

    • The manager roots generates mappings from the PreviewUrl to the BaseUrl.

    • The mappings created under /sitecore/system/Settings/Email/System/Hostname Mappings in the content tree.

    • The RendererUrl maps to the PreviewUrl or the BaseUrl of the email message’s manager root. TheRendererUrl is the hostname that EXM should use for rendering the email content and it defaults to the hostname of the current server.

For additional information about this, please reference Sitecore’s Documentation Site on Hostname Mapping

Managing the Unsubscribe

Tomorrow, we begin the next major mini-series Managing the Unsubscribe which is one of the most important pieces of managing a successful Sitecore EXM implementation.

Did You Miss EXM Live!?

You’re in luck!  You can now view EXM Live! On-Demand on YouTube!

Tagged as: ,

Categorised in: EXM, Sitecore

1 Response »


  1. 25 Days of Sitecore EXM | Sitecore Hacker

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Enter your email address to follow this blog and receive notifications of new posts by email.

Join 1,238 other subscribers

Blog Stats

  • 132,847 hits
Follow Sitecore Hacker on WordPress.com
Sitecore® and Own the Experience® are registered trademarks of Sitecore Corporation A/S in the U.S. and other countries.  This website is independent of Sitecore Corporation, and is not affiliated with or sponsored by Sitecore Corporation.
%d bloggers like this: