---
title: "Walkthrough: Using code to define data mapping"
slug: "walkthrough--using-code-to-define-data-mapping"
abstract: "Introduction to defining data mapping using code in Sitecore Data Exchange Framework."
---
# Walkthrough: Using code to define data mapping

When using Data Exchange Framework, the standard approach for mapping data is to configure the mapping in the tenant. In many cases, this approach works well because it reduces the amount of custom code needed. Specific mappings can be added or removed as needed, without having to write any code.

However, there are cases where the mapping logic is too complex to be described through configuration. There are also cases where existing data mapping logic should be reused. In these cases, you must define data mapping using code.

This walkthrough describes how to build, deploy, and integrate the components needed to implement code-based data mapping.

- Create Visual Studio project for data mapping
- Implement a custom value mapping set
- Create a template for a custom value mapping set
- Implement a converter for a custom value mapping set
- Integrate a custom value mapping set

<details>
<summary><h2>Create a Visual Studio project for data mapping</h2></summary>

You need a Microsoft Visual Studio project to implement the data mapping logic.

To create the project:

1. In Visual Studio, create the following project:

    | **Project type** | *Class Library (.NET Framework)* |
    | --- | --- |
    | **.NET version** | *.NET Framework 4.7.1* |
    | **Project name** | *Examples.DataExchange* |

2. Add references to the following NuGet packages:
    - `Sitecore.DataExchange`

> [!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).

</details>

<details>
<summary><h2>Implement a custom value mapping set</h2></summary>

