Contact lists

Current version: 9.0

Contact list definitions are managed by the Sitecore.Marketing.Definitions.ContactLists.ContactListDefinitionManager class.

Accessing the ContactListDefinitionManager

The ContactListDefinitionManager is available from the Sitecore DI container. It is preferable to include a parameter of type DefinitionManagerBase<IContactListDefinition, ContactListDefinitionRecord> in the constructor of your class and pull your class from the container, allowing the container to resolve the instance for you:

RequestResponse

public MyClass(DefinitionManagerBase<IContactListDefinition, ContactListDefinitionRecord> contactListDefinitionManager)
{
        ...
}

If you cannot use the container to construct your class, you can use the service locator. This class is also available in the Sitecore DI container:

RequestResponse

using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions;

ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<IContactListDefinition>();

Defining a contact list

A contact list is defined using types from the Sitecore.Marketing.Definitions.ContactLists namespace.

RequestResponse

using Sitecore.Marketing.Definitions.ContactLists;
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace Documentation
{
    public class AddContactList
    {
        public void Example()
        {
            Guid contactListId = Guid.NewGuid(); // Contact list ID
            CultureInfo contactListCulture = new CultureInfo("es"); // Contact list culture
            string contactListName = "Newly created contact list"; // Contact list name
            DateTime creationDate = DateTime.UtcNow; // Contact list creation date
            string createdBy = "sitecore\admin"; // Contact list creator

            ContactListDefinition contactList = new ContactListDefinition(contactListId, "Contact list item name", contactListCulture, contactListName, creationDate, createdBy);

            contactList.Owner = "sitecore\\maw";
            contactList.Type = "Folder";
        }
    }
}

Important

All ContactListDefinition properties except Type and Owner have been marked obsolete but not removed - this is to support migration for components such as List Manager. Be aware that some properties might be removed or moved in later releases.

Saving a contact list

Once you have defined a contact list you may save it by calling the SaveAsync() method on the definition manager.

RequestResponse

using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions.ContactLists;
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions;

namespace Documentation
{
        public class SaveContactList
        {
                public async void Example()
                {
                        Guid contactListId = Guid.NewGuid(); // Contact list ID
                        CultureInfo contactListCulture = new CultureInfo("es"); // Contact list culture
                        string contactListName = "Newly created contactList"; // Contact list name
                        DateTime creationDate = DateTime.UtcNow; // Contact list creation date
                        string createdBy = "sitecore\admin"; // Contact list creator

                        ContactListDefinition contactList = new ContactListDefinition(contactListId, "Contact list item name", contactListCulture, contactListName, creationDate, createdBy);

                        contactList.Owner = "sitecore\\maw";
                        contactList.Type = "Folder";

                        IDefinitionManager<IContactListDefinition> manager = ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<IContactListDefinition>();

                        await manager.SaveAsync(contactList);
                }
        }
}

You can also optionally activate the contact list during save by passing true to the second parameter of the SaveAsync() method:

RequestResponse

manager.SaveAsync(contactList, true);

Activating a contact list

Contact lists must be activated before they are available for use outside of Experience Manager. Contact lists can be activated when they’re saved by passing true to the activate (second) parameter of the SaveAsync() method:

RequestResponse

manager.SaveAsync(contactList, true);

Contact lists can also be activated without calling save, using the ActivateAsync() method:

RequestResponse

manager.ActivateAsync(contactListId);

The ActivateAsync() method takes the ID of the contact list and does not require the contact list definition model.

Deleting a contact list

To delete a contact list, use the Delete() method on the manager. Individual cultures cannot be deleted from the definition, only the entire definition. The culture provided to the method call should be either null (default value) or CultureInfo.InvariantCulture.

RequestResponse

using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions.ContactLists;
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions;

namespace Documentation
{
        public class SaveContactList
        {
                public async void Example()
                {
                        Guid contactListId = Guid.NewGuid(); // Contact list ID

                        IDefinitionManager<IContactListDefinition> manager = ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<IContactListDefinition>();

                        manager.Delete(contactListId);
                }
        }
}

Get a contact list

A single contact list can be retrieved by its ID using one of the Get() methods on the manager.

RequestResponse

using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions.ContactLists;
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions;

namespace Documentation
{
        public class GetContactList
        {
                public async void Example()
                {
                        Guid contactListId = Guid.NewGuid(); // Contact list ID

                        IDefinitionManager<IContactListDefinition> manager = ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<IContactListDefinition>();

                        // Get 'en' contact list, including inactive versions
                        manager.Get(contactListId, new CultureInfo("en"), true);
                }
        }
}

Retrieve a contact list by its alias

You can also retrieve a contact list by its alias:

RequestResponse

CultureInfo contactListCulture = new CultureInfo("fr-fr");
var contactListDefinitionByAlias = definitionManager.GetByAlias("My alias", contactListCulture);

Update an existing contact list

To update an existing contact list definition, retrieve the contact list by ID, edit the contact list properties, and save/activate to use:

RequestResponse

using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions.ContactLists;
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions;

namespace Documentation
{
        public class UpdateContactList
        {
                public async void Example()
                {
                        Guid contactListId = Guid.NewGuid(); // Contact list ID

                        IDefinitionManager<IContactListDefinition> manager = ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<IContactListDefinition>();

                        // Get 'en' contact list, including inactive versions
                        var contactList = manager.Get(contactListId, new CultureInfo("en"), true);

                        contactList.Owner = "sitecore\\newowner";
                        contactList.Name = "New name";

            manager.SaveAsync(contactList, true);
                }
        }
}

Retrieving all contact lists

The .GetAll() method can be used to get all contact lists from the manager. As there may be a large number of definitions, this method supports paging. The return value is a single page of results.

RequestResponse

using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions.ContactLists;
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Sitecore.Marketing.Definitions;
using Sitecore.Marketing.Core;

namespace Documentation
{
        public class GetAllContactList
        {
                public async void Example()
                {
                        Guid contactListId = Guid.NewGuid(); // Contact list ID

                        IDefinitionManager<IContactListDefinition> manager = ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<IContactListDefinition>();

                        // Get 'en' contact list, including inactive versions
                        var contactList = manager.Get(contactListId, new CultureInfo("en"), true);

                        // Get All with defaults which will be first page, page size 20, latest active versions only
                        ResultSet<DefinitionResult<IContactListDefinition>> contactLists = manager.GetAll(new CultureInfo("da"), new RetrievalParameters<IContactListDefinition, string>());

                        // Get page 2
                        ResultSet<DefinitionResult<IContactListDefinition>> page2contactLists = manager.GetAll(new CultureInfo("da"), new RetrievalParameters<IContactListDefinition, string>(pageNumber: 2));

                        // Include inactive versions
                        ResultSet<DefinitionResult<IContactListDefinition>> page1contactLists = manager.GetAll(new CultureInfo("da"), new RetrievalParameters<IContactListDefinition, string>(), true);
                }
        }
}

To access the results, use the DataPage property of the result.

RequestResponse

IContactListDefinition contactList = page1contactLists.DataPage.ElementAt(0);

The result also includes properties to expose the total number of definitions and the current page index and page size.

RequestResponse

long totalDefinitionCount = contactLists.Total;
int pageNumber = page1contactLists.PageNumber;
int pageSize = contactLists.Count;

Do you have some feedback for us?

If you have suggestions for improving this article,