Email Experience Manager

Creating a custom personalization token

Abstract

Create custom personalization tokens that you can replace with appropriate values from user profiles.

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 facetCreate a custom facet

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

  1. 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) 
            : base(taskPool, recipientValidator, contactService, dataProvider, itemUtil, eventDataService, dispatchManager)
        {
            _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, MyCustomFacet.DefaultFacetKey);
        }
    } }
  2. 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" />
    </dispatchTask>

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:

  1. 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" />
    
  2. 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.Configure the Import contacts wizard to include custom contact facetsConfigure the Import contacts wizard to include custom contact facets