Create a custom personalization token

Version:

In the Email Experience Manager (EXM), you can use tokens to personalize your email campaign messages. For example, at the beginning of a message, you can use the token $name$ in the greeting so that when you send your email campaign, the token is replaced with the name of the contact.

If you want to use tokens that are not available by default, you can create a custom token that you can use for your email campaigns.

Note

For custom tokens to be replaced in the online Preview mode, you must extend the getContact pipeline.

To create a custom token, you must:

In the Sitecore Experience Database, you can extend the contact with your own custom data by creating a new custom contact facet.

Create a custom dispatch task

To load custom facets that you just created, you must:

Override the default dispatch task in the Sitecore.EmailExperience.ContentManagement.config file.

For example:

namespace FooBar
{
public class CustomDispatchTask : DispatchTask
{
    private IContactService _contactService;
    public CustomDispatchTask([NotNull] ShortRunningTaskPool taskPool, [NotNull] IRecipientValidator recipientValidator, [NotNull] IContactService contactService, [NotNull] EcmDataProvider dataProvider, [NotNull] ItemUtilExt itemUtil, [NotNull] IEventDataService eventDataService, [NotNull] IDispatchManager dispatchManager), [NotNull] EmailAddressHistoryManager emailAddressHistoryManager, [NotNull] IRecipientManagerFactory recipientManagerFactory, [NotNull] SentMessageManager sentMessageManager) 
 
        : base(taskPool, recipientValidator, contactService, dataProvider, itemUtil, eventDataService, dispatchManager), emailAddressHistoryManager, recipientManagerFactory, sentMessageManager)
    {
        _contactService = contactService;
    }
    protected override IReadOnlyCollection<IEntityLookupResult<Contact>> GetContacts(List<DispatchQueueItem> dispatchQueueItems)
    {
        return _contactService.GetContacts(dispatchQueueItems.Select(x => x.ContactIdentifier), PersonalInformation.DefaultFacetKey, EmailAddressList.DefaultFacetKey, ConsentInformation.DefaultFacetKey, PhoneNumberList.DefaultFacetKey, ListSubscriptions.DefaultFacetKey, EmailAddressHistory.DefaultFacetKey,  ExmKeyBehaviorCache.DefaultFacetKey, MyCustomFacet.DefaultFacetKey);
    }
} }

In exm/dispatchTask, in the App_Config\Sitecore\EmailExperience\Sitecore.EmailExperience.ContentManagement.config file, replace the default dispatch task with your custom dispatchTask.

For example:

<dispatchTask type="FooBar.CustomDispatchTask, FooBar ">
<param ref="exm/dispatchFailedTaskPool"/>
<param desc="recipientValidator" ref="exm/recipientValidator" />
<param desc="contactService" ref="exm/contactService" />
<param desc="dataProvider" ref="exm/dataProvider" />
<param desc="itemUtil" ref="exm/itemUtil" />
<param desc="eventDataService" ref="exm/eventDataService" />
<param desc="dispatchManager" ref="exm/dispatchManager" />
<param desc="emailAddressHistoryManager" ref="exm/emailAddressHistoryManager" />
<param desc="recipientManagerFactory" ref="exm/recipientManagerFactory" />
<param desc="sentHistoryManager" ref="exm/sentHistoryManager" />

</dispatchTask>

Important

When you preview the email message for a specific recipient, custom tokens implemented using the CustomDispatchTask are not visible. Instead, use the Send a quick test feature on the Review tab.

Override the default token map

You must override the default implementation of the recipientPropertyTokenMap token map class that describes the bindings between tokens and properties of a contact.

To override the recipientPropertyTokenMap token map class and bind the token key to a property on your custom facet:

Replace or patch the recipients/recipientPropertyTokenMap element in App_Config\Sitecore\EmailExperience\Sitecore.EmailExperience.Core.config file with your custom token map.

For example:
<recipientPropertyTokenMap type="FooBar.CustomRecipientPropertyTokenMap, FooBar" singleInstance="true" />

Create your custom token map by adding your custom token.

For example:

namespace FooBar
{
public class CustomRecipientPropertyTokenMap : DefaultRecipientPropertyTokenMap
{
protected static readonly MethodInfo GetMyFacetValue = 
typeof(FacetExtensions).GetMethod(nameof(FacetExtensions.GetMyCustomFacetValue), new[] { typeof(MyCustomFacet) });
static CustomRecipientPropertyTokenMap()
{
if (TokenBindings == null)
{
TokenBindings = new Dictionary<Token, RecipientPropertyTokenBinding>();
}
RecipientPropertyTokenBinding customTokenBinding = RecipientPropertyTokenBinding.Build<MyCustomFacet>(new Token("customtokenkey"), null, GetMyFacetValue);
TokenBindings.Add(customTokenBinding.Token, customTokenBinding);
}
}
  public static class FacetExtensions
  {
    public static string GetMyCustomFacetValue (this MyCustomFacet facet)
    {
      return facet.SomeProperty;
    }
}
}

You can now use the $customtokenkey$ token in email messages and it will be replaced with the value that is stored on your custom facet for the relevant contact.

Note

If you want to import the new custom facet from a file, you can extend the import contacts wizard to include the custom contact facet as a new mapping field.

If you have suggestions for improving this article, let us know!

Create a custom personalization token

Create a custom contact facet

Create a custom dispatch task

Override the default token map