Walkthrough: Creating custom facets and events

Extending the xConnect collection model walkthrough series

Version:

This walkthrough is part five of the Extending the xConnect collection model walkthrough series. To complete this walkthrough, you must first complete walkthroughs part one, two, three, and four.

In this walkthrough, you are Sitecore Cinema, and you must extend the collection model to collect information from your visitors. The information relies on visitors swiping their loyalty card each time they interact with one of your cinemas, and as an incentive to visit, you offer free popcorn after 10 uses of the loyalty card.

The walkthrough describes how to:

Create the SitecoreCinema solution and class library project
Create the CinemaInfo interaction facet class
Create the CinemaVisitorInfo contact facet class
Create the WatchMovie outcome item
Create the WatchMovie outcome class
Create the BuyConcessions outcome item
Create the BuyConcessions outcome class
Create the UseSelfService event item
Create the UseSelfService event class
Create the SitecoreCinemaModel collection model class
Create the Console.Deploy console app project
Serialize SitecoreCinemaModel collection model
Create the Console.Journey console app project
Simulate a Sitecore Cinema visit

Note

In Sitecore 9.1.0, in the Sitecore.Xdb.Common.Web namespace:

Certificate**WebRequest**HandlerModifierOptions became Certificate**HttpClient**HandlerModifierOptions.
Certificate**WebRequest**HandlerModifier became Certificate**HttpClient**HandlerModifier.

Create the SitecoreCinema solution and class library project

To create the SitecoreCinema solution and class library project:

In Visual Studio with administrator privileges, create a new solution and class library project for .NET Framework called SitecoreCinema:
In Solution Explorer, right-click SitecoreCinema/References and click Add Reference.
In the Reference Manager window, click Browse and add the following references from your <xConnect instance>\bin\ folder:
- Sitecore.XConnect.Collection.Model.dll
- Sitecore.XConnect.Core
- Sitecore.XConnect.dll
Click OK.

Create the CinemaInfo interaction facet class

The CinemaInfo class is an interaction facet that contains information about the cinema visited during the interaction.

To create the CinemaInfo interaction facet class:

In Visual Studio with administrator privileges, in Solution Explorer, right-click the SitecoreCinema project and click Add, New Item.
In the Add New Item window:
- In the left pane, click Installed/Visual C# Items.
- In the middle pane, click Class.
- At the bottom, in the Name field, enter CinemaInfo.cs and click Add.

In the CinemaInfo.cs file, replace the content with the following code:

using Sitecore.XConnect;

namespace SitecoreCinema.Model.Collection
{
    [FacetKey(DefaultFacetKey)]
    public class CinemaInfo : Facet
    {
        public const string DefaultFacetKey = "CinemaInfo";
        public int CinemaId { get; set; }
    }
}

Save the CinemaInfo.cs file.

The CinemaVisitorInfo class is a contact facet that contains information about the visitor, such as loyalty ID.

To create the CinemaVisitorInfo contact facet class:

In Visual Studio with administrator privileges, in Solution Explorer, right-click the SitecoreCinema project and click Add, New Item.
In the Add New Item window:
- In the left pane, click Installed/Visual C# Items.
- In the middle pane, click Class.
- At the bottom, in the Name field, enter CinemaVisitorInfo.cs and click Add.

In the CinemaVisitorInfo.cs file, replace the content with the following code:

using Sitecore.XConnect;

namespace SitecoreCinema.Model.Collection
{
    [FacetKey(DefaultFacetKey)]
    public class CinemaVisitorInfo : Facet
    {
        public const string DefaultFacetKey = "CinemaVisitorInfo";
        public string FavoriteMovie { get; set; }
    }
}

Save the CinemaVisitorInfo.cs file.

Create the WatchMovie outcome item

To create the WatchMovie outcome item:

In the Marketing Control Panel, click Marketing Control Panel/Outcomes.
In the Options pane, click Outcome Definition.
In the Message window, enter WatchMovie and click OK.
In the Quick Info section, make a note of the item ID.

Create the WatchMovie outcome class

The WatchMovie outcome class triggers the WatchMovie outcome item from the Point-of-Sale system when the visitor buys a movie ticket.

To create the WatchMovie outcome class:

In Visual Studio with administrator privileges, in Solution Explorer, right-click the SitecoreCinema project and click Add, New Item.
In the Add New Item window:
- In the left pane, click Installed/Visual C# Items.
- In the middle pane, click Class.
- At the bottom, in the Name field, enter WatchMovie.cs and click Add.

In the WatchMovie.cs file, replace the content with the following code:

using Sitecore.XConnect;
using System;

namespace SitecoreCinema.Model.Collection
{
    public class WatchMovie : Outcome
    {
        public static Guid EventDefinitionId { get; } = new Guid("<WATCHMOVIE OUTCOME ITEM ID>");

        public WatchMovie(
            DateTime timestamp,
            string currencyCode,
            decimal monetaryValue
        ) : base(EventDefinitionId, timestamp, currencyCode, monetaryValue) { }

        // Entertainment Identifier Registry number (see https://eidr.org/)
        public string EIDR { get; set; }
    }
}

