Get interaction facets

Get interactions

Version:

You must specify which facets should be returned with an interaction or batch of interactions by passing an array of facet keys into the InteractionExpandOptions.

In the following example, the default IpInfo facet is requested as part of the interaction expand options:

var contacts = await client.GetAsync<Interaction>(references, new InteractionExecutionOptions(new Sitecore.XConnect.InteractionExpandOptions(IpInfo.DefaultFacetKey)));

A facet is added to the interaction’s Facets dictionary if the facet exists for that interaction. If the facet you requested is not defined in the model, xConnect will throw an exception when the request is executed. When the interaction or interactions have been returned, use the .GetFacet<T>() method on the interaction to retrieve the facet object:

IpInfo myFacetObject = contact.GetFacet<IpInfo>(IpInfo.DefaultFacetKey);

The method .GetFacet<T>() will return null if:

The facet was not requested as part of the InteractionExpandOptions when the interaction was initially retrieved
The facet has not set for a particular interaction
The combination of type and key is incorrect

The following example demonstrates how to retrieve and work with the IpInfo facet:

Note

All built-in facet models have a DefaultFacetKey property - for example, WebVisit.DefaultFacetKey.

using Sitecore.XConnect.Collection.Model;
using Sitecore.XConnect.Operations;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Sitecore.XConnect;
using System.Collections.ObjectModel;
using Sitecore.XConnect.Client;

namespace Documentation
{
    public class GetInteractionsWithFacets
    {
        public async void ExampleAsync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {

                    // Contact reference from ID
                    var contactRef = new Sitecore.XConnect.ContactReference(Guid.Parse("B9814105-1F45-E611-82E6-34E6D7117DCB"));
                    Sitecore.XConnect.InteractionReference interactionRef = new Sitecore.XConnect.InteractionReference(contactRef, Guid.Parse("DA2DA5F0-4348-E611-82E7-34E6D7117DCB"));

                    // Contact reference from identifier
                    var identifiedContactRef = new Sitecore.XConnect.IdentifiedContactReference("twitter", "myrtlesitecore");
                    Sitecore.XConnect.InteractionReference secondInteractionRef = new Sitecore.XConnect.InteractionReference(identifiedContactRef, Guid.Parse("E6067926-1F45-E611-82E6-34E6D7117DCB"));


                    var references = new List<Sitecore.XConnect.InteractionReference>()
                    {
                        interactionRef, secondInteractionRef
                    };

                    Task<ReadOnlyCollection<IEntityLookupResult<Interaction>>> interactionTask = client.GetAsync<Interaction>(references, new InteractionExecutionOptions(new InteractionExpandOptions(IpInfo.DefaultFacetKey)));

                    ReadOnlyCollection<IEntityLookupResult<Interaction>> interactions = await interactionTask;

                    foreach (var i in interactions)
                    {
                        IpInfo ipInfoFacet = i.Entity.GetFacet<IpInfo>(Sitecore.XConnect.Collection.Model.CollectionModel.FacetKeys.IpInfo);

                        var businessName = ipInfoFacet.BusinessName; // Do some work with facet values
                    }
                }
                catch (XdbExecutionException ex)
                {
                    // Manage exceptions
                }
            }
        }

        public void ExampleSync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {

                    // Contact reference from ID
                    var contactRef = new Sitecore.XConnect.ContactReference(Guid.Parse("B9814105-1F45-E611-82E6-34E6D7117DCB"));
                    Sitecore.XConnect.InteractionReference interactionRef = new Sitecore.XConnect.InteractionReference(contactRef, Guid.Parse("DA2DA5F0-4348-E611-82E7-34E6D7117DCB"));

                    // Contact reference from identifier
                    var identifiedContactRef = new Sitecore.XConnect.IdentifiedContactReference("twitter", "myrtlesitecore");
                    Sitecore.XConnect.InteractionReference secondInteractionRef = new Sitecore.XConnect.InteractionReference(identifiedContactRef, Guid.Parse("E6067926-1F45-E611-82E6-34E6D7117DCB"));

                    var references = new List<Sitecore.XConnect.InteractionReference>()
                    {
                        interactionRef, secondInteractionRef
                    };

                    IReadOnlyCollection<IEntityLookupResult<Interaction>> interactions = client.Get<Interaction>(references, new InteractionExecutionOptions(new InteractionExpandOptions(IpInfo.DefaultFacetKey)));

                    foreach (var i in interactions)
                    {
                        IpInfo ipInfoFacet = i.Entity.GetFacet<IpInfo>(Sitecore.XConnect.Collection.Model.CollectionModel.FacetKeys.IpInfo);

                        var businessName = ipInfoFacet.BusinessName; // Do some work with facet values
                    }
                }
                catch (XdbExecutionException ex)
                {
                    // Manage exceptions
                }
            }
        }
    }
}

