Walkthrough: Creating a custom predicate

Abstract

Guide to create custom predicates to find contacts using the segmentation engine.

This topic demonstrates how to create a custom predicate to find contacts using the segmentation engine.

In the example, the custom predicate finds contacts with a known preferred cinema that meets the following conditions:

  • The contact has at least one interaction.

  • The supplied cinema name matches the contact’s preferred cinema.

The example uses the following sample facet:

using System;
using System.Linq.Expressions;
using Sitecore.Framework.Rules;
using Sitecore.XConnect;
using Sitecore.XConnect.Segmentation.Predicates;

namespace Documentation.Examples
{
    // Contact facet that stores contact's preferred cinema name
    [Serializable]
    public class CinemaDetails : Facet
    {
        public const string DefaultFacetKey = "CinemaDetails";
        public string PreferredCinema { get; set; }
    }
}

This walkthrough describes how to:

  • Create a predicate class

  • Create a condition descriptor

  • Configure the Automation Engine

Create a predicate class

To create a predicate class:

  • Create a class that inherits from ICondition and IContactSearchQueryFactory as shown:

    Important

    You must use the InteractionsCache facet rather than the contact.Interactions property, because not all search providers support joins.

    using System;
    using System.Linq.Expressions;
    using Sitecore.Framework.Rules;
    using Sitecore.XConnect;
    using Sitecore.XConnect.Segmentation.Predicates;
    using Sitecore.XConnect.Collection.Model;
    using System.Linq;
    
    namespace Documentation.Examples
    {
        public class PreferredCinemaMatches : ICondition, IContactSearchQueryFactory
        {
            public string PreferredCinema { get; set; }
    
            // TIP: There are other operation types in 
            // theSitecore.XConnect.Segmentation.Predicates namespace
            public StringOperationType Comparison { get; set; }
    
            // Evaluates condition for single contact
            public bool Evaluate(IRuleExecutionContext context)
            {
                var contact = context.Fact<Contact>();
    
                return Comparison.Evaluate(contact.GetFacet<CinemaDetails>
                (CinemaDetails.DefaultFacetKey)?.PreferredCinema, PreferredCinema)
                && contact.Interactions.Any();
            }
    
            // Evaluates contact in a search context
            // IMPORTANT: Use InteractionsCache() facet rather than contact.Interactions 
            // as some search providers do not provide joins.
            public Expression<Func<Contact, bool>> 
            CreateContactSearchQuery(IContactSearchQueryContext context)
            {
                return contact => Comparison.Evaluate(contact.GetFacet<CinemaDetails>(
                CinemaDetails.DefaultFacetKey).PreferredCinema, PreferredCinema)
                && contact.InteractionsCache().InteractionCaches.Any();
            }
        }
    }

    Note

    In some instances, a predicate does not implement IContactSearchQueryFactory - for example, if the logic concerns data that is unique to the contact, such as an ID number or an email address.

Create a condition descriptor

To create a condition descriptor:

  1. Deploy the custom predicate DLL to all core roles - Content Management, Content Delivery, Processing, and Reporting.

  2. Choose a location for your condition under /sitecore/system/Settings/Rules/Definitions/Elements - for example, /sitecore/system/Settings/Rules/Definitions/Elements/XConnect - Contact Personal Details.

    Note

    The location of your condition determines which user interfaces the condition is available in.

  3. Create a condition using the /sitecore/templates/System/Rules/Condition template:

    Add a rule condition to the custom predicate.
  4. Fill in the Type and Text fields as shown - in this example, we are using a string comparison:

    Enter the rule condition Type and Text fields.

Configure the Automation Engine

To configure the Automation Engine:

  1. Deploy the custom predicate DLL to the Marketing Automation engine and Marketing Automation Operations service.

  2. Create a configuration file with the following XML and add it to the following paths:

    • \path\to\xconnect\App_data\jobs\continuous\AutomationEngine\App_Data\Config\sitecore\Segmentation

    • \path\to\xconnect\App_Data\Config\sitecore\Segmentation

    Important

    The file name must start with sc and end with .xml.

    The id node must match the ID of the condition item in Sitecore:

    <Settings>
        <Sitecore>
            <XConnect>
            <Services>
                <DescriptorLocator>
                <Options>
                    <PredicateDescriptors>
                        <PreferredCinemaMatches>
                            <id>{E9046292-BF68-4733-9FD4-10A74FB45E50}</id>
                            <type>
                                Documentation.Examples.PreferredCinemaMatches,
                                Documentation.Examples
                            </type>
                        </PreferredCinemaMatches>
                    </PredicateDescriptors>
                </Options>
                </DescriptorLocator>
            </Services>
            </XConnect>
        </Sitecore>
    </Settings>
            
  3. Restart the Marketing Automation service.

Note

Default predicates are in the sc.XConnect.Segmentation.Predicates.Model.xml configuration file.