In the data synchronization process, a [value mapping set](https://doc.sitecore.com/xp/en/developers/def/80/data-exchange-framework/value-mapping-sets.html "Value mapping sets") controls the mapping of data from the source object to the target object. Normally, you configure the data mapping by assigning individual [value mappings](https://doc.sitecore.com/xp/en/developers/def/80/data-exchange-framework/value-mappings.html "Value mappings") to the value mapping set. However, if the data mapping logic is very complex, you can control the data mapping through code instead. To do so, you must create a custom value mapping set that implements the code that determines the data mapping.

The code example in this topic implements the following data mapping logic:

- Read the *Name* property from the source object.
- Write it to the *Description* property on the target object.
- Set the current date on the *LastUpdated* property on the target object.

To create the custom value mapping set:

- In Visual Studio, add the following class:

    ```csharp
    using Sitecore.DataExchange.DataAccess;
    using Sitecore.DataExchange.DataAccess.Mappings;
    using Sitecore.DataExchange.DataAccess.Readers;
    using Sitecore.DataExchange.DataAccess.Writers;
    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Text;
    using System.Threading.Tasks;

    namespace Examples.DataExchange
    {
        public class CustomMappingSet : IMappingSet
        {
            public CustomMappingSet() { }

            public ICollection<IMapping> Mappings => throw new NotImplementedException();

            private static IValueReader ValueReader1 = new PropertyValueReader("Name");
            private static IValueWriter ValueWriter1 = new PropertyValueWriter("Description");
            private static IValueWriter ValueWriter2 = new PropertyValueWriter("LastUpdated");
            public bool Run(MappingContext context)
            {
                if (context == null || context.Source == null || context.Target == null)
                {
                    return false;
                }
                ApplyMapping(ValueReader1, ValueWriter1, context, new Mapping { Identifier = "Mapping1" });
                ApplyMapping(DateTime.Now.Date, ValueWriter2, context, new Mapping { Identifier = "Mapping2" });
                return true;
            }
            protected void ApplyMapping(IValueReader reader, IValueWriter writer, MappingContext context, IMapping mapping)
            {
                var context2 = new DataAccessContext();
                var result = reader.Read(context.Source, context2);
                if (!result.WasValueRead)
                {
                    context.RunFail.Add(mapping);
                    return;
                }
                ApplyMapping(result.ReadValue, writer, context, mapping);
            }
            protected void ApplyMapping(object value, IValueWriter writer, MappingContext context, IMapping mapping)
            {
                var context2 = new DataAccessContext();
                var writeSuccess = writer.Write(context.Target, value, context2);
                if (writeSuccess)
                {
                    context.RunSuccess.Add(mapping);
                    return;
                }
                context.RunFail.Add(mapping);
            }
        }
    }
    ```

</details>

<details>
<summary><h2>Create a template for a custom value mapping set</h2></summary>

To configure the data synchronization process to use a custom value mapping set, you must create and configure a template.

Since all of your value mapping is done in code, there is no reason to allow users to add value mapping items under the custom value mapping set.

To add a new template and remove the option to insert value mappings:

1. In the Content Editor, navigate to *Templates*. On the ribbon, on the Home tab, in the Insert group, click New Template.

    ![New template option on menu ribbon](https://doc.sitecore.com/api/markdown-image/xp/en/developers/def/80/data-exchange-framework/images/add-template.png)

2. In the **Select name** dialog, enter the following values:

    | **Name** | *Custom Value Mapping Set* |
    | --- | --- |
    | **Base template** | *Templates/Data Exchange/Framework> Data Access > Mapping > Value Mapping Set* |

3. Click **Next**. In the **Location** dialog, select *Templates/Data Exchange/Framework/Data Access/Mapping*.

    ![Data access mapping dialog](https://doc.sitecore.com/api/markdown-image/xp/en/developers/def/80/data-exchange-framework/images/location4.png)

4. Click **Next**. In the confirmation dialog, click **Close**.
5. To set an icon for the new template, in the content tree, select the template, for example, *Templates/Data Exchange/Framework/Data Access/Mapping/Custom Value Mapping Set*.
6. In the right-hand pane, on the **Content** tab, click the icon next to title.

    ![Value Mapping Set icon](https://doc.sitecore.com/api/markdown-image/xp/en/developers/def/80/data-exchange-framework/images/icon4.png)

7. In the **Change Icon** dialog, in the **Icon** field, enter, for example, *Office/32x32/vector_circle.png*.
8. With the template item selected, on the ribbon, on the **Builder Options** tab, in the **Template** group, click **Standard values**.
9. With the new *__Standard Values* item selected, on the ribbon, on the **Configure** tab, in the **Insert Options** group, click **Assign**.
10. In the **Insert Options** dialog, in the list on the right, click *Value Mapping*.

    ![Insert Options dialog](https://doc.sitecore.com/api/markdown-image/xp/en/developers/def/80/data-exchange-framework/images/value-mapping-selected.png)

11. Click the left arrow (![Left arrow icon](https://doc.sitecore.com/api/markdown-image/xp/en/developers/def/80/data-exchange-framework/images/left-arrow.png)) to remove *Value Mapping* from the **Selected** list. Click **OK** to save your changes.

</details>

<details>
<summary><h2>Implement a converter for a custom value mapping set</h2></summary>

In Data Exchange Framework, Sitecore items are only used for configuration. When a data synchronization process runs, the configuration is read from the Sitecore items and then converted into framework components.

You must implement a custom converter class using the item ID from the custom value mapping set template.

To implement the custom converter:

1. In the Content Editor, navigate to */sitecore/templates/Data Exchange/Framework/Data Access/Mapping/Custom Value Mapping Set*.
2. On the ribbon, on the **Content** tab, in the **Quick Info** section, copy the *Item ID* value.

    ![Quick Info section on the Content tab, showing the Item ID value.](https://doc.sitecore.com/api/markdown-image/xp/en/developers/def/80/data-exchange-framework/images/quick-info-section.png)

3. To create the custom converter class, in Visual Studio, add the following class:

    ```csharp
    using Sitecore.DataExchange;
    using Sitecore.DataExchange.Attributes;
    using Sitecore.DataExchange.Converters;
    using Sitecore.DataExchange.Repositories;
    using Sitecore.Services.Core.Model;
    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Text;
    using System.Threading.Tasks;

    namespace Examples.DataExchange
    {
        [SupportedIds("{00000000-0000-0000-0000-000000000000}")]
        public class CustomMappingSetConverter : BaseItemModelConverter<CustomMappingSet>
        {
            public CustomMappingSetConverter(IItemModelRepository repository) : base(repository)
            {
            }
            private static CustomMappingSet _instance = new CustomMappingSet();
            protected override ConvertResult<CustomMappingSet> ConvertSupportedItem(ItemModel source)
            {
                return ConvertResult<CustomMappingSet>.PositiveResult(_instance);
            }
        }
    }
    ```

    > [!note]
    > In the attribute *SupportedIds*, use the template item ID you copied in the previous step.

4. To deploy the code, build the Visual Studio project.
5. Copy the `Examples.DataExchange.dll` file to your Sitecore server.

</details>

<details>
<summary><h2>Integrate a custom value mapping set</h2></summary>

The final step is to integrate your custom value mapping set into Data Exchange Framework.

When configuring your data synchronization process, use your custom value mapping set when you create new tenants. For already existing tenants, replace the value mapping set currently used with your custom value mapping set.

To configure the template to use the custom converter and the custom value mapping set:

1. In the Content Editor, navigate to */sitecore/templates/Data Exchange/Framework/Data Access/Mapping/Custom Value Mapping Set/__Standard Values*.
2. On the **Configure** tab, in the **Data Exchange Framework** section, set the following field values:

    | Field | Value |
    | --- | --- |
    | **Converter Type** | *Examples.DataExchange.CustomMappingSetConverter,Examples.DataExchange* |

3. On the menu ribbon, on the **Configure** tab, in the **Insert Options** group, click **Assign**.
4. In the **Insert Options** dialog, in the tree on the left, navigate to *Templates/Data Exchange/Framework/Data Access/Mapping/Custom Value Mapping Set*. Click the right arrow (![Arrow pointing right](https://doc.sitecore.com/api/markdown-image/xp/en/developers/def/80/data-exchange-framework/images/right-arrow.png)) to add the set to the **Selected** list.

    ![Insert Options dialog](https://doc.sitecore.com/api/markdown-image/xp/en/developers/def/80/data-exchange-framework/images/custom-value-mapping-set-added-to-insert-options.png)

5. Click **OK**.

</details>