1. Mapping additional data from Salesforce to Sitecore

Walkthrough: Creating a custom contact facet

Version:

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

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:

  1. Create a Visual Studio project

  2. Implement a contact facet

  3. Implement a collection model

  4. Register a collection model

  5. Specify how to read from the Salesforce contact

  6. Specify how to write to the Contact facet

  7. Map Salesforce data to the contact facet

  8. Map the contact facet to the contact

  9. Add new facet to pipelines

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

Implement a contact facet

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

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:

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

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.Salesforce.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, 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 item, add the following item:

    Template

    Compiled Collection Model

    Item name

    Custom Collection Model for Salesforce

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

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

  2. Select your tenant.

    Tenant selected in content tree

  3. Navigate to Endpoints/Providers/xConnect/xConnect Client Endpoint.

    xConnect client endpoint in content tree

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

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.

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

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.

Add  a value accessor for the account on the contact 

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

  • When you read contacts from Salesforce, you must tell Salesforce 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 Salesforce.

  • When it is time to configure the mapping of data from Salesforce to Sitecore, the value accessor is used to specify which value to read from the Salesforce 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/Salesforce/Salesforce Contact Fields.

    Salesforce contact provider in content tree

  4. Add the following item:

    Template

    Salesforce Object Field Value Accessor

    Item name

    Account on Salesforce Contact

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

    Field

    Value

    Field Name

    Account

    Field Name for Select

    Account.Name 

  6. Save the item.

Add a value accessor for the name on the account

In Salesforce, when you specify that you want to include the account name when you read contacts, Salesforce returns an account object. This account object has a field that represents the account name. A value accessor is needed in order to read the name on the account object. This value accessor is never used directly. It is created so that the value reader created in the next step can use it.

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

    Salesforce provider in content tree

  2. Add the following item:

    Template

    Salesforce Object Value Accessor Set

    Item Name

    Salesforce Account Fields

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

    Template

    Salesforce Object Field Value Accessor

    Item name

    Name on Salesforce Account

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

    Field

    Value

    Field name

    Name

  5. Save the item.

Add a value reader for the account name

The purpose of this value reader will become apparent in a later step. For now, just follow the step below.

  1. In the Content Editor, navigate to Data Access/Value Readers/Providers/Salesforce.

    Salesforce value reader provider in content tree

  2. Add the following item:

    Template

    Value Accessor Value Reader

    Item Name

    Value Reader for Account Name Value Accessor

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

  4. Save the item.

Specify how to write to the 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 value accessor sets provider in content tree

  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.

Map Salesforce data to the contact facet

  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.

    Salesforce to xConnect contact mappings in content tree

  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.

Map the contact facet to 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/xConnect/xConnect Contact.

    xConnect Contact provider in content tree

  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.

    Salesforce contact to contact model value mapping set in content tree

  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.

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

If you have suggestions for improving this article, let us know!