Create a custom facet

Abstract

How to create a custom facet model and use it to define a contact facet with the same key.

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

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

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.

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:

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.

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.