Walkthrough: Implementing data access components

Version: 8.0

This walkthrough is part four of the Implementing a custom provider for text files walkthrough series and describes how to implement data access components. Data access components represent the logic used to read, write, and map values during a data synchronization process. The data access components in this example represent the ability to read values at specific positions from a line in a text file.

For example, consider a file that contains comma-separated values (CSV) that provide details about new customers. The file looks like the following:

RequestResponse

first,last,company
Aaron,Adkins,Ace Corp
Brad,Bedford,Burnside Bread
Charlotte,Colson,Carefree Farms

The pipeline step processor ReadTextFileStepProcessor reads each row from a file and creates an array of values using the specified delimiter. In this example, the delimiter is a comma.

You use data access components to control how the values in that array are accessed. In this example, you use the data access components to identify the following:

First name is at position 1
Last name (surname) is at position 2
Company name is at position 3

This walkthrough describes how to:

Create a template for value accessors
Implement a value accessor converter
Set default values on a value accessor template
Create a template for value accessor sets
Set default values on a value accessor set template

Create a template for value accessors

In this walkthrough, each row from the input text file is split into an array of values. The individual values in the array can be used in a data synchronization process. You must create a template, set an icon for the template, and add fields to it that let a user specify which values in the array to read.

To create a template:

In the Content Editor, navigate to Templates. On the menu ribbon, on the Home tab, click New Template.

In the Select name dialog, enter the following values:

Field	Value
Name	Array Value Accessor
Base template	Templates/Data Exchange/Framework/Data Access/Value Accessors/Value Accessor

Click Next.
In the Location dialog, select Templates/Data Exchange/Providers/File System/Data Access/Value Accessors. Click Next. In the confirmation dialog, click Close.
To set an icon for the value accessor, in the Content Editor, select the new template, for example, Templates/Data Exchange/Providers/File System/Data Access/Value Accessors/Array Value Accessor.
In the right-hand pane, on the Content tab, click the icon next to the title.
In the Change Icon dialog, in the Icon field, enter, for example, Office/32x32/radio_button_selected.png. Click OK.
To add fields to the value accessor, on the new template, add a template section and name it Settings.

Add the following fields:

Field	Value
Name	Position
Type	Integer
Shared	selected

Save the item.

Implement a value accessor converter

You must create a converter that can convert the settings on a value accessor item into a plugin. You can then specify the converter on the value accessor template in order to identify an endpoint for pipeline steps to read from.

To create the converter:

In Visual Studio, add the following class:

RequestResponse

using Sitecore.DataExchange.Attributes;
using Sitecore.DataExchange.Converters.DataAccess.ValueAccessors;
using Sitecore.DataExchange.DataAccess;
using Sitecore.DataExchange.DataAccess.Readers;
using Sitecore.DataExchange.DataAccess.Writers;
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.Providers.FileSystem
{
    [SupportedIds(ArrayValueAccessorTemplateId)]
    public class ArrayValueAccessorConverter : ValueAccessorConverter
    {
        public const string ArrayValueAccessorTemplateId = "[ARRAY VALUE ACCESSOR TEMPLATE ID]";
        public const string TemplateFieldPosition = "Position";
        public ArrayValueAccessorConverter(IItemModelRepository repository) : base(repository)
        {
        }
        protected override IValueReader GetValueReader(ItemModel source)
        {
            var reader = base.GetValueReader(source);
            if (reader == null)
            {
                var position = this.GetIntValue(source, TemplateFieldPosition);
                if (position < 0)
                {
                    return null;
                }
                reader = new ArrayValueReader(position);
            }
            return reader;
        }
        protected override IValueWriter GetValueWriter(ItemModel source)
        {
            var writer = base.GetValueWriter(source);
            if (writer == null)
            {
                var position = this.GetIntValue(source, TemplateFieldPosition);
                if (position < 0)
                {
                    return null;
                }
                writer = new ArrayValueWriter(position);
            }
            return writer;
        }
    }
}

Important

You must change the value of [ARRAY VALUE ACCESSOR TEMPLATE ID] to match the ID from the value accessor template named Array Value Accessor that you created in the previous step.

Compile the project.
Deploy Examples.DataExchange.Providers.FileSystem.dll to the Sitecore server.

Set default values on the value accessor template

Before you can use the value accessor template, you must configure its converter type. In this example, the converter type must point to the plugin you created in Visual Studio.

To configure the converter type:

In the Content Editor, navigate to Templates/Data Exchange/Providers/File System/Data Access/Value Accessors/Array Value Accessor.
In right-hand pane, click the Builder tab.
On the menu ribbon, on the Builder OPTIONS tab, click Standard values.
Select the new item.

In the right-hand pane, set the following field values:

Name	Converter Type
Value	Examples.DataExchange.Providers.FileSystem.ArrayValueAccessorConverter, Examples.DataExchange.Providers.FileSystem

Note

The field Converter Type is in the Data Exchange Framework section. You might need to expand the section before you see the field.

Save the item.

Create a template for value accessor sets

You use a value accessor set to group a set of related value accessor objects.

You can create a custom template that only supports certain types of value accessors. In this example, all the value accessors you use are based on the Array Value Accessor template. Therefore the example shows you how to create a value accessor set that only allows array value accessors. When you have created the value accessor, you must set an icon for it.

To create a value accessor set template that displays only array value accessors:

In the Content Editor, navigate to Templates.
On the menu ribbon, on the Home tab, click New Template.

In the Select name dialog, enter the following values:

Field	Value
Name	Array Value Accessor Set
Base template	Templates/Data Exchange/Framework/Data Access/Value Accessor Sets/Value Accessor Set

Click Next.
In the Location dialog, select Templates/Data Exchange/Providers/File System/Data Access/Value Accessor Sets.
Click Next. In the confirmation dialog, click Close.
Select the new template, for example, Templates/Data Exchange/Providers/File System/Data Access/Value Accessor Sets/Array Value Accessor Set. In the right-hand pane, on the Content tab, click the icon next to the title.
In the Change Icon dialog, in the Icon field, enter Office/32x32/radio_button_group.png. Click OK.

Set default values on the value accessor set template

Before you use the array value accessor set template, you must configure the default insert options on the template.

To set default values on the template:

In the Content Editor, navigate to Templates/Data Exchange/Providers/File System/Data Access/Value Accessor Sets/Array Value Accessor Set.
In the right-hand pane, click the Builder tab.
On the menu ribbon, on the Builder OPTIONS tab, in the Template group, click Standard values.
In the content tree, select the new item, for example, Templates/Data Exchange/Providers/File System/Data Access/Value Accessor Sets/_Standard values. On the menu ribbon, on the CONFIGURE tab, in the Insert Options group, click Assign.
Remove all templates from the Selected list, and add the template Templates/Data Exchange/Providers/File System/Data Access/Value Accessors/Array Value Accessor.
Click OK. Save the item.

Do you have some feedback for us?

If you have suggestions for improving this article,