Insert the WatchMovie outcome item ID.
Save the WatchMovie.cs file.

Create the BuyConcessions outcome item

To create the BuyConcessions outcome item:

In the Marketing Control Panel, click Marketing Control Panel/Outcomes.
In the Options pane, click Outcome Definition.
In the Message window, enter BuyConcessions and click OK.
In the Quick Info section, make a note of the item ID.

Create the BuyConcessions outcome class

The BuyConcessions outcome class triggers the BuyConcessions outcome item from the Point-of-Sale system when the visitor buys concessions.

To create the BuyConcessions outcome class:

In Visual Studio with administrator privileges, in Solution Explorer, right-click the SitecoreCinema project and click Add, New Item.
In the Add New Item window:
- In the left pane, click Installed/Visual C# Items.
- In the middle pane, click Class.
- At the bottom, in the Name field, enter BuyConcessions.cs and click Add.

In the BuyConcessions.cs file, replace the content with the following code:

using Sitecore.XConnect;
using System;

namespace SitecoreCinema.Model.Collection
{
    public class BuyConcessions : Outcome
    {
        public static Guid EventDefinitionId { get; } = new Guid("<BUYCONCESSIONS OUTCOME ITEM ID>");

        public BuyConcessions(
            DateTime timestamp,
            string currencyCode,
            decimal monetaryValue
        ) : base(EventDefinitionId, timestamp, currencyCode, monetaryValue) { }

        public bool BoughtAlcoholicDrink { get; set; }
    }
}

Insert the BuyConcessions outcome item ID.
Save the BuyConcessions.cs file.

Create the UseSelfService event item

To create the UseSelfService event item:

In the Marketing Control Panel, click Marketing Control Panel/Events.
In the Options pane, click Event.
In the Message window, enter UseSelfService and click OK.
In the Quick Info section, make a note of the item ID.

Create the UseSelfService event class

The UseSelfService event class triggers the UseSelfService event item from the ticket machine when the visitor buys a movie ticket.

To create the UseSelfService event class:

In Visual Studio with administrator privileges, in Solution Explorer, right-click the SitecoreCinema project and click Add, New Item.
In the Add New Item window:
- In the left pane, click Installed/Visual C# Items.
- In the middle pane, click Class.
- At the bottom, in the Name field, enter UseSelfService.cs and click Add.

In the UseSelfService.cs file, replace the content with the following code:

using Sitecore.XConnect;
using System;

namespace SitecoreCinema.Model.Collection
{
    public class UseSelfService : Event
    {
        public static Guid EventDefinitionId { get; } = new Guid("<USESELFSERVICE EVENT ITEM ID>");
        public UseSelfService(DateTime timestamp) : base(EventDefinitionId, timestamp) { }
    }
}

Insert the UseSelfService event item ID.
Save the UseSelfService.cs file.

Create the SitecoreCinemaModel collection model class

To create the SitecoreCinemaModel collection model class:

In Visual Studio with administrator privileges, in Solution Explorer, right-click SitecoreCinema and click Add, New Item.
In the Add New Item window:
- In the left pane, click Installed/Visual C# Items.
- In the middle pane, click Class.
- At the bottom, in the Name field, enter SitecoreCinemaModel.cs and click Add.

In the SitecoreCinemaModel.cs file, replace the content with the following code:

using Sitecore.XConnect;
using Sitecore.XConnect.Schema;

namespace SitecoreCinema.Model.Collection
{
    public class SitecoreCinemaModel
    {
        public static XdbModel Model { get; } = BuildModel();

        private static XdbModel BuildModel()
        {
            XdbModelBuilder modelBuilder = new XdbModelBuilder("SitecoreCinemaModel", new XdbModelVersion(1, 0));

            modelBuilder.DefineFacet<Contact, CinemaVisitorInfo>(FacetKeys.CinemaVisitorInfo);
            modelBuilder.DefineFacet<Interaction, CinemaInfo>(FacetKeys.CinemaInfo);
            modelBuilder.DefineEventType<WatchMovie>(false);
            modelBuilder.DefineEventType<BuyConcessions>(false);
            modelBuilder.DefineEventType<UseSelfService>(false);
            modelBuilder.ReferenceModel(Sitecore.XConnect.Collection.Model.CollectionModel.Model);

            return modelBuilder.BuildModel();
        }
    }

    public class FacetKeys
    {
        public const string CinemaInfo = "CinemaInfo";
        public const string CinemaVisitorInfo = "CinemaVisitorInfo";
    }
}

Save the SitecoreCinemaModel.cs file.

Create the Console.Deploy console app project

The Console.Deploy console app serializes SitecoreCinemaModel to JSON format.

To create the Console.Deploy console app project:

In Visual Studio with administrator privileges, right-click the SitecoreCinema solution and click Add, New Project to create a new console app project for .NET Framework called Console.Deploy:
In Solution Explorer, right-click Console.Deploy/References and click Add Reference.
In the Reference Manager window, on the Projects tab, select SitecoreCinema.
In the Reference Manager window, click Browse and add the following references from your <xConnect instance>\bin\ folder:
- Sitecore.XConnect.Core.dll
- Sitecore.XConnect.dll
Click OK.
In Solution Explorer, double-click the Console.Deploy/Program.cs file.

