Set contact facets
Abstract
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
ContactExpandOptionsIf 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
ContactExpandOptionsTo 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
}
}
}
}
}