CMP DAM in CMS

When integrated with Optimizely Graph, Optimizely Content Management System (CMS) can fetch data from Optimizely Content Marketing Platform (CMP) asset metadata in Optimizely Digital Asset Management (DAM) without relying on the CMP API. Optimizely Graph integration provides better performance than using the CMP REST API to fetch metadata. Optimizely Graph also lets you perform other actions like querying for images, videos, renditions, folders, and more.

📘

Notes

• The CMP DAM integration with CMS requires the following versions:
  • EPiServer.Cms.Core 12.22.1
  • EPiServer.Cms.UI 12.32.0
  • EPiServer.Cms.WelcomeIntegration.UI 2.0.0 or later

Integrate Optimizely CMP

1. Install or update the EPiServer.Cms.WelcomeIntegration.UI package to version 2.0.0 or later.

   C#

   $ dotnet add package EPiServer.CMS.WelcomeIntegration.UI
   

2. Install or update EPiServer.Cms.WelcomeIntegration.Graph package to version 2.0.0 or later.

   C#

   $ dotnet add package EPiServer.CMS.WelcomeIntegration.Graph
   

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

   JavaScript

   {  
   "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.

Configure optional starting folders

Configuring the starting folders allows lets you launch the CMP DAM Library Picker in a specific folder, determined globally or by the requested asset type.

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 REST API

📘

Prerequisite

Install Optimizely.Cmp.Client. REST API lets you track assets and retrieve asset metadata through scheduled jobs. However, you should use Optimizely Graph to retrieve metadata.

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.

If you cannot use HtmlHelper or TagHelper in some scenarios, you must load the metadata from CMP in other contexts. 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.

Integrate Optimizely Graph

📘

Notes

• The integration requires EPiServer.Cms.WelcomeIntegration.Graph 2.0.0 or later.
• Starting November 2024, you should use the Optimizely Graph-supported version of this integration for optimal performance.
• Starting December 2024, the Optimizely.Graph.Client 1.4.0 release introduced TransformActionBehaviour that lets you query both CMS and DAM in the same scope using different SingleKey.
• Content in CMS and assets in DAM each have separate indexes that must be queried using a separate SingleKey.
• CMP lets you index DAM assets into Optimizely Graph. Go to Settings \ Organization \ Misc and click on Enable & Sync for DAM. After the sync has completed, a URL with the SingleKey displays.

1. Install or update the EPiServer.Cms.WelcomeIntegration.UI package to version 2.0.0 or later.

   C#

   $ dotnet add package EPiServer.CMS.WelcomeIntegration.UI
   

2. Install or update EPiServer.Cms.WelcomeIntegration.Graph package to version 2.0.0 or later.

   C#

   $ dotnet add package EPiServer.CMS.WelcomeIntegration.Graph
   

3. Add the following calls to Startup.cs.

   C#

   services.AddDAMUi();
   services.AddDAMGraphIntegration();
   

4. If you do not already have a CMP DAM-to-Graph integration, then (in CMP) go to your avatar > Organization > Misc. tab.

   1. Scroll to the bottom of the Misc. tab and click Enable & Sync.

      

      📘

      Note

      Time for the first sync depends on the number of assets being synced (but the URL will be immediately available).

   2. After the sync completes, the button is replaced with a URL that you need to configure CMS (similar to https://cg.optimizely.com/app/graphiql?auth=SINGLE_KEY in the following image).

      

5. Add the following configuration in appsettings.json. You can keep the AppKey, Secret and SingleKey as dummy values because they are not used by the DAM integration. If you already have Optimizely Graph for CMS configured, leave the values as-is.

6. JSON

   "Optimizely": {  
     "ContentGraph": {  
       "GatewayAddress": "https://cg.optimizely.com",  
       "AppKey": "APPKEY",  
       "Secret": "SECRET",
       "SingleKey": "SINGLE_KEY",
       "TransformActionBehaviour": "Clone"
     }  
   }
   

   Configure TransformActionBehaviour to Clone if you plan on using Optimizely Graph-indexed content from CMS and indexed assets from DAM. If you use both sources, the SingleKey differs between them, and you need to clone the configuration. If CMS content is not indexed or queried, then there is no need for this.

7. The CMP+Graph integration uses a different schema and a separate SingleKey. Configure the following code in appsettings.json.

   JSON

   "EPiServer": {  
     "Cms": {  
       "CMPGraph": {  
          "SingleKey": "SINGLE_KEY"  
       }  
     }  
   }
   

   Or in Startup.cs.

   C#

   services.Configure<CMPGraphOptions>(options => {  
     options.SingleKey = "SINGLE_KEY";  
   });
   

   📘

   Note

   If your CMP/DAM instance is Optimizely Graph-enabled, you can find the key on the Misc tab under the Organization settings in CMP. The Single Key is the value of the auth query parameter of the URL listed under Content Graph Settings/DAM.

   

   If you do not see Content Graph Settings, contact Optimizely Support to enable it. Provide the name and SSO ID for your CMP instance (you can find the SSO ID under the General tab of the Organization settings.

Use CMP DAM to render assets

CMP DAM integration can render HTML tags (like <img>) through information from Optimizely services or by querying Optimizely Graph. This is the simplest approach and involves using the TagHelper and HtmlHelper. When the Optimizely Graph integration is configured, the helpers are powered by Optimizely Graph.

Retrieve asset data with IDAMAssetMetadataService

The GetAssetMetadatamethod on IDAMAssetMetadataServicelets you retrieve the latest metadata. Query the services using the identifier of the asset in CMP, which you can retrieve in a CMS context using the IDAMAssetMetadataService to get the DAM asset identity.

Query Optimizely Graph data

The CMS+CMP/DAM integration queries Optimizely Graph for metadata automatically, and you do not need to understand the schema or create your own GraphQL queries to use it. However, you have access to Optimizely Graph and can query it using your favorite GraphQL client.

The following example lists images with a public Url in the folder Hotels. Assets from CMP DAM are indexed in a separate index from CMS content. The following example query can only be used with the correct SingleKey as previously described.

Scheduled jobs for CMS and CMP DAM integration

The integration relies on two scheduled jobs to maintain data consistency in the integration between CMS and CMP DAM.

• Optimizely CMP DAM assets metadata maintenance – Syncs the metadata from CMP DAM to CMS each time it is executed. CMS maintains a persistent cache of CMP DAM asset metadata such as alternate text for an image to deliver consistent performance. Execute this job to avoid inconsistencies in metadata, such as alt text or SEO URLs in CMP.

  📘

  Note

  An asset is referenced from CMS the first time and then the metadata is synced at the moment of publishing the content that references the assets.

• Optimizely CMP DAM Tracking Assets – Tracks asset usage in asset lineage and finds all references to CMP DAM assets in published content in CMS. The job also reports the URL to those content instances to the CMP DAM. After the job is completed, view active references in published content in CMP under the header asset usage. Execute this job to avoid inconsistencies in asset usage.

Related topics

• Optimizely CMP DAM Asset Picker
• Configuration
• Cms section

📘

Looking for installation on CMS 11?

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