Create a custom facet

Current version: 10.2

Note

If you are using Sitecore XP 10.2 or later, you can also create facets using the Codeless Schema Extensions module.

This topic describes how to create a facet model named FrequentFlyerInfo and use it to define a contact facet with the same key.

Important

Facet keys are case sensitive.

Create a class that inherits Sitecore.XConnect.Facet

Add one or more properties that adhere to xConnect’s type restrictions.

Important

If you are going to use your facet in the context of the tracker, it must be marked [Serializable].

RequestResponse

namespace Documentation
{
    [Serializable]
    public class FrequentFlyerInfo : Sitecore.XConnect.Facet
    {
        public FrequentFlyerStatus Status { get; set; }
        public string FrequentFlyerID { get; set; } // Example: ABC12345

        public enum FrequentFlyerStatus
        {
            Unknown = 0,
            Bronze,
            Silver,
            Gold
        }
    }
}

If necessary, use a constructor to indicate mandatory properties. In the following example, FrequentFlyerID is mandatory and has a private setter, which means it cannot be updated once it has been set:

Important

All facets must declare an empty constructor - this is an oData restriction. The constructor can be private.

RequestResponse

namespace Documentation
{
    [Serializable]
    public class FrequentFlyerInfo : Sitecore.XConnect.Facet
    {
        public FrequentFlyerInfo(string frequentFlyerId)
        {
            FrequentFlyerID = frequentFlyerId;
        }

        private FrequentFlyerInfo() { }

        public FrequentFlyerStatus Status { get; set; }
        public string FrequentFlyerID { get; private set; } // Example: ABC12345

        public enum FrequentFlyerStatus
        {
            Unknown = 0,
            Bronze,
            Silver,
            Gold
        }
    }
}

Decorate facet or facet properties with the [PIISensitive] or [DoNotIndex] attributes as necessary. For example, a contact’s passport number is PII data:

RequestResponse

namespace Documentation
{
    [Serializable]
    public class FrequentFlyerInfo : Sitecore.XConnect.Facet
    {
        public FrequentFlyerInfo(string frequentFlyerId)
        {
            FrequentFlyerID = frequentFlyerId;
        }

        private FrequentFlyerInfo() { }

        public FrequentFlyerStatus Status { get; set; }
        public string FrequentFlyerID { get; private set; } // Example: ABC12345

        [PIISensitive]
        public string PassportNumber { get; set; }

        public enum FrequentFlyerStatus
        {
            Unknown = 0,
            Bronze,
            Silver,
            Gold
        }
    }
}

Optionally, use the [FacetKey] attribute to define a default facet key. Default facet keys simplify usage of the xConnect Client API.

RequestResponse

using Sitecore.XConnect;

namespace Documentation
{
    [FacetKey(DefaultFacetKey)]
    public class FrequentFlyerInfo : Sitecore.XConnect.Facet
    {
        public const string DefaultFacetKey = "FrequentFlyerInfo";

        public FrequentFlyerInfo(string frequentFlyerId)
        {
            FrequentFlyerID = frequentFlyerId;
        }

        public FrequentFlyerStatus Status { get; set; }
        public string FrequentFlyerID { get; set; } // Example: ABC12345

        public enum FrequentFlyerStatus
        {
            Unknown = 0,
            Bronze,
            Silver,
            Gold
        }
    }
}

Note

Sitecore’s default facet keys are in a static class named Sitecore.XConnect.Collection.Model.CollectionModel.FacetKeys, alongside the core collection model.

Define the new facet in your collection model using the .DefineFacet() method. In the following example, the facet has been added to a model named SampleModel. If you are using the model in a Sitecore context, the model class must be added to the client configuration file.

RequestResponse

using Sitecore.XConnect;
using Sitecore.XConnect.Schema;

namespace Documentation
{
    public class SampleModel
    {
        public static XdbModel Model { get; } = SampleModel.BuildModel();

        private static XdbModel BuildModel()
        {
            XdbModelBuilder modelBuilder = new XdbModelBuilder("SampleModel", new XdbModelVersion(0, 1));

            modelBuilder.ReferenceModel(Sitecore.XConnect.Collection.Model.CollectionModel.Model);
            modelBuilder.DefineFacet<Contact, FrequentFlyerInfo>(FrequentFlyerInfo.DefaultFacetKey);

            return modelBuilder.BuildModel();
        }
    }
}

Warning

If you do not register your facet, you cannot use it. You will get errors such as ‘The type of this instance does not correspond to any type in the schema’.

Use the xConnect Client API to work with facets.

Sitecore ships with a number of built-in facets.

Do you have some feedback for us?

If you have suggestions for improving this article,

Create a custom facet

Create a facet model class

Define a custom facet in the model

Use custom facets