CMP DAM Asset Picker in CMS

Package prerequisites

• EPiServer.CMS.Core 12.8.0 or later
• EPiServer.CMS.UI 12.9.0 or later

Install the Optimizely CMP integration package

1. Enter the following command to install the Optimizely Content Marketing Platform (CMP) integration package.
   C#

   $ dotnet add package EPiServer.CMS.WelcomeIntegration.UI
   

2. In Startup.cs add the following line:
   C#

   services.AddDAMUi();
   

Configure the Optimizely CMP integration

You can customize the integration in the EPiServer\Cms section of application.json:

{  
  "DAMUi" : {  
    "Enabled"  : true,  
    "Settings" : {  
      "Welcome" : {  
        "IconClass"      : "dijitNoIcon",  
        "AvailableTypes" : "episerver.core.imagedata",  
        "StoreName"      : "episervercmsdamcontentcreation",  
        "Endpoint"       : "https://cmp.optimizely.com",  
        "Path"           : "/cloud/library-picker"  
      }  
    }  
  }  
}

• IconClass – Choose an icon class. Default: dijitNoIcon.
• Availabletypes – Specify the editor command that is added only if it is (or inherited from) one of the available image types. Default: episerver.core.imagedata so properties that let you add an image have the new command.
• StoreName – Specify the server-side code (with your new store) to add your business logic. Default: episervercmsdamcontentcreation.
• EndPoint – Specify the endpoint to transform the root DAM domain for each environment you have (inte, preprod, or prod). Default: app.welcomesoftware.com.
• Path – Specify the path to the DAM library picker.

GlobalRootFolderGuid and RootFolderForTypes options properties

options.GlobalRootFolderGuid = "some-guid";
options.RootFolderForTypes = new Dictionary<string, IEnumerable<Type>>
{
    { "RootFolder1", new Type[] { typeof(DAMImageAsset), typeof(DAMVideoAsset) } },
    { "RootFolder2", new Type[] { typeof(DAMAsset) } }
};

The DAMOptions class includes the following properties to configure the root folder GUID and specify types for folders.

• GlobalRootFolderGuid – A string that represents the GUID of the global root folder.
• RootFolderForTypes – A dictionary that maps between folder names and types.

Configure the connection to CMP

📘

Prerequisite

Install Optimizely.Cmp.Client.

See Authenticate – Optimizely CMP Open API uses OAuth 2.0 as its authorization mechanism. Register an OAuth 2.0 app for an Optimizely Content Marketing Platform (CMP) organization to use the API. When your registration is successful, Optimizely CMP sends you a client_id and a client_secret.

An optional parameter to the AddDAMUi method lets you provide credentials.

services
  .AddDAMUi(
    o => o.Enabled = true,
    o =>
    {
      o.ClientId = "YourApplicationClientId";
      o.ClientSecret = "YourApplicationClientSecret";
    }
  );

You can also provide the Client ID and Client Secret through appsettings.json, as the second parameter in an Options configuration: CmpClientOptions.

📘

Note

Available only in CMS 12, Optimizely supports images, videos and some files, such as PDFs, Word Documents, Excel Spreadsheets, Zip and 7Zip files. In the case of files, an anchor tag is rendered to link to that specific file.

You have the following options to use this feature:

• Use the provided C# service to get the metadata from CMP by injecting the IDAMAssetMetadataService where you want to use it.
  The IDAMAssetMetadataService contains one method, GetAssetMetadata(Guid id), which retrieves metadata from CMP using the GUID of a specific asset. This GUID can be found within the information dialog of any asset in CMP.
• Use the HtmlHelper extension method, RenderTagWithMetadata which renders an appropriate HTML tag based on the retrieved asset.
  To use it, import @using EPiServer.Cms.WelcomeIntegration.UI.Helpers; inside a .cshtml page of choice, and use the page model that contains a ContentReference property.
  Then, call @await Html.RenderTagWithMetadata(x => x.YourWelcomeContentReference) with an expression that provides a ContentReference. You should link this ContentReference to a CMP Asset.
  Your page should now render an image, a video, or a link to the supported file with the respective metadata attached to the HTML tag.
