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)); modelBuilder.ReferenceModel(Sitecore.XConnect.Collection.Model.CollectionModel.Model);
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);
EmailAddressList
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("spam@me.com", false) } }, }; client.SetFacet<EmailAddressList>(new FacetReference(contact, EmailAddressList.DefaultFacetKey), emailFacet);
Important
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);
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" }; 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
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
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).
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);
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.
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);
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); }