Walkthrough: Implementing a troubleshooter component

Version: 8.0

A troubleshooter is a component that lets a Sitecore user run logic that determines whether the selected Sitecore item is configured correctly and working properly.

This walkthrough adds a troubleshooter functionality to the file system provider configured in Implementing a custom provider for text files walkthrough series. It adds a troubleshooter that can determine whether a file system endpoint is configured to use a file that the Sitecore server has access to.

Troubleshooters were originally designed for endpoints. They are used to let a user determine whether an endpoint is configured properly. This remains the primary use of troubleshooters, but they can be used on any type of item, provided the item inherits from the following Data Exchange Framework base templates:

Convertible
Troubleshootable

The walkthrough shows you how to:

Construct the troubleshooter component
Specify a troubleshooter on an endpoint
Test the troubleshooter

Note

Finished code and installation packages are available in GitHub.

Construct the troubleshooter component

You must construct a troubleshooter component in Microsoft Visual Studio and deploy it to your server.

To construct a troubleshooter component:

In Visual Studio, add the following class:

RequestResponse

using Sitecore.DataExchange.Models;
using Sitecore.DataExchange.Troubleshooters;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace Examples.DataExchange.Providers.FileSystem
{
    public class TextFileEndpointTroubleshooter : BaseEndpointTroubleshooter
    {
        public TextFileEndpointTroubleshooter()
        {
        }
        protected override ITroubleshooterResult Troubleshoot(Endpoint endpoint, TroubleshooterContext context)
        {
            var settings = endpoint.GetPlugin<TextFileSettings>();
            if (settings == null)
            {
                return TroubleshooterResult.FailResult("The endpoint is missing the plugin TextFileSettings.");
            }
            if (string.IsNullOrWhiteSpace(settings.Path))
            {
                return TroubleshooterResult.FailResult("The endpoint does not have a file path specified on it.");
            }
            if (!File.Exists(settings.Path))
            {
                return TroubleshooterResult.FailResult(
                    "The path specified on the endpoint either " +
                    "points to a file that does not exist " +
                    "or the process does not have permission to read the file.");
            }
            return TroubleshooterResult.SuccessResult("The specified file exists and can be accessed.");
        }
    }
}

Note

This troubleshooter inherits from Sitecore.DataExchange.Troubleshooters.BaseEndpointTroubleshooter. You can create a custom troubleshooter for any type of component by inheriting from Sitecore.DataExchange.Troubleshooters.ITroubleshooter.

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

Specify a troubleshooter on an endpoint

You can specify a troubleshooter on any item that inherits from the Data Exchange Framework templates Convertible and Troubleshootable.

In this example, the troubleshooter is added to the text file endpoint, which inherits from the Base Endpoint template, which meets the criteria, so no additional work is needed.

To specify a troubleshooter on an endpoint:

In the Content Editor, navigate to /sitecore/templates/Data Exchange/Providers/File System/Endpoints/Text File Endpoint/__Standard Values.

In the right-hand pane, specify the following field value:

Field	Value
Troubleshooter Type	Examples.DataExchange.Providers.FileSystem.TextFileEndpointTroubleshooter, Examples.DataExchange.Providers.FileSystem

Save the item.

Test the troubleshooter

The troubleshooter was assigned to the text file endpoint, so to test the troubleshooter you must:

In Content Editor, select the tenant. Navigate to Endpoints/Providers/File System/City Information File.
On the menu ribbon, click Run Troubleshooter.

If the endpoint is configured properly, the file exists, and the Sitecore server can access the file, the success message is displayed.

If the endpoint does not have a file path specified, an error message is displayed.

If the endpoint has a file path specified, but the file does not exist, or file permissions prevent the Sitecore server from accessing the file, an error message is displayed.

Do you have some feedback for us?

If you have suggestions for improving this article,