1. Facets

Create a custom facet

Version:
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 facet model class

  1. Create a class that inherits Sitecore.XConnect.Facet

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

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

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

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

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

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

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

    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 a custom facet in the 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.

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 custom facets

Use the xConnect Client API to work with facets.

Sitecore ships with a number of built-in facets.

If you have suggestions for improving this article, let us know!