Walkthrough: Creating a custom contact facet

Current version: 3.0

In Sitecore Experience Platform, contact facets are used to store data on contacts. This walkthrough guides you through the process of creating a custom contact facet and configuring the synchronization process to populate the facet with data from Microsoft Dynamics 365 for Sales.

In this example you will create a custom contact facet to store the name of the account the contact is associated with. The steps that you need to follow are:

Create a Visual Studio project

In order to store custom data on a contact, a contact facet is needed. Contact facets are implemented in code. A Visual Studio project is needed before you can implement the custom contact facet.

  1. In Visual Studio, create the following project:

    Project type

    Class Library (.NET Framework)

    .NET version

    .NET Framework 4.6.2

    Project name

    Examples.Connect.Dynamics

  2. Add references to the following NuGet packages:

    • Sitecore.DataExchange.Tools.DynamicsConnect.NoReferences

    • Sitecore.XConnect.NoReferences

Note

Sitecore’s public NuGet feed is available at https://sitecore.myget.org/gallery/sc-packages.

Implement a contact facet

Each Dynamics contact is associated with an account. In order to store the account name on a contact, a contact facet is needed.

  • In Visual Studio, add the following class:

    RequestResponse
    using Sitecore.XConnect;
    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Text;
    using System.Threading.Tasks;
    
    namespace Examples.Connect.Dynamics
    {
        [FacetKey(DefaultFacetKey)]
        [Serializable]
        public class DynamicsAccountInformationFacet : Facet
        {
            public const string DefaultFacetKey = "DynamicsAccount";
            public string AccountName { get; set; }
            public DynamicsAccountInformationFacet()
            {
            }
        }
    }

Implement a collection model

In xConnect, a collection model defines which contact facets are available. Before you can store data in a custom contact facet, you need a collection model that includes the custom contact facet.

  • In Visual Studio, add the following class:

    RequestResponse
    using Sitecore.DataExchange.Tools.DynamicsConnect.Models;
    using Sitecore.XConnect;
    using Sitecore.XConnect.Schema;
    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Text;
    using System.Threading.Tasks;
    
    namespace Examples.Connect.Dynamics
    {
        public class DynamicsConnectCollectionModelEx
        {
            public DynamicsConnectCollectionModelEx()
            {
            }
            static DynamicsConnectCollectionModelEx()
            {
                _model = BuildModel();
            }
            private static XdbModel _model = null;
            public static XdbModel Model { get { return _model; } }
            private static XdbModel BuildModel()
            {
                var builder = new XdbModelBuilder(typeof(DynamicsConnectCollectionModelEx).FullName, new XdbModelVersion(1, 0));
                builder.DefineFacet<Contact, DynamicsAccountInformationFacet>(DynamicsAccountInformationFacet.DefaultFacetKey);
                builder.ReferenceModel(DynamicsConnectCollectionModel.Model);
                return builder.BuildModel();
            }
        }
    }

Register a collection model

You must register your custom collection model before it can be used. This involves updating the components and configuration on several Sitecore server roles.

Deploy custom components

The assembly that contains the custom contact facet and collection model must be deployed on your Sitecore server.

  1. Build the Visual Studio project.

  2. Copy Examples.Connect.Dynamics.dll to your Sitecore server.

Add a collection model definition

The collection model must be defined within Sitecore.

Note

A custom data provider exposes the facets defined in the collection model. This makes it easier to configure data mapping that involves xConnect entities by showing the user what is available and reducing the changes that the user will accidentally enter an invalid value.

  1. In the Sitecore Content Editor, navigate to Sitecore/System/Settings/Data Exchange/Providers/xConnect/Collection Models.

    Collection Models in the content tree
  2. Add the following item:

    Template

    Collection Model Folder

    Item name

    Custom Models

  3. In the new collection model folder item, add the following item:

    Template

    Compiled Collection Model

    Item name

    Custom Collection Model for Dynamics

  4. In the new compiled collection model item, on the Content tab, in the Settings section, set the following field values:

    Field

    Value

    Collection Model Type

    Examples.Connect.Dynamics.DynamicsConnectCollectionModelEx, Examples.Connect.Dynamics

  5. Save the item.

Deploy and convert the collection model

The collection model must be deployed to the xConnect before any custom data can be sent to xConnect. This is accomplished by copying a JSON file that describes the collection model.

  1. Navigate to the custom collection model. In the ribbon, on the Data Exchange tab, click Convert Model to Items. Then click Convert Model to JSON.

    Convert Model to JSON button
  2. Save the model file.

  3. Deploy the model file to the following servers:

    • xConnect collection

    • xConnect indexing

Configure the xConnect Client Endpoint

In order to make a connection to xConnect a collection model must be specified. This ensures xConnect and the xConnect client know exactly what to expect from one another.

  1. In the Sitecore Content Editor, navigate to Sitecore/System/Data Exchange.

  2. Select your tenant.

    Tenant selection in content tree
  3. Navigate to Endpoints/Provider/xConnect/xConnect Client Endpoint.

    xConnect Client Endpoint in content tree
  4. Set the following field values:

    Field

    Value

    Collection Model

    Collection Models/Custom Models/Custom Collection Model for Dynamics

Test the configuration

Testing the configuration ensures that the collection model is deployed and the xConnect client endpoint is configured properly. To run the test:

  • In the ribbon, click Run Troubleshooter.

    Run Troubleshooter button

A message will appear, informing you a connection to the xConnect collection service was established.

Connection successfully established message

Specify how to read from the Dynamics contact

The tenant must be configured to understand the structure of the data being read from Dynamics. This section describes how to update the tenant in order to incorporate this information.

