Create a custom facet
This topic describes how to create a facet model named FrequentFlyerInfo
and use it to define a contact facet with the same key.
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.
ImportantIf you are going to use your facet in the context of the tracker, it must be marked
[Serializable]
.RequestResponseshellnamespace 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:ImportantAll facets must declare an empty constructor - this is an oData restriction. The constructor can be private.
RequestResponseshellnamespace 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:RequestResponseshellnamespace 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.RequestResponsec#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 } } }
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();
}
}
}
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.