Use core collection model facets
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 = "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("[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);
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);
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);
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).
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.
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:
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);
}