Sitecore Experience Platform

Set contact facets

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 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.

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 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)
                    {

                    }
                }
            }
        }
    }
}

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 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
                }
            }
        }
    }
}