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. 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.
Set a new facet on a new contact
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)
{
}
}
}
}
}
}
Set a new facet on an existing contact
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 ContactExecutionOptions(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 ContactExecutionOptions(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)
{
}
}
}
}
}
}
Update an existing facet on an existing contact
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 ContactExecutionOptions(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 ContactExecutionOptions(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
}
}
}
}
}