All built-in facet models have a FacetKey attribute that associates the default facet key with the facet model.

[FacetKey(CollectionModel.FacetKeys.IpInfo)]
public class IpInfo : Facet

If a facet key is not specified, xConnect will fall back to the default value. Add the FacetKey attribute to your own facet models to mimic this behavior. In the following example, .Expand<IpInfo>() and .GetFacet<IpInfo>() are used without specifying a facet key.

Important

An exception will be thrown if the facet model does not have a FacetKey attribute.

using Sitecore.XConnect.Collection.Model;
using Sitecore.XConnect.Operations;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Sitecore.XConnect;
using System.Collections.ObjectModel;
using Sitecore.XConnect.Client;

namespace Documentation
{
    public class GetInteractionsWithFacetsDefaults
    {
        public async void ExampleAsync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {

                    // Contact reference from ID
                    var contactRef = new Sitecore.XConnect.ContactReference(Guid.Parse("B9814105-1F45-E611-82E6-34E6D7117DCB"));
                    Sitecore.XConnect.InteractionReference interactionRef = new Sitecore.XConnect.InteractionReference(contactRef, Guid.Parse("DA2DA5F0-4348-E611-82E7-34E6D7117DCB"));

                    // Contact reference from identifier
                    var identifiedContactRef = new Sitecore.XConnect.IdentifiedContactReference("twitter", "myrtlesitecore");
                    Sitecore.XConnect.InteractionReference secondInteractionRef = new Sitecore.XConnect.InteractionReference(identifiedContactRef, Guid.Parse("E6067926-1F45-E611-82E6-34E6D7117DCB"));


                    var references = new List<Sitecore.XConnect.InteractionReference>()
                    {
                        interactionRef, secondInteractionRef
                    };

                    Task<ReadOnlyCollection<IEntityLookupResult<Interaction>>> interactionTask = client.GetAsync<Interaction>(references, new InteractionExecutionOptions(new InteractionExpandOptions(IpInfo. DefaultFacetKey)));

                    ReadOnlyCollection<IEntityLookupResult<Interaction>> interactions = await interactionTask;

                    foreach (var i in interactions)
                    {
                        IpInfo ipInfoFacet = i.Entity.GetFacet<IpInfo>();

                        var businessName = ipInfoFacet.BusinessName; // Do some work with facet values
                    }
                }
                catch (XdbExecutionException ex)
                {
                    // Manage exceptions
                }
            }
        }

        public void ExampleSync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {

                    // Contact reference from ID
                    var contactRef = new Sitecore.XConnect.ContactReference(Guid.Parse("B9814105-1F45-E611-82E6-34E6D7117DCB"));
                    Sitecore.XConnect.InteractionReference interactionRef = new Sitecore.XConnect.InteractionReference(contactRef, Guid.Parse("DA2DA5F0-4348-E611-82E7-34E6D7117DCB"));

                    // Contact reference from identifier
                    var identifiedContactRef = new Sitecore.XConnect.IdentifiedContactReference("twitter", "myrtlesitecore");
                    Sitecore.XConnect.InteractionReference secondInteractionRef = new Sitecore.XConnect.InteractionReference(identifiedContactRef, Guid.Parse("E6067926-1F45-E611-82E6-34E6D7117DCB"));

                    var references = new List<Sitecore.XConnect.InteractionReference>()
                    {
                        interactionRef, secondInteractionRef
                    };

                    IReadOnlyCollection<IEntityLookupResult<Interaction>> interactions = client.Get<Interaction>(references, new InteractionExecutionOptions(new
InteractionExpandOptions(IpInfo. DefaultFacetKey)));

                    foreach (var i in interactions)
                    {
                        IpInfo ipInfoFacet = i.Entity.GetFacet<IpInfo>();

                        var businessName = ipInfoFacet.BusinessName; // Do some work with facet values
                    }
                }
                catch (XdbExecutionException ex)
                {
                    // Manage exceptions
                }
            }
        }
    }
}

Note

If you have used a facet model (such as IpInfo) to define multiple facets, consider storing the non-default facet keys as constants in your model class.

You must use the .SetFacet() extension method to set contact facets. For more information, see:

Note

Interaction facets cannot be updated once they have been set.

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

Get interaction facets

Get facets using the default facet key

Setting interaction facets and adding events