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">
		<RedirectPagePath>/sitecore%20modules/Web/EXM/RedirectUrlPage.aspx</RedirectPagePath>
	</processor>
	<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">
		<RedirectPagePath>/sitecore%20modules/Web/EXM/RedirectUrlPage.aspx</RedirectPagePath>
		<UrlQueryKey ref="settings/setting[@name='QueryStringKey.RedirectUrl']/@value"/>
	</processor>
	<processor type="Sitecore.Modules.EmailCampaign.Core.Pipelines.GenerateLink.Hyperlink.EncryptQueryString, Sitecore.EmailCampaign">
		<param ref="queryStringEncryption" desc="queryStringEncryption"/>
	</processor>
</modifyHyperlink>

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:

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: 25days, EXM

Categorised in: EXM, Sitecore