Use core collection model facets


How to use core collection model facets.

xConnect defines a number of built-in facets. These facets are located in the Sitecore.XConnect.Collection.Model namespace.

The following example demonstrates how to reference the Sitecore.XConnect.Collection.Model.CollectionModel.Model in your own model:

xdbModelBuilder modelBuilder = new XdbModelBuilder("ModelName", new XdbModelVersion(0,1));

To work with facets within the core collection model, use the default facet keys as shown:

var avatarFacet = contact.GetFacet<Avatar>(Avatar.DefaultFacetKey);

All built-in facets have a default facet key that is represented by a DefaultFacetKey property - for example, PersonalInformation.DefaultFacetKey.

PersonalInformation (PersonalInformation)

The PersonalInformation facet does not have any mandatory properties.

PersonalInformation personal = new PersonalInformation();

personal.Birthdate = new DateTime(1901, 01, 20).ToUniversalTime();
personal.JobTitle = "xDB Enthusiast";
personal.LastName = "McSitecore";
personal.MiddleName = "";
personal.FirstName = "Myrtle";
personal.Gender = "Female";
personal.PreferredLanguage = "dk-DK";
personal.Suffix = "the Magnificent";
personal.Title = "Miss";
personal.Nickname = "Myrtle the Cool";

client.SetFacet<PersonalInformation>(new FacetReference(contact, PersonalInformation.DefaultFacetKey), personal);

You can also use the .SetPersonal() extension on the client:

client.SetPersonal(contact, personal);


var preferredEmail = new EmailAddress("sample@sitecore.test", true);
var preferredKey = "Work";

var emailFacet = new EmailAddressList(preferredEmail, preferredKey)
    Others = new Dictionary<string, EmailAddress>()
        { "Spam",  new EmailAddress("", false) }

client.SetFacet<EmailAddressList>(new FacetReference(contact, EmailAddressList.DefaultFacetKey), emailFacet);


The preferred e-mail is not included in the .Others list.

You can also use the .SetEmails() extension on the client:

client.SetEmails(contact, emailFacet);


// Preferred address
Address preferredAddress = new Address()
    AddressLine1 = "Slartibartfast Mansion",
    AddressLine2 = "42",
    AddressLine3 = "Douglas Road",
    AddressLine4 = "Adams Common",
    City = "Sqornshellous",
    CountryCode = "UK",
    GeoCoordinate = new GeoCoordinate(51.507351f, -0.127758f),
    PostalCode = "AB1 2CD",
    StateOrProvince = "Dragonville"

AddressList addressList = new AddressList(preferredAddress, "Home");

Address workAddress = new Address()
    AddressLine1 = "44 Work Street",
    City = "Work City",
    CountryCode = "DK"

addressList.Others.Add("Work", workAddress);


The preferred address is not listed in .Others.

You can also use the .SetAddresses() extension on the client:

client.SetAddresses(contact, addressList);


var countryCode = "44";
var number = "(555) 555-5555"

PhoneNumber mainNumber = new PhoneNumber(countryCode, number)
    Extension = "5"

PhoneNumberList numbers = new PhoneNumberList(mainNumber, "Home");

PhoneNumber mobileNumber = new PhoneNumber()
    CountryCode = "44",
    Number = "07912345678"

numbers.Others.Add("Mobile", mobileNumber);


The preferred phone number is not included in the Others list.

You can also use the .SetPhoneNumbers() extension on the client:

client.SetPhoneNumbers(contact, numbers);


ConsentInformation consent = new ConsentInformation();

consent.ConsentRevoked = false;
consent.DoNotMarket = true;
consent.ExecutedRightToBeForgotten = false;

You can also use the .SetConsentInformation() extension on the client:

client.SetConsentInformation(contact, consent);


ListSubscriptions subscriptions = new ListSubscriptions();

var listId = Guid.NewGuid(); /* Replace with real list ID */
var isActive = true;
var added = DateTime.UtcNow;

ContactListSubscription subscription = new ContactListSubscription(added, isActive, listId);