In the Program.cs file, replace the content with the following code:

using System.IO;

namespace SitecoreCinema.Console.Deploy
{
    public class Program
    {
        public static void Main(string[] args)
        {
            System.Console.WriteLine("Generating your model ...");
            var model = SitecoreCinema.Model.Collection.SitecoreCinemaModel.Model;
            string filePath = "C:\\" + model.FullName + ".json";
            var serializedModel = Sitecore.XConnect.Serialization.XdbModelWriter.Serialize(model);
            File.WriteAllText(filePath, serializedModel);
            System.Console.WriteLine("Your model is here: " + filePath);
            System.Console.WriteLine("Press any key to continue!");
            System.Console.ReadKey();
        }
    }
}

Save the Program.cs file.

Serialize the SitecoreCinemaModel collection model

To serialize the SitecoreCinemaModel collection model:

In Visual Studio with administrator privileges, in Solution Explorer, right-click the Console.Deploy project and click Set as Startup Project.

Click Start to run the Console.Deploy app and wait for it to serialize the model:

A terminal with the model details in the app output.

The serialized model in the C:\SitecoreCinemaModel, 1.0.json file must contain the following:

{
  "Name": "SitecoreCinemaModel",
  "Version": "1.0",
  "References": [
    {
      "Name": "XConnect",
      "Version": "1.0"
    },
    {
      "Name": "Sitecore.XConnect.Collection.Model",
      "Version": "9.3"
    }
  ],
  "Types": {
    "SitecoreCinema.Model.Collection.CinemaVisitorInfo": {
      "Type": "Facet",
      "BaseType": "Sitecore.XConnect.Facet",
      "ClrType": "SitecoreCinema.Model.Collection.CinemaVisitorInfo, SitecoreCinema, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null",
      "Properties": {
        "FavoriteMovie": {
          "Type": "String"
        }
      }
    },
    "SitecoreCinema.Model.Collection.CinemaInfo": {
      "Type": "Facet",
      "BaseType": "Sitecore.XConnect.Facet",
      "ClrType": "SitecoreCinema.Model.Collection.CinemaInfo, SitecoreCinema, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null",
      "Properties": {
        "CinemaId": {
          "Type": "Int32"
        }
      }
    },
    "SitecoreCinema.Model.Collection.WatchMovie": {
      "Type": "Event",
      "BaseType": "Sitecore.XConnect.Outcome",
      "ClrType": "SitecoreCinema.Model.Collection.WatchMovie, SitecoreCinema, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null",
      "Properties": {
        "EIDR": {
          "Type": "String"
        }
      }
    },
    "SitecoreCinema.Model.Collection.BuyConcessions": {
      "Type": "Event",
      "BaseType": "Sitecore.XConnect.Outcome",
      "ClrType": "SitecoreCinema.Model.Collection.BuyConcessions, SitecoreCinema, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null",
      "Properties": {
        "BoughtAlcoholicDrink": {
          "Type": "Boolean"
        }
      }
    },
    "SitecoreCinema.Model.Collection.UseSelfService": {
      "Type": "Event",
      "BaseType": "Sitecore.XConnect.Event",
      "ClrType": "SitecoreCinema.Model.Collection.UseSelfService, SitecoreCinema, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null",
      "Properties": {}
    }
  },
  "Facets": [
    {
      "Target": "Contact",
      "Name": "CinemaVisitorInfo",
      "Type": "SitecoreCinema.Model.Collection.CinemaVisitorInfo"
    },
    {
      "Target": "Interaction",
      "Name": "CinemaInfo",
      "Type": "SitecoreCinema.Model.Collection.CinemaInfo"
    }
  ]
}

Copy the C:\SitecoreCinemaModel, 1.0.json file to your <xConnect instance>\App_Data\Models\ folder.

Create the Console.Journey console app project

The Console.Journey console app simulates a visitor's journey through a Sitecore Cinema:

The visitor buys a movie ticket at the ticket machine.
The visitor buys some candy at the concession stand.
The visitor scans the movie ticket to enter the movie theater.

To create the Console.Journey console app project:

In Visual Studio with administrator privileges, right-click the SitecoreCinema solution and click Add, New Project to create a new console app project for .NET Framework called Console.Journey:
In Solution Explorer, right-click Console.Journey/References and click Add Reference.
In the Reference Manager window, on the Projects tab, select SitecoreCinema.
In the Reference Manager window, click Browse and add the following references from your <xConnect instance>\bin\ folder:
- Sitecore.XConnect.Client.dll
- Sitecore.XConnect.Collection.Model.dll
- Sitecore.XConnect.Core.dll
- Sitecore.XConnect.dll
- Sitecore.Xdb.Common.Web.dll
Click OK.
In Solution Explorer, right-click References and click Manage NuGet Packages.
In the NuGet window, click Browse and add the following references:
- Microsoft.Extensions.Configuration.Abstractions
- System.Interactive.Async.Providers
In Solution Explorer, double-click the Console.Journey/Program.cs file.