Sitecore Connect for Microsoft Dynamics 365 for Sales

Walkthrough: creating a custom contact facet

Abstract

How to create a custom contact facet in order to synchronize contact data between Microsoft Dynamics and Sitecore.

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:

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.

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:

    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()
            {
            }
        }
    }

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:

    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();
            }
        }
    }

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 Sitecore, open the Content Editor.

  2. Navigate to Sitecore/System/Settings/Data ExchangeProviders/xConnect/Collection Models.

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

    Template

    Collection Model Folder

    Item name

    Custom Models

  4. Select the new item.

    Custom models in the content tree
  5. Add the following item:

    Template

    Compiled Collection Model

    Item name

    Custom Collection Model for Dynamics

  6. Select the new item.

    Custom collection model in the content tree
  7. Set the following field values:

    Field

    Value

    Collection Model Type

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

  8. Save the item.

Deploy  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. In the ribbon, on the Data Exchange tab, 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. Navigate to Sitecore/System/Data Exchange.

    Data Exchange in content tree
  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

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 Sitecore, open the Content Editor.

  2. Navigate to Sitecore/System/Data Exchange.

  3. Select your tenant.

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

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

    Template

    Entity Attribute Value Accessor

    Item name

    Account on Dynamics Contact

  6. Select the new item.

    Dynamics contact item in content tree
  7. Set the following field values:

    Field

    Value

    Attribute Name

    parentcustomerid

    Value Type

    Formatted Value

  8. Save the item.

  1. In Sitecore, open the Content Editor.

  2. Navigate to Sitecore/System/Data Exchange.

  3. Select your tenant.

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

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

    Template

    xConnect Entity Facet Value Accessor Set

    Item name

    xConnect Contact Dynamics Account Information Facet

  6. Select the new item.

    xConnect item in content tree
  7. Add the following item:

    Template

    xConnect Entity Facet Property Value Accessor

    Item name

    Account Name on Dynamics Account Information Facet on xConnect Contact

  8. Select the new item.

    xConnect sub-item in content tree
  9. Set the following field values:

    Field

    Value

    Facet Property

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

  10. Save the item.

  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. Select the new item.

    Value Mapping Set item in content tree
  7. Add the following item:

    Template

    Value Mapping

    Item name

    Account Name

  8. Select the new item.

    Value Mapping item in content tree
  9. Set the following field values:

    Field

    Value

    Source Accessor

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

    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

  10. Save the item.

  1. In Sitecore, open the Content Editor.

  2. Navigate to Sitecore/System/Data Exchange.

  3. Select your tenant.

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

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

    Template

    xConnect Entity Facet Value Accessor

    Item name

    Dynamics Account Information Facet on xConnect Contact

  6. Select the new item.

    xConnect contact item in content tree
  7. 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

  8. Save the item.

  9. Select your tenant.

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

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

    Template

    Value Mapping

    Item name

    Dynamics Account Information Facet

  12. Select the new item.

    Dynamics contact to contact model item in content tree
  13. Set the following field values:

    Field

    Value

    Source Accessor

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

    Target Accessor

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

  14. Save the item.