Sana Assistant (online)
Table of Contents

Product Export Tutorial

From this article you will learn how to create product export extension. Custom product export extension is used as an example in this article.

Please use the following reference articles to find more details on extensions infrastructure:

Start with a new project

Create a new add-on project named "Sana.Extensions.CustomProductExportExtension" as described in the add-on development tutorial.

Implement the extension class

Create a new class CustomProductExportExtension inherited from ProductExportExtension. More information about ProductExportExtension can be found in ProductExportExtension reference article.

public class CustomProductExportExtension : ProductExportExtension
{
}

Implement configuration class

Create a new class ProductExportConfiguration inherited from the ExtensionConfiguration and decorate it with ConfigurationKey attribute. This class will be used by Sana as a view-model to configure product extension in Sana Admin. More details about extension configuration class can be found in Extension configuration article.

[ConfigurationKey("ProductConfiguration")]
public class ProductExportConfiguration : ExtensionConfiguration
{
}

Let's add properties which are needed to configure the product export extension to the ProductExportConfiguration.

[ConfigurationKey("ProductConfiguration")]
public class ProductExportConfiguration : ExtensionConfiguration
{
    [Display(Name = "User name", Description = "Name of API user.")]
    [Required]
    [DataType(DataType.Text)]
    public string Username { get; set; } = string.Empty;

    [Display(Name = "Password", Description = "Password of API user.")]
    [Required]
    [DataType(DataType.Password)]
    public string Password { get; set; } = string.Empty;

    [Display(Name = "File name", Description = "File name.")]
    [Required]
    [DataType(DataType.Text)]
    public string FileName { get; set; } = "Products.json";
}

You can decorate the properties with data annotation attributes since this class is a model for a view. See Extension configuration article for more details.

Implement IConfigurable<TConfiguration> interface in CustomProductExportExtension. Put ProductExportConfiguration class as a generic type parameter for IConfigurable<TConfiguration>, it will indicate that our product extension should be configured with this class.

public class CustomProductExportExtension : ProductExportExtension, IConfigurable<ProductExportConfiguration>
{
    public ProductExportConfiguration Configuration { get; set; }
}

Sana will initialize Configuration property with configuration settings entered in Sana Admin on the extension configuration page.

Implement GetLoadOptions method

Implement GetLoadOptions method of ProductExportExtension class.

This method provides ability to load specific data during export process.

See LoadOptions reference of product export extension for more details.

public override LoadOptions GetLoadOptions() =>
    new LoadOptions
    {
        LoadEnrichment = true,
        LoadProductInfo = true,
        LoadImages = true,
        LoadInventory = true,
        LoadPrices = true,
        LoadUrls = true,
        LoadRelatedSkus = true,
        LoadRelatedProducts = true,
    };

Implement OnStart method

Implement OnStart method of ProductExportExtension class.

This method is used to write ExportContext data to the file.

See OnStart method of product export extension for more details.

public override void OnStart(ExportContext context)
{
    Api.Log($"Start");

    var jsonSerializerSettings = CreateJsonSerializerSettings();

    Api.DataFiles.DeleteFile(Configuration.FileName);

    try
    {
        using (Stream stream = Api.DataFiles.OpenWrite(Configuration.FileName))
        using (StreamWriter writer = new StreamWriter(stream))
        {
            var json = JsonConvert.SerializeObject(context, jsonSerializerSettings);
            writer.Write(json);
        }
    }
    catch (Exception ex)
    {
         Api.LogError($"OnStart - Exception: {ex.Message}");
    }
}

private JsonSerializerSettings CreateJsonSerializerSettings()
{
    return new JsonSerializerSettings
    {
        Formatting = Formatting.Indented,
    };
}

Implement OnSuccess method

Implement OnSuccess method of ProductExportExtension class.

Sana calls OnSuccess method when execution of the extension successfully finished.

See OnSuccess method of product export extension for more details.

public override void OnSuccess(ExportContext context)
{
    Api.Log($"Product export extension saved data to files");
    // If needed there can be code for logging, freeing memory, deleting temporary files, etc.
}

Implement OnFail method

Implement OnFail method of ProductExportExtension class.

This method is used to correctly finish extension execution when an error occurs. Sana calls OnFail method when errors occurred during execution of the extension.

See OnFail method of product export extension for more details.

public override void OnFail(ExportContext context)
{
    Api.LogError($"Error occurred during execution of the product export extension");
    // If needed there can be code to finish extension execution correctly (logging, freeing memory, deleting temporary files, etc).
}

Implement OnFinalize method

Implement OnFinalize method of ProductExportExtension class.

This method is called at the end of execution.

See OnFinalize method of product export extension for more details.

public override void OnFinalize(ExportContext context)
{
    Api.Log($"Product export extension execution is completed.");
    // If needed there can be code to finish execution of the extension (logging, deleting temporary files, etc).
}

Implement ProcessBatch method

Implement ProcessBatch method of ProductExportExtension class.

This method is used to save data into temporary file based on loading options and task configurations.

See ProcessBatch method of product export extension for more details.

public override void ProcessBatch(ProcessBatchContext context)
{
    var jsonSerializerSettings = CreateJsonSerializerSettings();

    try
    {
        using (Stream stream = Api.DataFiles.OpenWrite(Configuration.FileName))
        {
            stream.Seek(0, SeekOrigin.End);

            using (StreamWriter writer = new StreamWriter(stream))
            {
                var json = JsonConvert.SerializeObject(context.Products, jsonSerializerSettings);
                writer.Write(json);
            }
        }
    }
    catch (Exception ex)
    {
        Api.LogError($"ProcessBatch - Exception: {ex.Message}");
    }
}

Implement GetFilesToExport method

Implement GetFilesToExport method of ProductExportExtension class.

This method returns extension files to be exported as result of the extension.

See GetFilesToExport method of product export extension for more details.

public override IEnumerable<string> GetFilesToExport()
{
    return Api.DataFiles.GetFiles();
}

See also