You can use the .SetListSubscriptions() extension on the client to set this facet:

client.SetListSubscriptions(contact, subscriptions);

Getting contact list definitions

Each ContactListSubscription stores the list ID. If you want to access details about the list (such as the list name), use the contact list definition manager (this is part of the Marketing Operations API).

The AutomationPlanEnrollmentCache contains a contact’s current automation plan enrollments, including the activity they are enrolled in. This facet is set by the Automation Engine whenever a contact is enrolled in a new plan or activity.


Do not set this facet manually. It is updated by the Marketing Automation Operations API.

AutomationPlanEnrollmentCache enrollmentCache = new AutomationPlanEnrollmentCache();

foreach (var enrollment in enrollmentCache.ActivityEnrollments)
    Guid activityID = enrollment.ActivityId;
    Guid planID = enrollment.AutomationPlanDefinitionId;
    DateTime entryDate = enrollment.ActivityEntryDate; // Entry date for activity
    string contextKey = enrollment.ContextKey;

To retrieve this facet:

var facet = contact.GetFacet<AutomationPlanEnrollmentCache>(AutomationPlanEnrollmentCache.DefaultFacetKey);

Get plan and activity definitions

Each AutomationPlanEnrollment stores the activity ID and plan ID. If you want to access details about the plan or activity (such as names), use the automation plan definition manager (this is part of the Marketing Operations API).


var pictureByteArray = new byte[] { 0x20, 0x20, 0x20, 0x20, 0x20, 0x20, 0x20 };
var mimeType = "image/jpeg";

Avatar avatar = new Avatar(pictureByteArray, mimeType);

To retrieve this facet:

var facet = contact.GetFacet<Avatar>(Avatar.DefaultFacetKey);

You can also use the .SetAvatar() extension on the client:

client.SetAvatar(contact, avatar);

The following calculated contact facets are available by default:


You should never set the value of calculated facets - they are set by a service plugin each time an interaction is submitted to xConnect.


UserAGentInfo userAgentInfo = new UserAgentInfo();

userAgentInfo.CanSupportTouchScreen = true;
userAgentInfo.DeviceType = "Mobile";
userAgentInfo.DeviceVendor = "HTC"
userAgentInfo.DeviceVendorHardwareModel = "HTC Desire"


var ipAddress = "8, 8, 8, 8";

IpInfo ipInfo = new IpInfo(ipAddress);

ipInfo.Isp = "Super Duper Internet";
ipInfo.Latitude = 55.673977;
ipInfo.Longitude = 12.568730;
ipInfo.MetroCode = "408";
ipInfo.AreaCode = "205";
ipInfo.BusinessName = "Bizniz";
ipInfo.City = "Super City";
ipInfo.Country = "Narnia";
ipInfo.PostalCode = "12A 24B";
ipInfo.Region = "Icy Plains";
ipInfo.Url = "host.local";
ipInfo.Dns = "dnsvalue";

To retrieve this facet:

var facet = interaction.GetFacet<IpInfo>IpInfo.DefaultFacetKey);

You can also use the .SetIpInfo() extension on the client:

client.SetIpInfo(interaction, ipInfo);


ProfileScore profileScore = new ProfileScore()
    MatchedPatternId = Guid.NewGuid(), // Guid of matched profile
    ProfileDefinitionId = Guid.NewGuid(), // Guid of profile
    Score = 1.9f,
    ScoreCount = 3,
    Values = new Dictionary<Guid, float>() { { Guid.NewGuid(), 1.2f }, { Guid.NewGuid(), 1.2f } }

ProfileScores profiles = new ProfileScores();

profiles.Scores.Add(Guid.NewGuid(), profileScore);

// NOTE: The Scores dictionary key should be the profile definition ID as a Guid


The WebVisit facet stores information about an interaction that occurred on a website. In a Sitecore context, this facet is populated by the tracker on session end. The following example demonstrates how to imitate a web visit by setting the WebVisit facet and adding a number of PageViewEvent events to the interaction:

using Sitecore.XConnect;
using Sitecore.XConnect.Collection.Model;
using System;

namespace Documentation
    public class SampleWebVisit
        public async void Example()
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
                // Create a new contact and set some facets
                var contact = new Contact();

                var personalInfoFacet = new PersonalInformation()
                    FirstName = "Myrtle",
                    LastName = "McSitecore"

                client.SetPersonal(contact, personalInfoFacet);


                // Create a new interaction for the contact
                Guid channelId = Guid.NewGuid();
                string userAgent = "Sample User Agent";
                Interaction webInteraction = new Interaction(contact, InteractionInitiator.Brand, channelId, userAgent);

                // Create a new web visit facet model
                var webVisitFacet = new WebVisit();

                // Populate data about the web visit
                webVisitFacet.Browser = new BrowserData() { BrowserMajorName = "Chrome", BrowserMinorName = "Desktop", BrowserVersion = "22.0" };
                webVisitFacet.Language = "en";
                webVisitFacet.OperatingSystem = new OperatingSystemData() { Name = "Windows", MajorVersion = "10", MinorVersion = "4" };
                webVisitFacet.Referrer = "";
                webVisitFacet.Screen = new ScreenData() { ScreenHeight = 1080, ScreenWidth = 685 };
                webVisitFacet.SearchKeywords = "sitecore";
                webVisitFacet.SiteName = "website";

                var itemId = Guid.NewGuid();
                var itemVersion = 5;

                // First page view
                 pageView = new PageViewEvent(new DateTime(2016, 10, 10, 13, 20, 22).ToUniversalTime(), itemId, itemVersion, "en");

                pageView.ItemLanguage = "en";
                pageView.Duration = new TimeSpan(3000);


                var secondItemId = Guid.NewGuid();
                var secondItemVersion = 2;

                // Second page view
                PageViewEvent pageView2 = new PageViewEvent(new DateTime(2016, 10, 10, 13, 21, 22).ToUniversalTime(), secondItemId, secondItemVersion, "en");

                pageView.ItemLanguage = "en";
                pageView.Duration = new TimeSpan(3200);


                // First goal, associated with second page view
                Goal goal1 = new Goal(Guid.NewGuid(), new DateTime(2016, 10, 10, 13, 22, 22).ToUniversalTime());

                goal1.ParentEventId = pageView2.Id;


                var thirdItemId = Guid.NewGuid();
                var thirdItemVersion = 2;

                // Third page view
                PageViewEvent pageView3 = new PageViewEvent(new DateTime(2016, 10, 10, 13, 22, 22).ToUniversalTime(), thirdItemId, thirdItemVersion, "en");

                pageView.ItemLanguage = "en";
                pageView.Duration = new TimeSpan(1200);


                // Set web visit facet on interaction
                client.SetWebVisit(webInteraction, webVisitFacet);

                // Add interaction

                // Submit contact and interaction
                await client.SubmitAsync(); // Synchronous version - client.SubmitAsync().GetAwaiter().GetResult();


LocaleInfo localeInfo = new LocaleInfo();

localeInfo.TimeZoneOffset = new TimeSpan(200);
localeInfo.GeoCoordinate = new GeoCoordinate(1.11111f, 2.22222f);

You can also use the .SetLocaleInfo() extension on the client:

client.SetLocaleInfo(interaction, localeInfo);

Add usingSitecore.XConnect.Collection.Model to your class to access a number of extension methods for contacts, interactions, and the xConnect client that make it easier to get and set built-in facets. For example, myContact.Personal() calls the following method:

public static PersonalInformation Personal(this Contact c)
    return c.GetFacet<PersonalInformation>(PersonalInformation.DefaultFacetKey);

Similarly, client.SetAddresses(myContactObject,myFacetObject) calls the following method:

public static SetFacetOperation<AddressList> SetAddresses(this XdbContext context, IEntityReference<Contact> contact, AddressList facet)
    return context.SetFacet(new FacetReference(contact, PersonalInformation.DefaultFacetKey), facet);