Walkthrough: Creating a custom contact facet

To store custom data on a contact, you must create a custom contact facet and collection model. You must create a Microsoft Visual Studio project to implement the custom components in code.

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.

To build and deploy an assembly with the custom components:

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://nuget.sitecore.com/resources/v3/index.json.

3. To create a contact facet for storing the account name, 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()
           {
           }
       }
   }

4. To implement a collection model, 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();
           }
       }
   }

5. To deploy the assembly on your Sitecore server, build the Visual Studio project, and copy the resulting Examples.Connect.Salesforce.dll file to your Sitecore server.

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 you accidentally enter an invalid value.

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

To define the collection model:

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

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.

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.

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

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

To deploy and configure the collection model:

1. To deploy the collection model, 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.

   

2. Save the model file, and deploy the model file to the following servers:

   • xConnect collection
   • xConnect indexing

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

4. To configure the xConnect Client Endpoint to use the collection model, navigate to Sitecore/System/Data Exchange//Endpoints/Providers/xConnect/xConnect Client Endpoint

5. Set the following field values:

   Field	Value
   Collection Model	Collection Models/Custom Models/Custom Collection Model for Dynamics

6. Save the item.

7. To test the configuration, in the ribbon, on the Data Exchange tab, click Run Troubleshooter.

   

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

   

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 Content Editor, navigate to Sitecore/System/Data Exchange.

2. Select your tenant.

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

   

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.

To set up a value accessor set:

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

2. Select your tenant.

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

   

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.

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

2. Select your tenant.

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

   

4. Add the following item:

   Template	Value Mapping Set
   Item name	Dynamics Contact to xConnect Contact Dynamics Account Information Facet

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

   Template	Value Mapping
   Item name	Account Name

6. 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

7. Save the item.

To map a contact facet:

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

2. Select your tenant.

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

   

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.

   

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.

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 facet to pipeline steps:

1. To add the fields for the facets to the pipeline step, in the Content Editor, navigate to Sitecore/System/Data Exchange.
2. Navigate to /Pipelines/xConnect Contacts to Dynamics Sync Pipelines/Read Contacts from xConnect Pipeline/Read Contacts from xConnect.
3. 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. Save the pipeline step.
4. To add the facet to the Process Single Contact from Salesforce pipeline step, in the Content Editor, navigate to /Pipelines/Dynamics Contacts to xConnect Sync Pipelines/Process Single Contact from Dynamics Pipeline/Resolve Contact Model by Dynamics Id from xConnect.
5. 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. Save the pipeline step.