Walkthrough: Creating a custom contact facet

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

2. Add references to the following NuGet packages:

   • Sitecore.DataExchange.Tools.SalesforceConnect.NoReferences
   • Sitecore.XConnect.NoReferences

Each Salesforce 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.Salesforce
  {
      [FacetKey(DefaultFacetKey)]
      [Serializable]
      public class SalesforceAccountInformationFacet : Facet
      {
          public const string DefaultFacetKey = "SalesforceAccount";
          public string AccountName { get; set; }
          public SalesforceAccountInformationFacet()
          {
          }
      }
  }

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

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

Test the configuration

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

• On the ribbon, click Run Troubleshooter.

  

A message will appear, 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 Salesforce. This section describes how to update the tenant in order to incorporate this information.

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 Salesforce Account Information Facet

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

   Template	xConnect Entity Facet Property Value Accessor
   Item name	Account Name on Salesforce 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 Salesforce/Facets/Contact/SalesforceAccount/AccountName

7. Save the item.

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

2. Select your tenant.

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

   

4. Add the following item:

   Template	Value Mapping Set
   Item name	Salesforce Contact to xConnect Contact Salesforce 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/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, a value reader was created 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, the account name is needed, not the account object itself. So the source value transformer reads the name from the account object.

7. Save the item.

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	Salesforce 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 Salesforce/Facets/Contact/SalesforceAccount
   Mapping Set	Value Mapping Sets/Salesforce to xConnect Contact Mappings/Salesforce Contact to xConnect Contact Salesforce Account Information Facet

6. Save the item.

7. Select your tenant.

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

   

9. Add the following item:

   Template	Value Mapping
   Item name	Salesforce Account Information Facet

10. In the new item, 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

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 Salesforce and Process Single Contact from Salesforce pipeline steps.

To add the fields to the Read Contacts from Salesforce pipeline step:

1. In the Content Editor, navigate to Sitecore/System/Data Exchange.
2. Select your tenant.
3. Navigate to Pipelines/Salesforce Contacts to xConnect Sync Pipelines/Read Contacts from Salesforce Pipeline/Read Contacts from Salesforce.
4. On the Content tab, in the Object Settings sections, in the Fields to Read field, add Salesforce Account Fields 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 Content Editor, navigate to Sitecore/System/Data Exchange.
2. Select your tenant.
3. Navigate to Pipelines/Salesforce Contacts to xConnect Sync Pipelines/Process Single Contact from Salesforce Pipeline/Resolve Contact Model by 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 Salesforce/Facets/Contact/SalesforceAccount. Add it to the Selected column.
5. Save the pipeline step.