Area: Optimizely Commerce
Applies to versions: 7.5

Migrating assets to the media system

Recommended reading 


This document descibes how to migrate assets for an EPiServer Commerce site in order to use the new EPiServer media/asset API. The procedure is required to be able to use existing assets for instance when editing products in the new Catalog Edit view. The asset migration tool can be downloaded from EPiServer World.

It is highly recommended to back up your site before starting the migration.

Using the asset migration tool

Adding content type

Before you can use the ECF asset migration tool, the Commerce site must be updated to include a new media data content type, a class inherited from EPiServer.Core.MediaData.


        [ContentType(GUID = "1ACF9AB9-A992-43F1-8058-D155794EBE68")] 
        public class GenericFile : MediaData
            public virtual string Description { get; set; }

You will need to compile and then reload the site to ensure that the new content type is created.

Preparing the destination folder for migration

The migrated assets will be placed in the folder "Catalogs\Root" (which is the same folder structure as in Commerce Manager). If you already have a folder named "Root" containing your assets, it is recommended to rename it to avoid conflicts between created and migrated files, since the migration tool will skip a file if it exists in "Catalogs\Root".

Migration tool options

Download and unzip the files. Continue by executing the asset migration tool.

Enter migration options as follows:

  • Site Path is the path to the Commerce site. This is important as the migration tool must initialize your site in order to work.
  • Continue On Error means that the migration tool will continue to work even when exceptions occur.
  • Show Log means that the migration tool will display a migration log.

Click Migrate to start the migration. Depending on the number of assets and catalog entries, the migration may take from a couple of minutes to half an hour to complete.

Note that the migration tool will also migrate the folder structure from ECF to CMS. If those folders already exists, the creation of these will be skipped.

Note that you need to restart the site after migration to clear the existing cache from any CMS asset content. It is also recommended to finalize the migration before making any changes to the site, for instance recompiling code.

Update settings in Commerce Manager

Do the following to update the web.config of Commerce Manager to make it use the new EPiServer asset system: set the value of UseLegacyAssetSystem key in appSettings section to "false". This will disable the "legacy" way of accessing of assets in Commerce Manager.

Update code to use the new Asset API

Removing FolderElementEntity

Originally, the CatalogItemAsset table stores the key of an asset in the AssetKey column, which is used by FolderElementEntity to retrieve blobs in ECF. After migration, the CatalogItemAsset table will be updated to store the GUID of the content created in CMS. Therefore, code relying on this table must be updated to remove any usage of FolderElementEntity, otherwise the site may not work after the migration.

The new way to retrieve assets is to get the media content by GUID(s) stored in Assets, as in the following example:

/// <summary>
/// Gets all asset elements by group name, unsupported file extension is omitted.
/// </summary>
/// <param name="groupName">Name of the group.</param>
/// <returns>List of asset elements related to group name.</returns>
private List<string> GetAllAssetElement(Entry entry, string groupName)
    var filteredItemAssets = entry.Assets.Where(i =>
        i.AssetType != null
        && i.GroupName != null
        && i.AssetType.Equals("File", StringComparison.OrdinalIgnoreCase)// is file
        && i.GroupName.Equals(groupName, StringComparison.OrdinalIgnoreCase));// in groupName

    var urls = new List<string>();
    foreach (var item in filteredItemAssets)
        var assetKey = item.AssetKey;
        var contentRepository = ServiceLocation.ServiceLocator.Current.GetInstance<IContentRepository>();
        var media = contentRepository.Get<MediaData>(new Guid(assetKey));
        urls.Add(UrlResolver.Current.GetVirtualPath(media.ContentLink, "en").GetUrl());
    return urls;

Default image

In EPiServer Commerce, the ECF API provides a default product image in case no asset is found. Since the CMS asset API does not support this feature, it is therefore necessary to specify a default product image.


Do you find this information helpful? Please log in to provide feedback.

Last updated: Oct 20, 2016

Recommended reading