• Use the TagHelper called DAMAssetTagHelper, which does the same thing as above but is used differently.
  To use it:
  1. Add the tag helper in your \_ViewImports.cshtml file:@addTagHelper \*, EPiServer.Cms.WelcomeIntegration.UI.
  2. Add \<dam-asset content-reference="@Model.YourWelcomeContentReference"/> to your .cshtml page of choice.
     Your page should now render an image, a video, or a link to the supported file with the respective metadata attached to the HTML tag.

The following example shows HtmlHelper and TagHelper on Alloy site:

@using EPiServer.Cms.WelcomeIntegration.UI.Helpers;
@model PageViewModel<StandardPage>
  
  Using HtmlHelper
  @await Html.RenderTagWithMetadata(x => x.CurrentPage.WelcomePageImage)
                                    
  Using TagHelper
  <dam-asset content-reference="@Model.CurrentPage.WelcomePageImage"/>         

The result is shown in the following image.

In some scenarios, it is not possible to use HtmlHelper or TagHelper and the metadata must be loaded from CMP in other contexts. In this case, you can use IDAMAssetIdentityResolver and IDAMAssetMetadataService instead, as shown in the following example:

public class DamAssetInfoExample
{
    private readonly IDAMAssetIdentityResolver _resolver;
    private readonly IDAMAssetMetadataService _service;
  
    public DamAssetInfoExample(IDAMAssetIdentityResolver resolver, IDAMAssetMetadataService service)
    {
        _resolver = resolver;
        _service = service;
    }

    /// <summary>
    /// Retrieve asset metadata from CMP
    /// </summary>
    /// <param name="contentReference">Content Reference to an asset in the DAM content provider</param>
    /// <returns></returns>
    public async Task<DamAssetInfo?> Get(ContentReference contentReference)
    {
        var asset = _resolver.Get(contentReference);
        var guid = GetAssetGuid(asset);
        if (guid.HasValue)
        {
            return await _service.GetAssetMetadata(guid.Value);
        }

        return null;
    }

    /// <summary>
    /// Helper to determine if the guid on the asset is an image or a rendition
    /// </summary>
    /// <param name="assetIdentity"></param>
    /// <returns></returns>
    private static Guid? GetAssetGuid(DAMAssetIdentity assetIdentity)
    {
        bool TryParseRendition(string id, out Guid? renditionGuid)
        {
            renditionGuid = null;
            if (string.IsNullOrWhiteSpace(id))
            {
                return false;
            }

            if (Guid.TryParse(id, out var guid))
            {
                renditionGuid = guid;
                return true;
            }

            return false;
        }
        bool TryParseImage(string id, out Guid? imageGuid)
        {
            imageGuid = null;
            if (string.IsNullOrWhiteSpace(id))
            {
                return false;
            }

            var decodedId = Encoding.UTF8.GetString(Convert.FromBase64String(id)).Split("=")[1];

            if (Guid.TryParse(decodedId, out var guid))
            {
                imageGuid = guid;
                return true;
            }

            return false;
        }

        var assetId = assetIdentity.DAMAssetUri.Segments.Last();

        if (TryParseRendition(assetId, out Guid? renditionGuid))
        {
            return renditionGuid.Value;
        }

        if (TryParseImage(assetId, out Guid? imageGuid))
        {
            return imageGuid.Value;
        }

        return null;
    }
}

Configure security headers

If your site uses content security policy (CSP) headers, ensure that https://app.welcomesoftware.com is included to prevent errors in the CMS UI when selecting assets.

Related topics

📘

Looking for installation on CMS 11?

See Install the Optimizely DAM Asset Picker (for CMS 11).

• Optimizely CMP DAM Asset Picker
• Configuration
• Cms section