A value accessor is used to represent that the account is a property of the contact in Dynamics. This value accessor serves a couple of purposes:

  • When you read contacts from Dynamics, you must tell Dynamics to include the account for the contact. The value accessors in the value accessor set are used to determine which fields on the contact object should be read. Adding a value accessor enables you to specify that you want to read additional fields from Dynamics.

  • When it is time to configure the mapping of data from Dynamics to Sitecore, the value accessor is used to specify which value to read from the Dynamics contact.

To add a value accessor for the account on the contact:

  1. In the Sitecore Content Editor, navigate to Sitecore/System/Data Exchange.

  2. Select your tenant.

  3. Navigate to Data Access/Value Accessor Sets/Providers/Dynamics/Dynamics Contact.

    Dynamics Contact in content tree
  4. Add the following item:

    Template

    Entity Attribute Value Accessor

    Item name

    Account on Dynamics Contact

  5. In the new item, on the Content tab, in the Attribute section, set the following field values:

    Field

    Value

    Attribute Name

    parentcustomerid

    Value Type

    Formatted Value

  6. Save the item.

Specify how to write to the Contact facet

  1. In the Sitecore Content Editor, navigate to Sitecore/System/Data Exchange.

  2. Select your tenant.

  3. Navigate to Data Access/Value Accessor Sets/Providers/xConnect.

    xConnect provider in content tree
  4. Add the following item:

    Template

    xConnect Entity Facet Value Accessor Set

    Item name

    xConnect Contact Dynamics Account Information Facet

  5. In the new item, add the following item:

    Template

    xConnect Entity Facet Property Value Accessor

    Item name

    Account Name on Dynamics Account Information Facet on xConnect Contact

  6. In the new item, on the Content tab, in the Settings section, set the following field value:

    Field

    Value

    Facet Property

    Collection Models/Custom Models/Custom Collection Model for Dynamics/Facets/Contact/DynamicsAccount/AccountName

  7. Save the item.

Map Dynamics data to the contact facet

  1. In Sitecore, open the Content Editor.

  2. Navigate to Sitecore/System/Data Exchange.

  3. Select your tenant.

  4. Navigate to Value Mapping Sets/Dynamics to xConnect Contact Mappings.

    Value Mapping Sets in content tree
  5. Add the following item:

    Template

    Value Mapping Set

    Item name

    Dynamics Contact to xConnect Contact Dynamics Account Information Facet

  6. In the new item, add the following item:

    Template

    Value Mapping

    Item name

    Account Name

  7. In the new item, on the Content tab, set the following field values:

    Section

    Field

    Value

    Source

    Source Accessor

    Data Access/Value Accessor Sets/Providers/Dynamics/Dynamics Contact/Account on Dynamics Contact

    Target

    Target Accessor

    Data Access/Value Accessor Sets/Providers/xConnect/xConnect Contact Dynamics Account Information Facet/Account Name on Dynamics Account Information Facet on xConnect Contact

  8. Save the item.

Map the contact facet to the contact

  1. In the Sitecore Content Editor, navigate to Sitecore/System/Data Exchange.

  2. Select your tenant.

  3. Navigate to Data Access/Value Accessor Sets/Providers/xConnect/xConnect Contact.

    xConnect Contact in content tree
  4. Add the following item:

    Template

    xConnect Entity Facet Value Accessor

    Item name

    Dynamics Account Information Facet on xConnect Contact

  5. In the new item, on the Content tab, in the Settings section, set the following field values:

    Field

    Value

    Facet Definition

    Collection Models/Custom Models/Custom Collection Model for Dynamics/Facets/Contact/DynamicsAccount

    Mapping Set

    Value Mapping Sets/Dynamics to xConnect Contact Mappings/Dynamics Contact to xConnect Contact Dynamics Account Information Facet

  6. Save the item.

  7. Select your tenant.

  8. Navigate to Value Mapping Sets/Dynamics to xConnect Contact Mappings/Dynamics Contact to Contact Model.

    Dynamics to xConnect contact mappings in content tree
  9. Add the following item:

    Template

    Value Mapping

    Item name

    Dynamics Account Information Facet

  10. In the new item, on the Content tab, set the following field values:

    Section

    Field

    Value

    Source

    Source Accessor

    Data Access/Value Accessors/Common/Value Accessor with Raw Value Reader Set

    Target

    Target Accessor

    Data Access/Value Accessor Sets/Providers/xConnect/xConnect Contact/Dynamics Account Information Facet on xConnect Contact

  11. Save the item.

Add new facet to pipelines

In order for the information in the new facet to be processed, you must add it to the Read Contacts from xConnect and Process Single Contact from Dynamics pipelines.

To add the fields to the Read Contacts from xConnect pipeline:

  1. In the Sitecore Content Editor, navigate to Sitecore/System/Data Exchange.

  2. Select your tenant.

  3. Navigate to Pipelines/xConnect Contacts to Dynamics Sync Pipelines/Read Contacts from xConnect Pipeline/Read Contacts from xConnect.

  4. On the Content tab, in the Contact Settings sections, in the Contact facets to Read field, add xConnect Contact Dynamics Account Information Facet to the Selected column.

  5. Save the pipeline step.

To add the facet to the Process Single Contact from Salesforce pipeline step:

  1. In the Sitecore Content Editor, navigate to Sitecore/System/Data Exchange.

  2. Select your tenant.

  3. Navigate to Pipelines/Dynamics Contacts to xConnect Sync Pipelines/Process Single Contact from Dynamics Pipeline/Resolve Contact Model by Dynamics Id from xConnect.

  4. On the Content tab, in the xConnect Settings sections, in the Facets to Read field, locate Collection Models/Custom Models/Custom Collection Model for Dynamics/Facets/Contact/DynamicsAccount. Add it to the Selected column.

  5. Save the pipeline step.

Do you have some feedback for us?

If you have suggestions for improving this article,