Blog posts by Robert Svallin2026-04-12T08:48:22.0000000Zhttps://world.optimizely.com/blogs/robert-svallin/Optimizely WorldCMS 12 - Optimizely DAM Integration 2.2.0<div>
<h2>What's New in Optimizely DAM Integration 2.2.0</h2>
Version 2.2.0 of the Optimizely DAM (CMP) integration for CMS 12 is a pretty big release. Many of the improvements here come directly from customer feedback and real-world production observations. The result is a more reliable, faster, and more consistent integration across the board.</div>
<div> </div>
<div>This release was developed in parallel with CMS 13, and will most likely be the last version to introduce new features for the CMS 12 integration. CMS 13 adopts the SaaS integration model, which works in a fundamentally different way. Going forward, our focus is on the CMS 13 integration. CMS 12 will continue to receive critical fixes, but new feature work will target CMS 13.</div>
<div>
<h3>A Note on REST API vs Graph Integration</h3>
While this release includes improvements to both the REST API and Graph integration paths, Optimizely strongly encourages developers to move to the Graph integration if you haven't already. The REST API integration has inherent performance limitations and implements rate limiting that can result in 429 (Too Many Requests) status codes under heavy use. This becomes particularly problematic in high-traffic production environments where multiple concurrent requests to CMP can trigger throttling.</div>
<div> </div>
<div>The Graph integration provides a better alternative. It handles high-volume requests without rate limiting issues, offers better query performance, and scales more effectively for production workloads. While this version continues to address issues in the REST API integration for those still using it, the recommended path forward is to migrate to Graph integration.</div>
<h3>Performance: Cached Metadata During Rendering</h3>
<div>
<div>All rendering helpers now reuse cached metadata from the database. This includes the DAMAssetTagHelper (<dam-asset> tag), HtmlHelpers.RenderTagWithMetadata(), and the new IUrlHelper.DamAssetUrl() extension method. The integration only makes API calls when cached metadata is incomplete, specifically when the URL or MIME type is missing. In typical use cases, metadata is populated during content publishing or by the scheduled maintenance job, which means render-time API calls are eliminated entirely.</div>
<br />
<div>For a page with 10 DAM assets, the previous implementation would make 10 separate Graph API calls on each render, adding 500-2000ms of latency depending on network conditions and API load. The cached approach retrieves the same data from the database in under 10ms total. For production sites with high traffic, this typically reduces API calls by 95% or more on steady-state pages.This is probably the change you'll notice most. Previously, the TagHelper and HtmlHelper components made live API calls to CMP Graph every time a page was rendered, even though the metadata was already cached in the CMS database. On high-traffic sites with many assets, this behavior led to SNAT port exhaustion and unnecessary load on the Graph API.</div>
</div>
<h3>New URL Helper Extension</h3>
<div>Version 2.2.0 introduces IUrlHelper.DamAssetUrl() for direct URL generation from cached metadata:</div>
<div>
<pre class="language-csharp"><code>@using EPiServer.Cms.WelcomeIntegration.UI.Helpers
<!-- Basic asset URL -->
<img src="@Url.DamAssetUrl(Model.CurrentPage.HeroImage)" alt="Hero" />
<!-- Specific rendition URL -->
<img src="@Url.DamAssetUrl(Model.CurrentPage.HeroImage, "thumbnail")" alt="Thumbnail" /></code></pre>
<br />
<div>The method follows this priority chain:</div>
<ol>
<li>Rendition URL (if rendition name provided and exists in cached metadata)</li>
<li>Main asset URL (from cached metadata)</li>
<li>IUrlResolver fallback (if metadata unavailable)</li>
<li>Empty string (if ContentReference is null/empty)</li>
</ol>
<h3>DAM Deep Linking for All Property Types</h3>
When replacing an existing DAM asset on a content page, the DAM picker opens with the current asset pre-selected, making it easy to browse related assets or pick a different version. In previous releases, this deep linking only worked for properties backed by a `ContentReference`. Properties that store a URL instead, such as `UrlToImage` or `LinkItem`, would open the picker without any context about the current selection.</div>
<div> </div>
<div>The integration now resolves URL-based values server-side before opening the picker. When an editor clicks "replace" on a property that stores a URL, the integration resolves the URL back to a content reference and looks up the corresponding DAM asset. The picker then opens with that asset pre-selected. A small improvement, but one that removes a real friction point for editors working with different property types.<br />
<h3>Metadata Consistency Across REST API and Graph</h3>
The integration now provides consistent metadata regardless of whether you retrieve asset information through the CMP REST API or Optimizely Graph. Previously, the data available in the CMS database varied depending on the retrieval method, which created inconsistencies in how assets were stored and rendered.</div>
<div> </div>
<div>The normalization work ensures that three key metadata properties are now consistently populated from both sources. The <strong>Description</strong> field, which was previously only available when using the REST API, is now properly retrieved from Graph as well. <strong>Renditions</strong>, alternative asset versions like thumbnails, banners, and other predefined sizes, are now correctly fetched and stored regardless of the data source. Additionally, the <strong>FocalPoint</strong> property has been restored. This smart crop coordinate data (X, Y values) was available in the 1.x versions of the integration but had been missing in 2.x releases.<br />
<div>For REST API users, rendition fetching requires explicit configuration. Configure `GetRenditions` to enable rendition data, and optionally GetRenditionsWidthAndHeight to include dimension information:</div>
</div>
<div>
<pre class="language-csharp"><code>services.AddCMPRestApi(options =>
{
options.GetRenditions = true;
options.GetRenditionsWidthAndHeight = true;
});</code></pre>
<br /><br />Graph queries are unaffected by these settings and include renditions by default. See the Upgrading section below for additional configuration details.<br />
<div> </div>
<div>With Description, Renditions, and FocalPoint now included, the metadata story is complete. The integration covers the full set of properties that will be synchronized from CMP, and no additional metadata fields are planned for future releases.</div>
<br />
<h3>Document and Video Fixes</h3>
<strong>Video and document metadata in Graph</strong>. The Graph integration now handles all asset types uniformly. In previous versions, retrieving metadata for videos or documents through Graph would result in a null DAMAssetInfo, while the same request through the REST API would return proper metadata including title, MIME type, and URL. This discrepancy has been resolved, and the Graph integration now correctly retrieves and populates metadata for images, videos, and documents alike.<br />
<div> </div>
<div><strong>Document rendering</strong>. The rendering helpers previously only recognized a hardcoded list of nine application/* MIME types (PDF, Office formats, ZIP) as downloadable documents. Assets with other application/* types fell through to a default case that rendered a <div> with the asset title but no link, making the output non-functional. Text-based documents like CSV or plain text files produced no output at all. This release fixes document rendering so that all document types produce working download links. Text-based documents (text/*) are now explicitly handled, the hardcoded allowlist for application/* types has been removed so all application formats are treated consistently, and the default fallback for any unrecognized MIME type now renders a download link as well.</div>
<br />
<h3>Rendition Retrieval Fixes</h3>
</div>
<div>
<p>Fixed a bug where Renditions was null when calling IDAMAssetMetadataService.GetAssetMetadata(Guid id) or when stored metadata had no Type value. The metadata service previously only fetched renditions when assetType was explicitly DAMAssetType.Image, but several code paths passed null for this parameter.</p>
<p>The service now fetches renditions regardless of the assetType value.</p>
</div>
<h3>Asset Tracking Improvements</h3>
<div>The asset tracking system has been improved to correctly handle removals from rich text fields. When you removed a DAM asset from an `XhtmlString` field and published the page, the tracking metadata would remain in the database, making it appear that the asset was still in use. The tracking system now properly updates when assets are removed from `XhtmlString` fields, ensuring the `Trackings` field is correctly nullified when assets are no longer referenced.</div>
<h3>Upgrading to 2.2.0</h3>
<div>Upgrading to version 2.2.0 is straightforward. Update the NuGet packages to version 2.2.0:</div>
<div>
<pre class="language-python"><code>dotnet add package EPiServer.CMS.WelcomeIntegration.UI --version 2.2.0
dotnet add package EPiServer.Cms.WelcomeIntegration.Core --version 2.2.0
dotnet add package EPiServer.Cms.WelcomeIntegration.Graph --version 2.2.0</code></pre>
<br />
<div>If you're still using the REST API endpoint, consider this a good time to migrate to the Graph integration. The REST API path carries inherent performance limitations including rate limiting that can cause 429 errors under load, and future development efforts will prioritize the Graph integration. The <a href="https://docs.developers.optimizely.com/content-management-system/docs/cmp-dam-in-cms">official documentation </a>covers the migration path.</div>
<br />
<div>For REST API users who are not yet ready to migrate and want to retrieve renditions, you'll need to add configuration:</div>
<br />
<div>
<pre class="language-javascript"><code>{
"CMPRestApi": {
"GetRenditions": true,
"GetRenditionsWidthAndHeight": true
}
}</code></pre>
</div>
<br />
<div>After upgrading, run the "Optimizely DAM Maintenance" scheduled job to backfill missing metadata for existing assets. The job will populate Description, Renditions, and FocalPoint data for assets that were created before the upgrade.</div>
<div> </div>
Version 2.2.0 closes a lot of gaps that we have received feedback on over time. If you run into issues after upgrading, or if something doesn't behave the way you'd expect, file an issue through Optimizely Support. That feedback is what shaped most of this release, and it will shape what comes next for CMS 13.</div>
<div>
<div> </div>
</div>2026-04-12T08:48:22.0000000ZBlog postCMS 13 Preview 4 — Upgrading from Preview 3<p>This is the third post in a series where I use the Alloy template as a reference to walk through each CMS 13 preview. The <a href="/link/401767d8a5e8446db6e213b139618c2d.aspx">first post</a> covered upgrading from CMS 12 to Preview 2, and the <a href="/link/440e06e8b64e4e80aa1b65dc833d9ec2.aspx">second</a> looked at the key changes in Preview 3. If you're following along, pick up where we left off.</p>
<p>Preview 4 is out. The package bump is easy enough, but there's an API change around how you resolve the start page that'll ripple through your code. Here's what to change and what's worth knowing about.</p>
<h2>Step 1: Update Packages</h2>
<p>Bump your package references from preview3 to preview4:</p>
<pre class="language-html"><code><PackageReference Include="EPiServer.CMS" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.CMS.UI.AspNetIdentity" Version="13.0.0-preview4" />
<PackageReference Include="Optimizely.Graph.Cms" Version="13.0.0-preview4" /></code></pre>
<div>
<h3>Known Issue: Database Schema Upgrade from Older CMS 12 Versions</h3>
If you're upgrading directly from an older CMS 12 version (e.g. 12.34.1 or earlier) to a CMS 13 preview and not from preview3 (which this article assumes), the database schema migration may fail with an error like:</div>
<div>
<pre class="language-html"><code>Column names in each table must be unique. Column name 'Failed' in table 'dbo.tblNotificationMessage' is specified more than once.</code></pre>
This happens because certain columns were added in later CMS 12 releases, and the CMS 13 migration scripts don't check whether they already exist before trying to add them.<br />
<div>Workaround: First upgrade to the latest CMS 12 version so that your database schema is fully up to date, then upgrade from there to the CMS 13 preview. This ensures all intermediate schema changes are applied before the CMS 13 migration runs.</div>
</div>
<h2>Step 2: Resolving the Start Page</h2>
<p>In Preview 3, Alloy template resolved the start page by casting to Website and accessing RoutingEntryPoint. In Preview 4, the simplest approach is to use ContentReference.StartPage directly — no need to go through IApplicationResolver in most cases.</p>
<p><strong>Before (Preview 3)</strong></p>
<pre class="language-csharp"><code>var website = _applicationResolver.GetByContext() as Website;
var startPageContentLink = website?.RoutingEntryPoint;</code></pre>
<p><strong>After (Preview 4)</strong></p>
<pre class="language-csharp"><code>var startPageContentLink = ContentReference.StartPage;</code></pre>
<p>In the Alloy template this simplified things across several files by using ContentReference.StartPage <br />- <strong>PageViewContextFactory.cs</strong> — CreateLayoutModel <br />- <strong>ContentLocator.cs</strong> — GetContactPages <br />- <strong>PreviewController.cs</strong> — the Index action<br />- <strong>StartPageController.cs</strong> — the Index action<br />- <strong>Breadcrumbs.cshtml</strong> and <strong>Header.cshtml</strong> — same change</p>
<p>If you do need more control, IRoutableApplication with its EntryPoint property is still available as an alternative.</p>
<p>The SiteDefinition migration keeps getting refined. Issues with default application provisioning and hostname resolution between preview and view modes from earlier previews have been sorted out.</p>
<h2>Step 3: DAM Integration (optional)</h2>
<p>Preview 4 adds a new package for Optimizely DAM integration. Its important to call out that even though DAM is a fundamental piece of CMS 13 it is possible to run without it. CMS still can store assets in te traditional sense.</p>
<p>Similar to CMS 12 the DAM configuration is handled using options directly requiring an application to be created in CMP from which the credentials can be retrieved for configuration in CMS. You'll also need the SSO ID which can be found under <strong>Settings \ Organization \ General</strong> in CMP.</p>
<p>The DAM integration no longer talks to the CMP REST API directly. Instead it's built on External Sources, which means DAM assets need to be indexed into the Optimizely Graph instance connected to your CMS. So before wiring up the code below, make sure you have Optimizely Graph set up, then contact Optimizely Support to connect DAM to your Graph instance. The onboarding steps — selecting your DAM instance, activating asset types — follow the same process as CMS SaaS and are documented in the <a href="https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/docs/onboard-dam-to-cms-saas">Onboard DAM to CMS guide</a>. Updated documentation specific to CMS 13 will be available at release. Once that's done, Content Manager can be used to discover and pick DAM assets directly from the editing UI.</p>
<p>Add the package:</p>
<pre class="language-html"><code><PackageReference Include="EPiServer.Cms.DamIntegration.UI" Version="13.0.0-preview4" /></code></pre>
<p>Register the DAM UI in Startup.cs:</p>
<pre class="language-csharp"><code>services.AddDamUI();</code></pre>
<p>Add the DAM HTML helpers namespace to Views/_ViewImports.cshtml:</p>
<pre class="language-csharp"><code>@using EPiServer.Cms.DamIntegration.UI.Helpers</code></pre>
<p>This gives you access to helpers like RenderTagWithMetadata(...) for rendering DAM assets. Note that the epi-property tag helper you're already using comes from EPiServer.Cms.AspNetCore.TagHelpers, which should already be registered in your _ViewImports.cshtml via @addTagHelper.</p>
<p>Then configure your CMP credentials (note that these have defaults, included here for transparency) in appsettings.json:</p>
<pre class="language-javascript"><code>"Optimizely": {
"Cms": {
"DamUI": {
"Endpoint": "https://cmp.optimizely.com",
"SsoId": "<your-sso-id>",
"NavigationUrl": "https://cmp.optimizely.com/cloud/library"
}
},
"Cmp": {
"Client": {
"TokenUrl": "https://accounts.cmp.optimizely.com/o/oauth2/v1/token",
"ApiUrl": "https://api.cmp.optimizely.com/v3/",
"ClientId": "<your-client-id>",
"ClientSecret": "<your-client-secret>"
}
}
}</code></pre>
<p>The DAM picker now also supports multi-select, which is a nice improvement for editors working with lots of media.</p>
<h3>Migrating from CMS 12 DAM Integration</h3>
<p>For the GA release of CMS 13, a standalone migration package will be available that converts the CMS 12-style DAM integration to the new one. This package will handle the migration of existing DAM asset references so that they work with the new EPiServer.Cms.DamIntegration.UI package.</p>
<p>The first version of the migration package will support:<br /> - ContentReference properties<br /> - IList<ContentReference> properties</p>
<p>Support for additional property types will be added in future releases.</p>
<h3>Using DAM Assets in Your Content</h3>
<p>To use DAM assets on a page, add a ContentReference property with the UIHint.Image hint:</p>
<pre class="language-csharp"><code>using EPiServer.Web;
using System.ComponentModel.DataAnnotations;
public class DamExamplePage : StandardPage
{
[Display(GroupName = Globals.GroupNames.Content)]
[UIHint(UIHint.Image)]
public virtual ContentReference Image { get; set; }
}</code></pre>
<p>In the view, render it with the epi-property tag helper — same pattern as any other CMS property:</p>
<pre class="language-html"><code><img epi-property="@Model.CurrentPage.Image" /></code></pre>
<h2>Step 4: Audiences (optional)</h2>
<p>Audiences are a separate package in CMS 13. If you were using services.AddVisitorGroups() in Preview 3, you'll need to add the new NuGet package and update your service registration.</p>
<p>Add the package:</p>
<pre class="language-csharp"><code><PackageReference Include="EPiServer.Cms.UI.VisitorGroups" Version="13.0.0-preview4" /></code></pre>
<p>Then update your Startup.cs — the old AddVisitorGroups() call is replaced with two separate registrations:</p>
<pre class="language-csharp"><code>using EPiServer.Cms.UI.VisitorGroups;
services.AddVisitorGroupsMvc().AddVisitorGroupsUI();</code></pre>
<p>A few audience-related bugs have also been fixed: the policy-not-found error is gone, Geographic Location criteria works, and context menu positioning for personalized groups has been corrected.</p>
<h2>What Else Is New in Preview 4</h2>
<p>A few things worth knowing about beyond the upgrade steps:</p>
<h3>Graph .NET SDK</h3>
<p>There's a new .NET SDK for Optimizely Graph with a fluent API covering facets, caching, auth, tracking, and object-to-Graph field mapping. Extensibility points have also been added to ContentGraph.CMS so you can hook into the indexing pipeline.</p>
<h3>Improved Migration from SiteDefinition</h3>
<p>The migration from SiteDefinition to the Application Model has been improved. Creating in-process websites via the settings UI works again, and typed content types now show up correctly when picking the start page for an application.</p>
<p>For the full list of changes, check the official release notes.</p>2026-03-20T12:08:15.0000000ZBlog postCMS 13 Preview 3: Key changes<p>If you've been following along with the CMS 13 preview, you've likely worked through the initial upgrade path covered in my previous post. Preview 3 brings us another step closer to a production-ready release. Based on feedback on Preview 2 we have made changes so that <strong>Content Manager and Optimizely Graph are no longer enabled by default. </strong></p>
<p>It is however important to understand that: while these features are opt-in from a technical perspective, Optimizely Graph is effectively required if you want to unlock the full potential of CMS 13. <span class="fabric-background-color-mark">In practice, we expect most customers to adopt Graph as part of their CMS 13 journey, since many of the platform’s most meaningful innovations depend on it. Let’s unpack what that means.</span></p>
<h2>What's New in Preview 3?</h2>
<p>Preview 3 includes the usual improvements and bug fixes, but I wont highlight them here but instead refer to the official <a href="https://docs.developers.optimizely.com/content-management-system/v13-Pre-Release/docs/release-notes-for-cms-13-pre-release-preview-3">release notes</a>. What is worth discussing is the change in having Optimizely Graph and Content Manager enabled through opt in.</p>
<h2>Why Optimizely Graph Matters</h2>
<p>Several of CMS 13's new features are built on top of Optimizely Graph. Let´s look at some of the bigger examples:</p>
<ul class="ak-ul">
<li>
<p>Content Manager: The new editorial experience relies on Graph for content discoverability.</p>
</li>
<li>
<p>External Content: Integrating content from external sources outside of CMS requires Graph's indexing capabilities</p>
</li>
<li>
<p>Content Binding: The approach to rendering external content leverages Graph's structured queries</p>
</li>
<li>
<p><span class="fabric-background-color-mark">RAG for Opal: Graph allows Opal to “see” and “understand” your content. Allowing Opal to query all content, understand tone of voice, and more.</span></p>
</li>
</ul>
<p>In other words, if you're planning to use any of the new CMS 13 features that differentiate it from CMS 12, you need Optimizely Graph - they wont work without it. At Optimizely, we view Optimizely Graph as a <strong>mandatory</strong> and foundational component for using CMS 13 to its full potential. Running CMS 13 without Optimizely Graph will be very close to running CMS 12 compiled for .NET 10 with a smaller subset of new features. Over time, Optimizely Graph will increase in usage in CMS 13 and beyond since it is at the very center of functionality that we build.</p>
<p><span class="fabric-background-color-mark">For organizations that truly cannot adopt Graph, it’s worth carefully evaluating the value of moving to CMS 13 in the near term, since several of the headline innovations will not be available without it.</span></p>
<h2>Is Optimizely Graph required?</h2>
<p>Let's be pragmatic about this. You can run CMS 13 without Graph in some scenarios, for example:</p>
<ul class="ak-ul">
<li>
<p>You're maintaining a CMS 12 codebase with minimal changes during migration</p>
</li>
<li>
<p>You're in the early phases of migration and haven't yet enabled the new features</p>
</li>
</ul>
<p><span class="fabric-background-color-mark">One example is customers with strict on-prem or data residency requirements where introducing a cloud service is not feasible. That said, many customers who run CMS “on-prem” Today are already operating in hybrid models (self-hosted in cloud environments, partner-hosted infrastructure, etc.), and in those cases Graph is often still a viable option.</span></p>
<p>If you're upgrading to CMS 13 for its new capabilities, then its likely that you will be adopting Graph. The question probably isn't "if" but rather "when" in your migration timeline.</p>
<h2>Enabling Content Manager and Optimizely Graph</h2>
<p>Since you'll almost certainly need these features, or at least want to try them out, here's the straightforward opt-in process:</p>
<p>Step 1: Add the NuGet Packages<br />Reference the appropriate packages in your project:</p>
<pre class="language-csharp"><code>dotnet add package EPiServer.Cms.UI.ContentManager
dotnet add package Optimizely.Graph.Cms</code></pre>
<p>Step 2: Update Your Startup Configuration<br />In your Startup.cs (or wherever you're configuring services in your Alloy-based project), add the following calls to your service registration:</p>
<pre class="language-csharp"><code>public void ConfigureServices(IServiceCollection services)
{
// ... your existing service configuration
services.AddContentGraph();
services.AddContentManager();
// ... rest of your configuration
}</code></pre>
<p>Notice the order matters here: AddContentGraph() should come before AddContentManager() since Content Manager depends on Graph's infrastructure.</p>
<h2>My perspective on Graph Adoption</h2>
<p>Here's what I am thinking with this change on Opt In approach: Graph isn't a nice-to-have feature add-on—it's a corner stone for content delivery in the Optimizely ecosystem.</p>
<ul class="ak-ul">
<li>
<p>Content Manager gives editors a performant content discovery experience powered by Graph queries</p>
</li>
<li>
<p>External Content lets you unify disparate content sources through Graph's indexing</p>
</li>
<li>
<p>Content Binding enables developers to work with strongly-typed content models backed by Graph's schema</p>
</li>
</ul>
<p>These aren't isolated features; they are puzzle pieces that tell a joint story. And Graph is the connective tissue that bind them together.</p>
<p>If you're building greenfield projects or undertaking significant modernization efforts, I think that you should embrace Graph from day one. Trying to retrofit it later when you want to adopt Content Manager or External Content will be more painful than including it from the start.</p>
<h2>So, Alloy Template</h2>
<p>If you're working with the Alloy template as a learning tool or project foundation, you'll want to enable both features to get the full editorial experience. The Alloy template shows Content Manager's capabilities, and Graph powers both its search functionality and the new content delivery patterns.</p>
<p>This is actually a good learning environment to understand how Graph integrates with the platform before you build your production architecture.</p>
<p>As always, remember that Preview 3 is not production-ready. Use it for evaluation, experimentation, and preparation—but keep your production sites on CMS 12 until the official CMS 13 release.</p>
<p>Happy coding!</p>2026-02-19T13:44:31.0000000ZBlog postFrom 12 to 13 preview: A Developer's Guide to testing an Optimizely CMS 13 Alloy Site<p>The release of Optimizely CMS 13 marks a significant step forward, embracing a more composable and headless-first architecture. While this unlocks powerful new capabilities, it also introduces important changes to the underlying framework.</p>
<p>This guide provides a hands-on walkthrough for upgrading a standard CMS 12 Alloy starter site to the CMS 13 preview. We'll cover dependency updates, code migrations for obsolete APIs, and the new application configuration model.</p>
<h2>Step 1: Create a Baseline CMS 12 Site</h2>
<p>First, let's establish a starting point. Create a fresh CMS 12 Alloy site using the Optimizely templates. This ensures we have a clean, working installation before we begin the upgrade.</p>
<pre class="language-csharp"><code># Create a new Alloy project
dotnet new epi-alloy-mvc -n alloy13preview
# Build and run the site
dotnet build
dotnet run</code></pre>
<div class="fabric-editor-breakout-mark fabric-editor-block-mark css-p8f2xz">
<div class="code-block css-ggxefa"> </div>
</div>
<p>Once the site is running, register a new user account so you can log in. Verify that the site is fully functional. When you're ready, shut down the application.</p>
<h2>Step 2: Update Project Dependencies</h2>
<p>With our baseline established, the next step is to update the project file and NuGet packages.</p>
<ol class="ak-ol">
<li>
<p><strong>Update the Target Framework</strong>: Open the .csproj file and change the target framework to</p>
<div class="code-block css-ggxefa">
<pre class="language-html"><code><PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
</PropertyGroup></code></pre>
</div>
</li>
<li>
<p><strong>Update NuGet Packages</strong>: Update all EpiServer.* package versions to 13.0.0-preview2.</p>
</li>
<li>
<p><strong>Add AspNetIdentity</strong>: CMS 13 decouples the UI's identity management. Add a new package reference for EPiServer.CMS.UI.AspNetIdentity. </p>
<div class="code-block css-ggxefa">
<div class="css-9n57oc">
<pre class="language-csharp"><code><PackageReference Include="EPiServer.CMS.UI.AspNetIdentity" Version="13.0.0-preview2" /></code></pre>
</div>
</div>
</li>
</ol>
<h2>Step 3: Code Migration and Mitigating Obsolete APIs</h2>
<p>CMS 13 refactors several core APIs. The compiler will now report a series of warnings and errors related to obsolete members. Let's work through them.</p>
<blockquote>
<p><strong>A Friendly Pro-Tip:</strong> As you begin the migration, make it a habit to check the compiler warnings in your IDE or build output. These warnings are your roadmap to finding every instance of a deprecated or obsolete API in your specific project. While this guide covers the common changes for the Alloy template, your codebase may have other areas needing attention.</p>
</blockquote>
<h3>Use ContentReference and ContentLink</h3>
<p>The PageReference and PageData.PageLink types are now obsolete. This change reflects a broader shift to treat all content more generically. The fix is a straightforward replacement across your solution:</p>
<ul class="ak-ul">
<li>
<p>Replace PageReference with ContentReference.</p>
</li>
<li>
<p>Replace .PageLink with .ContentLink.</p>
</li>
</ul>
<h3>Replace SiteDefinition with the New Application Model</h3>
<p>The concept of SiteDefinition is replaced by a more flexible <strong>Application Model</strong>. An application connects a starting point in the content tree with a specific rendering mode (e.g., "In-Process" or "Headless") and hostnames.</p>
<p>To resolve this, you'll need to inject IApplicationResolver into your controllers and services to get the context of the current application (IApplication).</p>
<p>Here is an example of how to refactor the StartPageController:</p>
<div class="fabric-editor-breakout-mark fabric-editor-block-mark css-p8f2xz">
<div class="code-block css-ggxefa">
<pre class="language-csharp"><code>using alloy13preview.Models.Pages;
using alloy13preview.Models.ViewModels;
using EPiServer.Web;
using EPiServer.Web.Mvc;
using Microsoft.AspNetCore.Mvc;
using EPiServer.Applications;
using EPiServer.Shell.Security;
using EPiServer.Web.Routing;
namespace alloy13preview.Controllers;
public class StartPageController : PageControllerBase<StartPage>
{
private readonly IApplicationResolver _applicationResolver;
public StartPageController(IApplicationResolver applicationResolver)
{
_applicationResolver = applicationResolver;
}
public async Task<IActionResult> Index(StartPage currentPage, CancellationToken cancellationToken)
{
var model = PageViewModel.Create(currentPage);
var application = await _applicationResolver.GetByContextAsync(cancellationToken);
var website = application as Website;
if (website is not null && website.RoutingEntryPoint.CompareToIgnoreWorkID(currentPage.ContentLink))
{
// Connect the view models logotype property to the start page's to make it editable
var editHints = ViewData.GetEditHints<PageViewModel<StartPage>, StartPage>();
editHints.AddConnection(m => m.Layout.Logotype, p => p.SiteLogotype);
editHints.AddConnection(m => m.Layout.ProductPages, p => p.ProductPageLinks);
editHints.AddConnection(m => m.Layout.CompanyInformationPages, p => p.CompanyInformationPageLinks);
editHints.AddConnection(m => m.Layout.NewsPages, p => p.NewsPageLinks);
editHints.AddConnection(m => m.Layout.CustomerZonePages, p => p.CustomerZonePageLinks);
}
return View(model);
}
}
</code></pre>
</div>
</div>
<p>You will need to apply a similar pattern to other places in the code that reference SiteDefinition.Current. For SiteDefinition.Current.RootPage, you can replace it with ContentReference.RootPage.</p>
<h3>Modernize Dependency Injection</h3>
<p>Service location using InitializationEngined.Locate is obsolete. Instead, use constructor injection to get an IServiceProvider instance.</p>
<ul class="ak-ul">
<li>
<p><strong>Before</strong>: context.Locate.Advanced.GetInstance<T>()</p>
</li>
<li>
<p><strong>After</strong>: Inject IServiceProvider and call serviceProvider.GetRequiredService<T>() In an IInitializationModule, you can access it via context.Services.</p>
</li>
</ul>
<h3>Other Small API Changes</h3>
<ul class="ak-ul">
<li>IContentTypeRepository<T>: The generic argument is no longer needed. Change IContentTypeRepository<PageType>() to IContentTypeRepository()</li>
<li>
<p>PageController.PageContext.Page This property is now of type IContent. Update your code to reflect this change.</p>
</li>
</ul>
<h2>Step 4: Configuration Updates</h2>
<p>Next, we need to make a few adjustments in Startup.cs and appSetting.json</p>
<ol class="ak-ol">
<li>
<p><strong>Enable Database Compatibility Update</strong>: In Startup.cs, add the following to allow the database compatibility level to be updated automatically.</p>
<div class="code-block css-ggxefa">
<pre class="language-csharp"><code>services.Configure<DataAccessOptions>(options =>
{
options.UpdateDatabaseCompatibilityLevel = true;
});</code></pre>
</div>
</li>
<li>
<p><strong>Configure Content Graph</strong>: Content Graph is enabled by default in the preview of CMS 13 and cant be disabled. This will likely change in subsequent releases. You must add your credentials to appSettings.json.</p>
<div class="code-block css-ggxefa">
<pre class="language-javascript"><code>"Optimizely": {
"ContentGraph": {
"GatewayAddress": "https://staging.cg.optimizely.com",
"AllowSendingLog": "true",
"SingleKey": "INSERT SINGLEKEY HERE",
"AppKey": "INSERT APPKEY HERE",
"Secret": "INSERT SECRET HERE"
}
}</code></pre>
</div>
</li>
<li>
<p><strong>Install Visitor Groups</strong>: Due to a known issue in the preview, the menu system will not render correctly unless Visitor Groups are installed. Add this to Startup.cs</p>
<div class="code-block css-ggxefa">
<div class="css-9n57oc">
<div class="css-4osl21">
<div>
<pre class="language-csharp"><code>services.AddVisitorGroups();</code></pre>
</div>
</div>
</div>
</div>
</li>
</ol>
<h2>Step 5: Fixing the Post-Upgrade 404</h2>
<p>After making all the changes, run the application:</p>
<div class="fabric-editor-breakout-mark fabric-editor-block-mark css-p8f2xz">
<div class="code-block css-ggxefa">
<pre class="language-csharp"><code>dotnet run</code></pre>
</div>
</div>
<p>You will notice the site returns a <strong>404 Not Found</strong> error. This is expected. The migrated database still has the old SiteDefinition configuration, which doesn't align with the new Application Model.</p>
<p>Follow these steps to fix it:</p>
<ol class="ak-ol">
<li>
<p>Navigate to the CMS admin interface: <code class="_ca0qyh40 _u5f3m5ip _n3tdyh40 _19bvm5ip _2rkofajl _11c819w5 _1reo1wug _18m91wug _1dqoglyw _1e0c1nu9 _bfhk187e _16d9qvcn _syazi7uo _vwz41kw7 _1i4q1hna _o5721jtm">https://localhost:5000/Optimizely/CMS</code>.</p>
</li>
<li>
<p>Go to <strong>Settings</strong> > <strong>Applications</strong>. If the page fails to render, clear your browser cache and reload. You will see a default "Headless" application.</p>
</li>
<li>
<p>Edit the application and click <strong>Delete Application</strong>.</p>
</li>
<li>
<p>Click <strong>Create New Application</strong>.</p>
<ul class="ak-ul">
<li>
<p>Set the <strong>Type</strong> to <strong>In Process</strong>.</p>
</li>
<li>
<p>Select your original Alloy start page as the <strong>Application start page</strong>.</p>
</li>
<li>
<p>Give it a name.</p>
</li>
</ul>
</li>
<li>
<p>Edit the new "In Process" application you just created.</p>
<ul class="ak-ul">
<li>
<p>In the <strong>Hosts</strong> section, add a new host with the name localhost:5000 and set it as the default.</p>
</li>
</ul>
</li>
</ol>
<p>Your Alloy site should now render correctly on the frontend, and preview in Edit mode will be functional.</p>
<h2>Conclusion</h2>
<p>Congratulations! You have successfully upgraded your Alloy site to CMS 13. This process highlights the key architectural shifts in the new version, particularly the move to a composable Application Model and modernized APIs. You are now ready to explore the new features and possibilities of Optimizely CMS 13.</p>
<p><strong>Important Note</strong>: The steps outlined in this guide are intended for developers to explore the CMS 13 preview with the Alloy template. This is an incomplete preview, and these instructions are not recommended for use with an actual development project and certainly not a live production site. We will share more as we get closer to the release date of CMS 13.</p>2026-01-23T14:21:45.0000000ZBlog postCMP DAM asset sync to Optimizely Graph self service<p>The CMP DAM integration in CMS introduced support for querying Optimizly Graph (EPiServer.Cms.WelcomeIntegration.Graph 2.0.0) for metadata such as alternative texts. Up until now interaction with Optimizely has been needed when adding this integration from CMP to Optmizely Graph but that is no longer the case. CMP now contains a self service feature where Optimizely Graph can be added and initial synchronization of assets started. This makes it easier to get started and reap the performance benefits of moving from REST API integration with CMP to the more performant Optimizely Graph integration.</p>
<p>In CMP simply header over to <strong>Settings \ Organization \ Misc</strong>, scroll to the bottom of the view and hit the <strong>Enable & Sync</strong> button that you will find there. Once the sync has completed you will find a URL to the Optimizely Graph UI which contains the <strong>SingleKey</strong> needed to configure CMS.</p>
<p><img src="/link/ff2c84cbf623455ba306902f5ed5b262.aspx?1739443330051" alt="Enabling and syncing DAM assets to Optimizely Graph" width="195" height="94" /></p>
<p>The URL will look something like below.</p>
<p><a title="Optimizely Graph UI with single key" href="https://cg.optimizely.com/app/graphiql?auth=SINGLE_KEY">https://cg.optimizely.com/app/graphiql?auth=SINGLE_KEY</a></p>
<p>If you havent already read about our integration with CMP, either with REST API, or with Optimizely Graph, then please head over to <a href="https://docs.developers.optimizely.com/platform-optimizely/docs/cmp-dam-cms">CMP DAM in CMS</a> to find details on how to get started.</p>2025-02-13T10:48:51.0000000ZBlog postDAM integration new major version, performance improvements and Library Picker folder selection<p>As you might already have seen we have decided to delist the EPiServer.CMS.WelcomeIntegration version 1.4.0 where we introduced Graph support. Unfortunately a return type was changed that we didn’t catch which means that it became a breaking change. We have decided to delist 1.4.0 and release the performance improvements we have been working on as a new major. We apologize for any inconvenience this has caused and suggest that you either downgrade to 1.3.9 and rely on the CMP API instead of Graph, or upgrade to 2.0.0 instead. We recommend to upgrade to 2.0.0 for the best performance.</p>
<h2><strong>Performance</strong></h2>
<p>The integration between CMS and CMP uses a combination of the CMP Library Picker, in which the editor selects the asset to reference and, either the CMP´s REST API, or indexed assets in Graph. The API or Graph is used to pull metadata regarding the assets such as sizing or alt texts. The integration with REST API has been around for quite some time and the Graph integration was released in the previous version, 1.4.0, and we described how to configure it in <a href="/link/652f47770cce478882e5e0481d69b6c8.aspx">this blog post by Bartosz Sekula</a>.</p>
<p>We are now releasing a change in how metadata is cached in the CMS for assets referenced from CMP DAM. Moving forward from version 2.0.0 the cache will move to the database and stored permanently. This removes the need for any page request that contain CMP DAM assets to perform outbound network requests to retrieve that metadata when cache has expired.</p>
<p>The metadata will be fetched for Image assets from CMP when a content that contains references to those images is <strong>published</strong>. So metadata will be available once the page starts to receive traffic. Please note that fetching the metadata is handled in the background to not block the editor from interacting with the UI. If the images are already referenced by other pages or block then the already existing metadata will be used.</p>
<p>Should for some reason the metadata not have been populated then the image will still render but with the public URL which was stored the first time the asset was referenced, instead of the latest URL provided by CMP through the metadata.</p>
<p><strong>Renditions</strong> of <strong>Images</strong> is a bit different and a topic to which we will return. Currently the renditions for an image asset will render without alt-text. As already stated, we are working on resolving that. The HtmlHelper and TagHelper as well as DamImageAssetViewComponent will still render the correct rendition.</p>
<p>Example of using HtmlHelper</p>
<pre class="language-markup"><code>@model PageViewModel<StandardPage>
@using EPiServer.Cms.WelcomeIntegration.UI.Helpers
@await Html.RenderTagWithMetadata(p => p.CurrentPage.Image)</code></pre>
<p>Example of using TagHelper</p>
<pre class="language-markup"><code>@model PageViewModel<StandardPage>
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
<dam-asset content-reference="@Model.CurrentPage.Image" /></code></pre>
<h3>Maintaining asset metadata</h3>
<p>Since the metadata for Images now have moved to the database, how does it get updated? A new scheduled job has been created which will, on schedule, pull metadata from CMP DAM for all assets and update in CMS. This job can be executed manually should the need arise to sync metadata between CMP and CMS.</p>
<p><img src="/link/7771fed1d3e54efbb6c8f8b4142cecc8.aspx?1732854990499" alt="The scheduled job for maintaining CMP DAM asset metadata in CMS" width="834" height="471" /></p>
<p>Metrics from testing scenarios indicate big performance improvements when serving content with DAM assets to visitors.</p>
<h2><strong>Asset Library folder selection</strong></h2>
<p>CMP has the possibility to organize content in folder structures and it is now possible configure either globally or by type which folder to open in the <strong>CMP Library Picker</strong>. Configuration is done at startup or appSettings as usual.</p>
<pre class="language-csharp"><code>.AddDAMUi(o => {
o.Enabled = true;
o.GlobalRootFolderGuid = "a7fd6357c13d49829715f38fe8114c40";
o.RootFolderForTypes = new Dictionary<string, IEnumerable<Type>>
{
{ "57523add60d04e328d7fc1e02c05ed40", new Type[] { typeof(DAMImageAsset) } },
{ "7bce1de28e66411590ac32896eff2ce1", new Type[] { typeof(DAMVideoAsset) } },
{ "72b89ab1b83041acaab861a035db7e7b", new Type[] { typeof(DAMAsset) } }
};
});</code></pre>2024-11-29T04:37:35.0000000ZBlog postEPiServer.CMS UI 12.17.0 delisted from Nuget feed<p style="margin: 0in; font-family: Calibri; font-size: 11.0pt;" lang="sv">The 12.17.0 version of the UI packages have been delisted from our Nuget feed and is no longer available. We are working on providing a patch, 12.17.1 to correct an issue that affects string properties that use <span class="classLib">SelectMany</span> attribute and a <span class="classLib">ISelectionFactory</span> to handle the available options.</p>
<p style="margin: 0in; font-family: Calibri; font-size: 11.0pt;" lang="sv"> </p>
<p style="margin: 0in; font-family: Calibri; font-size: 11.0pt;" lang="sv">The root issue is that the representation of the selected values is now stored in a different way in the database and that needs to be considered a breaking change. We moved from a comma separated list in favor of a Json array. I.e. from "value1,value2,value3" to "[\"value1\",\"value2\",\"value3\"] in an effort to try and broaden the capabilities. The change only applies to properties that have been updated and saved to the database since the 12.17.0 upgrade was done on the installation.</p>
<p style="margin: 0in; font-family: Calibri; font-size: 11.0pt;" lang="sv"> </p>
<p style="margin: 0in; font-family: Calibri; font-size: 11.0pt;" lang="sv">An installation can be checked if it has been affected by the issue, by running a query against the database to see if the properties store a JSON array or comma separated strings. Please note that only installations using 12.17.0 and that uses properties that are using SelectMany attribute is potentially affected.</p>
<p style="margin: 0in; font-family: Calibri; font-size: 11.0pt;" lang="sv">An example would be that 12.17.0 would store</p>
<p style="margin: 0in; font-family: Calibri; font-size: 11pt; padding-left: 40px;" lang="sv"><span class="classLib">["1","2","3"]</span></p>
<p style="margin: 0in; font-family: Calibri; font-size: 11.0pt;" lang="sv"> </p>
<p style="margin: 0in; font-family: Calibri; font-size: 11.0pt;" lang="sv">Instead of the previously used</p>
<p style="margin: 0in; font-family: Calibri; font-size: 11pt; padding-left: 40px;" lang="sv"><span class="classLib">1,2,3</span></p>
<p style="margin: 0in; font-family: Calibri; font-size: 11.0pt;" lang="sv"> </p>
<ul>
<li style="font-family: Calibri; font-size: 11pt;" lang="sv"><a href="/epiui/CMS/Content/support/Bug-list,,149001/bug/CMS-26903?epieditmode=False&epsremainingpath=bug/CMS-26903" title="CMS-26903">CMS-26903</a><br />When addressing the issue <a href="/epiui/CMS/Content/support/Bug-list,,149001/bug/CMS-23405?epieditmode=False&epsremainingpath=bug/CMS-23405" title="CMS-23405">CMS-23405</a> <span lang="sv" style="font-family: Calibri; font-size: 11.0pt;">a breaking change was introduced in how the values for string properties using </span><span lang="en-SE" style="font-weight: bold; font-family: -apple-system; font-size: 10.5pt; color: #272b32; background: white;">SelectManyAttribute</span><span lang="sv" style="font-family: Calibri; font-size: 11.0pt;"> and </span><span lang="en-SE" style="font-weight: bold; font-family: -apple-system; font-size: 10.5pt; color: #272b32; background: white;">ISelectionFactory</span><span lang="sv" style="font-family: Calibri; font-size: 11.0pt;"> are stored in the database. A change was made to serialize the selected options as JSON instead of comma separated strings.</span></li>
</ul>
<p style="margin: 0in; font-family: Calibri; font-size: 11.0pt;" lang="sv">We offer our apologies that this occured and we are sorry that this has affected our customers. For installations that are in the process of migrating to 12.17.0 we ask that you verify if you are affected. Wait for the 12.17.1 version that will arrive shortly and then verify that data is stored correctly.</p>
<p style="margin: 0in; font-family: Calibri; font-size: 11.0pt;" lang="sv">This blog post will be updated as we move forward with this issue. Thank you for your patience.</p>2023-03-01T05:30:45.0000000ZBlog postImproving And Unifying The UI<p><span>We aim to unify and make a seamless user experience across all Optimizely products. This change will make our products more predictable, easy to use, and accessible. T</span>herefor the CMS in Content Cloud has, over the last few versions (starting with 12.3.0), received multiple updates to the UI. This work is still ongoing, and in the coming weeks/months we expect to release even more updates. However, we wanted to pause and talk a bit about what we have done recently.</p>
<p>Let’s start with a direct comparison of how the UI has changed during this period. The screenshots below clearly outline the differences.</p>
<p><img src="/link/e22dea18564b4579a02de912701e2f89.aspx" width="2844" alt="A comparison of form edit between 12.7.0 (left) and 12.2.0 (right)." style="border-style: solid;" /></p>
<p><span style="font-family: helvetica, arial, sans-serif;"><em>Image: A comparison of form edit between 12.7.0 (left) and 12.2.0 (right).</em></span></p>
<p>The UI now uses icons from Font Awesome Pro 6, which is a font-based icon library which in turn means that there are fewer resources to download and the icons scale better since they are vector-based. Icons are no longer solid instead, they are outlined, more sharp, crisp, and modern looking. All products from Optimizely use the same set of icons.</p>
<p>The new icons use the same CSS classes as the old ones did, so for example the home icon still uses the .epi-iconObjectStart CSS class. However, the new icons use a licensed version of Font Awesome 6 Pro, and this limits how the icons can be used. Third-party add-ons and extensions need to use either a free version of Font Awesome 6/equivalent or purchase their license. The new icons have the following sizes, small (16 x 20), medium (24 x 30), and large (32 x 40). </p>
<p>Spacing has also been reworked to introduce more padding to create an improved visual clarity, balancing the layout and making it easier to overview. By introducing more white space into the layout important elements draw the user’s attention, allowing the user to focus on call-to-action items and making everything easier to read. In general, alignment has been given an overhaul as well.</p>
<p>Primary buttons have moved to the right-most side in a button group and the secondary button no longer has a border unless it receives focus or the user hovers on it. This further makes the primary button easier for the eye to catch.</p>
<p><img src="/link/6f5baee0cc0c464799cea3b323ff351f.aspx" width="800" alt="Button placement and disabled state in 12.7.0 (left) and 12.2.0 (right)" height="808" style="border-style: solid;" /></p>
<p><span style="font-family: helvetica, arial, sans-serif;"><em>Image: Button placement and disabled state in 12.7.0 (left) and 12.2.0 (right)</em></span></p>
<p><span>Disabled buttons are not transparent anymore. Instead, they have a specific look to them to make sure that they stand out as inactive. For example, a disabled primary button was previously a muted blue that became brighter when enabled. Now the disabled version is instead grey and becomes blue once enabled.</span></p>
<p>Content Selectors have been reworked to support the user in selecting content without using drag and drop. This was made possible by allowing all content selectors to have a drop-down menu that allows the user to select as well as create content. Drag-n-drop is still present in the UI and the borders of drop zones have been adjusted so that they are coherent and visible.</p>
<p><img src="/link/b7383116577b428e9e0db0cded611f6c.aspx" width="1024" alt="Creating and selecting content in 12.7.0 (left) and 12.2.0 (right)" height="254" style="border-style: solid;" /></p>
<p><span style="font-family: helvetica, arial, sans-serif;"><em>Image: Creating and selecting content in 12.7.0 (left) and 12.2.0 (right).</em></span></p>
<h2><span style="font-family: helvetica, arial, sans-serif;">Multi-targeting .NET 6 and .NET 5</span></h2>
<p>As of EPiServer.CMS.UI 12.4.0 our nugets multi-target both .NET 6.0 and .NET 5.0. EPiServer.CMS.TinyMCE 3.2.0 also supports both as well as EPiServer.Telemetry.UI 2.1.0.</p>
<p>This was a small selection of the many updates that have been made in the UI and as you upgrade you will discover many more. In the coming versions the team will work on more updates, and we are looking forward to your feedback.</p>
<h2><b>New support for tiff files</b></h2>
<p>The CMS UI supports tiff files and adds Tiff to <span class="classLib">SupportedEditExtensions</span> list. Currently, tiff is quite an old image extension and It is supported by a few browsers (for example, safari, IE11).</p>
<h3>What is in the box?</h3>
<ul>
<li>On Chrome/other browsers users can:
<ul>
<li>Upload a .tiff image</li>
<li>Open in Image Editor to edit a .tiff image</li>
</ul>
</li>
<li>On Safari/IE11 browser users can:
<ul>
<li>Upload a .tiff image</li>
<li>DnD a .tiff image into Image property (content reference/content reference list/link item collection/URL to (doc,image, page), XhtmlString, Content Area)</li>
<li>Open a .tiff image on OPE or All properties mode</li>
<li>Open in Image Editor to edit a .tiff image</li>
<li>View a .tiff image on View mode</li>
</ul>
</li>
</ul>
<h3>Known issues</h3>
<ul>
<li>Thumbnails in Media gadget have a hard-coded content-type (image/png) in CMS Core, and they are not going to change it. That explains why tiff or ico files don't show thumbnails.</li>
<li>We only support *.tiff extension. *.tif is not supported</li>
</ul>2022-06-16T14:17:55.0000000ZBlog post