Create a custom personalization token

Last updated Wednesday, December 20, 2017 in Email Experience Manager for Developer

In the Email Experience Manager (EXM), you can use tokens to personalize your email campaign messages. For example, in 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.

To create a custom token, you must:

Create a custom contact facet

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 your 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);
    }
} }
  1. 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>

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:

  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;
        }
    }
    }

Now, you can 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.

Send feedback about the documentation to docsite@sitecore.net.