Walkthrough: Creating a custom contact facet

To store custom data on a contact, you must have contact facets. You implement contact facets in a Micrososft Visual Studio project.

To create and deploy a 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.Salesforce

2. Add references to the following NuGet packages:

   • Sitecore.DataExchange.Tools.SalesforceConnect.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 to store the Salesforce contact account name, add the following class to the project:

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

4. To create an xConnect collection model that defines which contact facets are available, add the following class to the project:

   using Sitecore.DataExchange.Tools.SalesforceConnect.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.Salesforce
   {
       public class SalesforceConnectCollectionModelEx
       {
           public SalesforceConnectCollectionModelEx()
           {
           }
           static SalesforceConnectCollectionModelEx()
           {
               _model = BuildModel();
           }
           private static XdbModel _model = null;
           public static XdbModel Model { get { return _model; } }
           private static XdbModel BuildModel()
           {
               var builder = new XdbModelBuilder(typeof(SalesforceConnectCollectionModelEx).FullName, new XdbModelVersion(1, 0));
               builder.DefineFacet<Contact, SalesforceAccountInformationFacet>(SalesforceAccountInformationFacet.DefaultFacetKey);
               builder.ReferenceModel(SalesforceConnectCollectionModel.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 the user enters an invalid value accidentally.

You must register your custom collection model before it can be used.

To define a collection model:

1. In Sitecore, open the Content Editor and 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 Custom Models item, add the following item:

   Template	Compiled Collection Model
   Item name	Custom Collection Model for Salesforce

4. Select the new Custom Collection Model for Salesforce item. In the right-hand pane, on the Content tab, in the Settings section, set the following field value:

   Field	Value
   Collection Model Type	Examples.Connect.Salesforce.SalesforceConnectCollectionModelEx, Examples.Connect.Salesforce

5. Save the item.

To deploy the collection model:

1. To deploy the model to xConnect, navigate to the custom collection model. On 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 to the following servers:

   • xConnect collection
   • xConnect indexing

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

4. In the right-hand pane, on the Content tab, in the Collection Service section, set the following field value:

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

5. Save the item.

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

   

   A message informs you a connection to the xConnect collection service was established:

   

You must configure the tenant to read the contact data from Salesforce. To do so, you use value accessors and value readers to represent the Salesforce data structure.

To specify how to read from the Salesforce contact:

When it is time to configure the mapping of data from Salesforce to Sitecore, you use the value accessor to specify what value to read from the Salesforce contact.

When you specify that you want to include the account name for the contact, Salesforce returns an account object. This account object has a field that represents the account name. You must create a value accessor to access the name on the account object. This value accessor is never used directly. You must create a value reader that uses the value accessor to read the account name.

To specify how to read from the Salesforce contact:

1. To add the value accessor for the account on the contact, in the Content Editor, navigate to /Data Access/Value Accessor Sets/Providers/Salesforce/Salesforce Contact Fields. Add the following item:

   Template	Salesforce Object Field Value Accessor
   Item name	Account on Salesforce Contact

2. Select the new Account on Salesforce Contact item. In the right-hand pane, on the Content tab, in the Field section, set the following field values:

   Field	Value
   Field Name	Account
   Field Name for Select	Account.Name

3. Save the item.

4. To create the value accessor to access the account name , in the Content Editor, navigate to /Data Access/Value Accessor Sets/Providers/Salesforce. Add the following item:

   Template	Salesforce Object Value Accessor Set
   Item Name	Salesforce Account Fields

5. In the new Salesforce Account Fields item, add the following item:

   Template	Salesforce Object Field Value Accessor
   Item name	Name on Salesforce Account

6. In the new Name on Salesforce Account item, in the right-hand pane, on the Content tab, in the Field section, set the following field value:

   Field	Value
   Field name	Name

7. Save the item.

8. To create the value reader, in the Content Editor, navigate to /Data Access/Value Readers/Providers/Salesforce. Add the following item:

   Template	Value Accessor Value Reader
   Item Name	Value Reader for Account Name Value Accessor

9. In the new Value Reader for Account Name Value Accessor item, in the right-hand pane, on the Content tab, in the Settings section, set the following field value:

   Field	Value
   Value Accessor	Value Accessor Sets/Providers/Salesforce/Salesforce Account Fields/Name on Salesforce Account

10. Save the item.

To set up a value accessor set:

1. In the Content Editor, navigate to /Data Access/Value Accessor Sets/Providers/xConnect.

2. Add the following item:

   Template	xConnect Entity Facet Value Accessor Set
   Item name	xConnect Contact Salesforce Account Information Facet

3. In the new xConnect Contact Salesforce Account Information Facet item, add the following item:

   Template	xConnect Entity Facet Property Value Accessor
   Item name	Account Name on Salesforce Account Information Facet on xConnect Contact

4. In the new Account Name on Salesforce Account Information Facet on xConnect Contactitem, in the right-hand pane, 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 Salesforce/Facets/Contact/SalesforceAccount/AccountName

5. Save the item.

To map data to the contact facet:

1. In the Content Editor, navigate to /Value Mapping Sets/Salesforce to xConnect Contact Mappings.

2. Add the following item:

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

3. In the new Salesforce Contact to xConnect Contact Salesforce Account Information Facet item, add the following item:

   Template	Value Mapping
   Item name	Account Name

4. In the new Account Name  item, in the right-hand pane, on the Content tab, set the following field values:

   Section	Field	Value
   Source	Source Accessor	Data Access/Value Accessor Sets/Providers/Salesforce/Salesforce Contact Fields/Account on Salesforce Contact
   Target	Target Accessor	Data Access/Value Accessor Sets/Providers/xConnect/xConnect Contact Salesforce Account Information Facet/Account Name on Salesforce Account Information Facet on xConnect Contact
   Rules	Source Value Transformer	Value Readers/Providers/Salesforce/Value Reader for Account Name Value Accessor

   Note

   In the Specify how to read from the Salesforce contact section, you created a value reader for the account name. This value reader is set as the source value transformer on the value mapping. The source value transformer is a value reader that reads a value from the object read by the source value accessor. In this case, the source value accessor reads the account object from the Salesforce contact. However, it uses the account name, not the account object itself. So the source value transformer reads the name from the account object.

5. Save the item.

To map the facet:

1. In the Content Editor, navigate to /Data Access/Value Accessor Sets/Providers/xConnect/xConnect Contact.

2. Add the following item:

   Template	xConnect Entity Facet Value Accessor
   Item name	Salesforce Account Information Facet on xConnect Contact

3. In the new Salesforce Account Information Facet on xConnect Contact item, in the right-hand pane, 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 Salesforce/Facets/Contact/SalesforceAccount
   Mapping Set	Value Mapping Sets/Salesforce to xConnect Contact Mappings/Salesforce Contact to xConnect Contact Salesforce Account Information Facet

4. Save the item.

5. Select your tenant.

6. Navigate to /Value Mapping Sets/Salesforce to xConnect Contact Mappings/Salesforce Contact to Contact Model.

7. Add the following item:

   Template	Value Mapping
   Item name	Salesforce Account Information Facet

8. In the new Salesforce Account Information Facet item, in the right-hand pane, on the Content tab, set the following 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/Salesforce Account Information Facet on xConnect Contact

9. Save the item.

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

To add the facet to the pipeline steps:

1. To add the fields for the facets to the pipeline step, in the Content Editor, navigate to /Pipelines/Salesforce Contacts to xConnect Sync Pipelines/Read Contacts from Salesforce Pipeline/Read Contacts from Salesforce.
2. In the right-hand pane, on the Content tab, in the Object Settings sections, in the Fields to Read field, add Salesforce Account Fields to the Selected column. Save the pipeline step.
3. To add the facet to the Process Single Contact from Salesforce pipeline step, in the Content Editor, navigate to /Pipelines/Salesforce Contacts to xConnect Sync Pipelines/Process Single Contact from Salesforce Pipeline/Resolve Contact Model by Id from xConnect.
4. In the right-hand pane, on the Content tab, in the xConnect Settings sections, in the Facets to Read field, locate Collection Models/Custom Models/Custom Collection Model for Salesforce/Facets/Contact/SalesforceAccount. Add it to the Selected column.
5. Save the pipeline step.