Set contact facets
How to use the xConnect Client API to set contact facet values.
Use the client.SetFacet()
method to create or update a contact facet.
When you use a default facet value, the value isn't stored in the shard databases (xDB). Instead, the default value is populated when the facet is retrieved using xConnect. Examples of default values include false
for a Boolean field, and 0
for an int32 type field.
Keep the following in mind when updating an existing contact’s facets:
If you are updating an existing facet on an existing contact, you request that facet as part of the
ContactExpandOptions
If you are setting a facet for the first time on an existing contact, you do not need to request that facet as part of the
ContactExpandOptions
To update a contact facet that has already been set, you must retrieve the existing facet object and set individual properties - overwriting the entire facet or setting it to null will result in an exception
Important
Facets are available in the contact’s Facets
collection immediately after SubmitAsync()
/ Submit()
succeeds.
In the following example, three facets are added to a new contact. The example demonstrates how to use each of the client.SetFacet()
overloads.
using Sitecore.XConnect; using Sitecore.XConnect.Client; using Sitecore.XConnect.Collection.Model; namespace Documentation { public class AddFacetData { // Async example public async void ExampleAsync() { using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient()) { { try { Contact contact = new Contact(new ContactIdentifier("twitter", "myrtlesitecore", ContactIdentifierType.Known)); client.AddContact(contact); // Facet with a reference object, key is specified PersonalInformation personalInfoFacet = new PersonalInformation() { FirstName = "Myrtle", LastName = "McSitecore" }; FacetReference reference = new FacetReference(contact, PersonalInformation.DefaultFacetKey); client.SetFacet(reference, personalInfoFacet); // Facet without a reference, using default key EmailAddressList emails = new EmailAddressList(new EmailAddress("myrtle@test.test", true), "Home"); client.SetFacet(contact, emails); // Facet without a reference, key is specified AddressList addresses = new AddressList(new Address() { AddressLine1 = "Cool Street 12", City = "Sitecore City", PostalCode = "ABC 123" }, "Home"); client.SetFacet(contact, AddressList.DefaultFacetKey, addresses); // Submit operations as batch await client.SubmitAsync(); } catch (XdbExecutionException ex) { } } } } // Sync example public async void ExampleSync() { using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient()) { { try { Contact contact = new Contact(new ContactIdentifier("twitter", "myrtlesitecore", ContactIdentifierType.Known)); client.AddContact(contact); // Facet with a reference object, key is specified PersonalInformation personalInfoFacet = new PersonalInformation() { FirstName = "Myrtle", LastName = "McSitecore" }; FacetReference reference = new FacetReference(contact, PersonalInformation.DefaultFacetKey); client.SetFacet(reference, personalInfoFacet); // Facet without a reference, using default key EmailAddressList emails = new EmailAddressList(new EmailAddress("myrtle@test.test", true), "Home"); client.SetFacet(contact, emails); // Facet without a reference, key is specified AddressList addresses = new AddressList(new Address() { AddressLine1 = "Cool Street 12", City = "Sitecore City", PostalCode = "ABC 123" }, "Home"); client.SetFacet(contact, AddressList.DefaultFacetKey, addresses); // Submit operations as batch client.Submit(); } catch (XdbExecutionException ex) { } } } } } }
The following example demonstrates how to set the PersonalInformation
facet on an existing contact. In this example, the contact does not yet have a PersonalInformation
facet.
using Sitecore.XConnect; using Sitecore.XConnect.Client; using Sitecore.XConnect.Collection.Model; using System.Threading.Tasks; namespace Documentation { public class AddFacetDataToExistingContact { // Async example public async void ExampleAsync() { using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient()) { { try { Task<Contact> contactTask = client.GetAsync<Contact>(new IdentifiedContactReference("twitter", "myrtlesitecore"), new ContactExpandOptions(PersonalInformation.DefaultFacetKey)); Contact contact = await contactTask; if (contact.GetFacet<PersonalInformation>(PersonalInformation.DefaultFacetKey) == null) { // Only create new facet if one does not already exist PersonalInformation personalInfoFacet = new PersonalInformation() { FirstName = "Myrtle", LastName = "McSitecore" }; client.SetFacet(contact, PersonalInformation.DefaultFacetKey, personalInfoFacet); await client.SubmitAsync(); } } catch (XdbExecutionException ex) { } } } } // Sync example public void ExampleSync() { using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient()) { { try { Contact contact = client.Get<Contact>(new IdentifiedContactReference("twitter", "myrtlesitecore"), new ContactExpandOptions(PersonalInformation.DefaultFacetKey)); if (contact.GetFacet<PersonalInformation>(PersonalInformation.DefaultFacetKey) == null) { // Only create new facet if one does not already exist PersonalInformation personalInfoFacet = new PersonalInformation() { FirstName = "Myrtle", LastName = "McSitecore" }; client.SetFacet(contact, PersonalInformation.DefaultFacetKey, personalInfoFacet); client.Submit(); } } catch (XdbExecutionException ex) { } } } } } }
The following example demonstrates how to update an existing facet on an existing contact.
using Sitecore.XConnect.Collection.Model; using Sitecore.XConnect; using System; using System.Collections.Generic; using System.Threading.Tasks; using System.Linq; using Sitecore.XConnect.Client; namespace Documentation { public class UpdateFacet { public async void ExampleAsync() { using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient()) { try { // Retrieve contact var existingContactTask = client.GetAsync<Sitecore.XConnect.Contact>(new IdentifiedContactReference("twitter", "myrtlesitecore"), new Sitecore.XConnect.ContactExpandOptions(EmailAddressList.DefaultFacetKey)); Sitecore.XConnect.Contact existingContact = await existingContactTask; if (existingContact != null) { // Retrieve facet by name var facet = existingContact.GetFacet<EmailAddressList>(EmailAddressList.DefaultFacetKey); if (facet != null) { // Change facet properties facet.PreferredEmail = new EmailAddress("myrtle@test.test", true); facet.PreferredKey = "Work"; // Set the updated facet client.SetFacet(existingContact, EmailAddressList.DefaultFacetKey, facet); } else { // Facet is new EmailAddressList emails = new EmailAddressList(new EmailAddress("myrtle@test.test", true), "Work"); client.SetFacet<EmailAddressList>(existingContact, EmailAddressList.DefaultFacetKey, emails); } await client.SubmitAsync(); } } catch (XdbExecutionException ex) { // Handle exception } } } public void ExampleSync() { using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient()) { try { // Retrieve contact Sitecore.XConnect.Contact existingContact = client.Get<Sitecore.XConnect.Contact>(new IdentifiedContactReference("twitter", "myrtlesitecore"), new Sitecore.XConnect.ContactExpandOptions(EmailAddressList.DefaultFacetKey)); if (existingContact != null) { // Retrieve facet by name var facet = existingContact.GetFacet<EmailAddressList>(EmailAddressList.DefaultFacetKey); if (facet != null) { // Change facet properties facet.PreferredEmail = new EmailAddress("myrtle@test.test", true); facet.PreferredKey = "Work"; // Set the updated facet client.SetFacet(existingContact, EmailAddressList.DefaultFacetKey, facet); } else { // Facet is new EmailAddressList emails = new EmailAddressList(new EmailAddress("myrtle@test.test", true), "Work"); client.SetFacet<EmailAddressList>(existingContact, EmailAddressList.DefaultFacetKey, emails); } client.Submit(); } } catch (XdbExecutionException ex) { // Handle exception } } } } }