1. Work with contacts

Set contact facets

Version:

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.

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("[email protected]", 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("[email protected]", 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("[email protected]", true);
                            facet.PreferredKey = "Work";

                            // Set the updated facet
                            client.SetFacet(existingContact, EmailAddressList.DefaultFacetKey, facet);
                        }
                        else
                        {
                            // Facet is new
                            EmailAddressList emails = new EmailAddressList(new EmailAddress("[email protected]", 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("[email protected]", true);
                            facet.PreferredKey = "Work";

                            // Set the updated facet
                            client.SetFacet(existingContact, EmailAddressList.DefaultFacetKey, facet);
                        }
                        else
                        {
                            // Facet is new
                            EmailAddressList emails = new EmailAddressList(new EmailAddress("[email protected]", true), "Work");

                            client.SetFacet<EmailAddressList>(existingContact, EmailAddressList.DefaultFacetKey, emails);
                        }

                        client.Submit();
                    }

                }
                catch (XdbExecutionException ex)
                {
                    // Handle exception
                }
            }
        }
    }
}
If you have suggestions for improving this article, let us know!