1. Facets

Use core collection model facets

Version:

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

Referencing the core collection model

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));
modelBuilder.ReferenceModel(Sitecore.XConnect.Collection.Model.CollectionModel.Model);

Using core collection model facets

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.

Contact facets

PersonalInformation (PersonalInformation)

The PersonalInformation facet does not have any mandatory properties.

PersonalInformation personal = new PersonalInformation();

personal.Birthdate = new DateTime(1901, 01, 20, 0, 0, 0, DateTimeKind.Utc);
personal.JobTitle = "xDB Enthusiast";
personal.LastName = "McSitecore";
personal.MiddleName = "";
personal.FirstName = "Myrtle";
personal.Gender = "Female";
personal.PreferredLanguage = "English";
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);

EmailAddressList 

var preferredEmail = new EmailAddress("[email protected]", true);
var preferredKey = "Work";

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

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

The preferred email is not included in the .Others list.

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

client.SetEmails(contact, emailFacet);

AddressList 

// 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);
Important

The preferred address is not listed in .Others.

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

client.SetAddresses(contact, addressList);

PhoneNumberList

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

PhoneNumber mainNumber = new PhoneNumber(countryCode, number)
{
    Extension = "5",
    AreaCode = "917"  
};

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

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

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

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

Note

The ConsentInformation facet changed in Sitecore 10.0.

The following example shows how to populate an instance of the ConsentInformation facet class and add two consent items to the dictionary - one for the default site (website) and one for a custom site (subsite):

var consentInformation = new ConsentInformation();

consentInformation.Consents.Add("website", new ConsentItem
{
    ConsentDateTime = DateTime.UtcNow,
    ConsentValue = 1 // Consent given
});

consentInformation.Consents.Add("subsite", new ConsentItem
{
    ConsentDateTime = DateTime.UtcNow,
    ConsentValue = 0 // Consent not given
});

consentInformation.Consents["website"].ConsentValue = 0; // Update consent
consentInformation.Consents["website"].ConsentDateTime = DateTime.UtcNow; // Update consent time

EXM provides extension methods to read and change the doNotMarket and consentRevoked values:

var doNotMarket = consentInformation.IsDoNotMarket();
var consentRevoked = consentInformation.IsConsentRevoked();

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

client.SetConsentInformation(contact, consent);

ListSubscriptions

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

subscriptions.Subscriptions.Add(subscription);

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).

AutomationPlanEnrollmentCache 

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.

Important

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).

Avatar

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

Calculated contact facets

The following calculated contact facets are available by default:

Important

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

Interaction facets

UserAgentInfo 

UserAGentInfo userAgentInfo = new UserAgentInfo();

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

IpInfo

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

ProfileScores

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

WebVisit

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

                client.AddContact(contact);

                // 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 = "www.google.com";
                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);

                webInteraction.Events.Add(pageView);

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

                webInteraction.Events.Add(pageView2);

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

                webInteraction.Events.Add(goal1);

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

                webInteraction.Events.Add(pageView3);

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

                // Add interaction
                client.AddInteraction(webInteraction);

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

LocaleInfo 

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

Facet get/set extension methods

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);
}
If you have suggestions for improving this article, let us know!