---
title: "Walkthrough: Creating a custom contact facet"
slug: "walkthrough--creating-a-custom-contact-facet"
abstract: "How to create a custom contact facet to synchronize contact data between Salesforce CRM and Sitecore."
---
# Walkthrough: Creating a custom contact facet

In Sitecore Experience Platform, you use contact facets 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. The custom contact facet stores the name of the account the contact is associated with.

This walkthrough describes how to:

- Create and deploy a custom contact facet assembly
- Define a collection model
- Deploy and configure the collection model
- Specify how to read from the Salesforce contact
- Specify how to write to the Contact facet
- Map Salesforce data to the contact facet
- Map the contact facet to the contact
- Add new facet to pipelines

<details>
<summary><h2>Create and deploy a custom contact facet assembly</h2></summary>

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](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:

    ```csharp
    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:

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

</details>

<details>
<summary><h2>Define a collection model</h2></summary>

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.

</details>

<details>
<summary><h2>Deploy and configure the collection model</h2></summary>

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

    ![Convert model to JSON button](<https://doc.sitecore.com/api/markdown-image/xp/en/developers/salesforce-connect/80/sitecore-connect-for-salesforce-crm/images/convert%20model%20to%20json%20button.png>)

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/<your Salesforce tenant>/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**.

    ![Run Troubleshooter button](<https://doc.sitecore.com/api/markdown-image/xp/en/developers/salesforce-connect/80/sitecore-connect-for-salesforce-crm/images/run%20troubleshooter%20button.png>)

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

    ![Connection successfully established message](<https://doc.sitecore.com/api/markdown-image/xp/en/developers/salesforce-connect/80/sitecore-connect-for-salesforce-crm/images/connection%20established%20message.png>)

</details>

<details>
<summary><h2>Specify how to read from the Salesforce contact</h2></summary>

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 *<your Salesforce tenant>/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 *<your Salesforce tenant>/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 *<your Salesforce tenant>/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.

</details>

<details>
<summary><h2>Specify how to write to the Contact facet</h2></summary>

To set up a value accessor set:

1. In the Content Editor, navigate to *<your Salesforce tenant>/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 Contact*item, 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.

</details>

<details>
<summary><h2>Map Salesforce data to the contact facet</h2></summary>

To map data to the contact facet:

1. In the Content Editor, navigate to *<your Salesforce tenant>/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](https://doc.sitecore.com/xp/en/developers/salesforce-connect/80/sitecore-connect-for-salesforce-crm/walkthrough--creating-a-custom-contact-facet.html#UUID-e55f8a5d-3fd6-6f5d-c7d7-f37ef08e2900_N1527254567757 "Specify how to read from the Salesforce contact"), 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.

</details>

<details>
<summary><h2>Map the contact facet to the contact</h2></summary>

To map the facet:

1. In the Content Editor, navigate to *<your Salesforce tenant>/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 *<your Salesforce tenant>/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.

</details>

<details>
<summary><h2>Add new facet to pipelines</h2></summary>

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 *<your Salesforce tenant>/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 *<your Salesforce tenant>/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.

</details>