Optimizely CMS 13 DAM Migration: Prevent Broken Assets
Optimizely CMS 13.3 now includes a scheduled job to convert legacy Digital Asset Management references from CMS 12 into the Graph-backed format used by CMS 13. This matters because an application can complete its code upgrade and still show broken or empty images, videos and files in the editor or on the live website when old references remain.
Optimizely published the dedicated migration procedure on 6 October 2026. It is timely for organisations moving to CMS 13 because DAM is no longer only a picker or media-library concern: it sits inside the content delivery path, editorial workflow and governance model. A failed or incomplete conversion can affect campaign pages, product content, downloads, rich text, translations, historical versions and content restored from trash.
This guide is for Australian business owners, marketing and digital managers, CMS owners, developers and technology decision-makers planning or reviewing an Optimizely CMS 12-to-13 upgrade. It focuses on the operational evidence needed to migrate safely—not only the command that starts the job.
Why this Optimizely migration is trending now
CMS 13 changes how Optimizely DAM assets reach the website. CMS 12 content can still contain references to the older DAM content provider, while CMS 13 delivers DAM assets through External Sources indexed in Optimizely Graph. Optimizely's new CMS 13.3 migration job bridges those models.
The business issue is immediate rather than theoretical. Without conversion, editors may see empty asset fields and customers may encounter missing campaign imagery, documents or video. The affected reference may be buried in a nested block, a rich-text field, an older language version or an unpublished draft, so checking a few visible pages is not enough.
The release also removes a common upgrade ambiguity. Teams now have a supported migration mechanism and a published set of prerequisites, but they still need to decide when to run it, how to prove coverage, what recovery point to preserve and who signs off before production.
Broken assets are more than a visual defect
Map the customer, editorial and operational consequences before treating the work as a background data task.
Customer journeys
Missing product media, campaign images, videos or downloads can weaken conversion, trust and accessibility.
Editorial workflow
Empty asset fields can block preview, approval, localisation and scheduled campaign work.
Search and delivery
Graph-backed frontends and APIs need references that resolve to the expected asset types, URLs and renditions.
Historic content
Old versions, drafts and trash matter because teams may compare, republish or restore them later.
Governance
Asset tracking, ownership and usage evidence depend on the new DAM relationship being complete.
Recovery
In-place updates and cleanup make a tested backup and restoration plan part of the release, not an optional extra.
Move references only after Graph is ready
First confirm whether the site is affected
The migration is relevant when a CMS 12 implementation used the Optimizely DAM integration and stored DAM references in content that is moving to CMS 13. Do not assume every media item is affected. Locally uploaded CMS media and external assets can follow different paths.
Build an inventory before changing anything:
- the CMS 12 and target CMS 13 versions, environments and deployment owners;
- the DAM or CMP instance, asset types and Graph instance connected to the target;
- content properties that can contain DAM references, including rich text and nested blocks;
- languages, sites, brands, applications and content branches in scope;
- frontends and APIs that render the assets, including headless and server-rendered paths;
- scheduled jobs, exports, feeds, search indexes and mobile applications that consume asset data;
- the number of references and content versions expected before migration.
Include content outside the obvious page tree. Optimizely says the job processes published items, drafts, old versions, all languages and trash. That breadth protects future restores and republication, but it also means the test dataset and run-time estimate need to represent the full repository.
Meet every prerequisite before the first run
Optimizely's checklist is deliberately strict. The target must run CMS 13.3 or later, DAM features must be activated, and assets must have finished synchronising from CMP into Optimizely Graph. The required Graph content sources for images, videos and files should exist, CMP credentials should be configured, the DAM tracking job should complete without errors, and a full database backup should be available.
| Gate | Evidence to keep | Why it matters |
|---|---|---|
| CMS package baseline | Deployed version and package lock or bill of materials | The migration capability is tied to CMS 13.3 or later. |
| DAM activation | Configured instance and enabled asset types | The editor and asset tracking need the intended DAM connection. |
| Graph readiness | Completed sync, available content sources and sample resolved assets | Converted references are useful only if the new source can resolve them. |
| CMP access | Credential test and least-privilege owner | Reference conversion can continue without credentials, but cleanup will be skipped. |
| Tracking health | Successful DAM Tracking Assets job result | It proves the CMS can communicate with CMP before the one-off job starts. |
| Recovery point | Backup identifier, completion time and restore procedure | The job updates versions in place and cannot be undone from the admin UI. |
Treat these as release gates. A green application build does not prove that Graph contains the right assets or that the editorial experience can use them.
Rehearse with production-shaped content
Optimizely recommends staging and regression testing for CMS 13 breaking changes. For DAM migration, a thin developer database is especially risky because it may not contain the old versions, translations, rich text, deep block structures and deleted content that expose edge cases.
- Create a current recovery point. Export or copy the database using the process appropriate to the hosting model, and record how it will be restored. Optimizely notes that DXP database export and import can take hours and, in extreme cases, days, so lead time belongs in the release schedule.
- Use representative content. Include high-value pages, complex ContentAreas, rich text, local blocks, block lists, documents, videos, renditions, multiple languages, drafts and trash.
- Capture the baseline. Record reference counts, representative page screenshots, Graph responses, asset identifiers, broken-reference totals and tracking-job results.
- Run the same build and configuration. The rehearsal should use the CMS packages, Graph connection, DAM activation, credentials and frontend code planned for production.
- Measure duration and load. The migration scans content versions. Record time, resource use, log volume and any effect on editors or background jobs.
The goal is a repeatable runbook with expected counts and decision points. If the rehearsal result cannot be explained, production is not ready.
Run the CMS 13.3 migration as a controlled release
The technical mechanism is straightforward: add the EPiServer.Cms.DamMigration package at an appropriate CMS 13.3-or-later version, register the DAM migration services, configure the CMP client, enable Optimizely:Cms:DamMigration:Enabled, and deploy the tested build.
Then use CMS Admin > Scheduled Jobs:
- run Optimizely DAM Tracking Assets and confirm it completes without errors;
- open Optimizely DAM Legacy Asset Migration;
- start the job inside the approved change window;
- monitor job history and application logs until it completes or stops;
- record the counts of resolved DAM assets, patched CMS versions, cleanup results and failures.
Do not paste secrets into tickets, chat or screenshots. Store CMP credentials through the normal deployment secret mechanism, separate them by environment and limit access to the people and services that need it.
The job updates the legacy reference, walks content and then removes old tracking and mapping records. Those are different outcomes. A message that references were converted but cleanup was skipped should be recorded as partial completion, with an owner and next step.
Verify the migration at four levels
A successful scheduled-job message is necessary, but it is not sufficient. Test the stored data, the editorial interface, the delivery layer and the customer experience.
| Level | Minimum checks | Evidence |
|---|---|---|
| Reference data | Expected totals migrated; failures explained; drafts, versions, languages and trash included | Job history, logs and before-versus-after counts |
| Editorial experience | Existing assets display; picker opens; replacements save; preview works; usage is visible | Role-based acceptance results and representative screenshots |
| Graph and frontend | Asset types resolve; URLs and renditions load; alt text and metadata are correct; caches refresh | Graph query assertions, HTTP checks and page tests |
| Business journeys | Campaign pages, product content, downloads, video, search, forms and localisation remain usable | End-to-end test results signed by content and business owners |
Choose test cases by risk, not convenience. Prioritise revenue pages, current campaigns, regulated documents, customer downloads, high-traffic templates and content with complex nesting. Include a restore-from-trash test in the rehearsal environment because the job intentionally migrates trash to prevent restored content from pointing at deleted legacy mappings.
Handle stopped runs and partial cleanup deliberately
Optimizely says the migration can be run more than once. References already converted are skipped, and work completed before a stop is retained. That makes the job resumable, but not consequence-free.
When a run stops, preserve the job message and logs before restarting. Separate failures into at least four groups:
- Unresolved reference: the legacy identity could not be mapped to a Graph-backed asset.
- Content update failure: the reference was identified but a content version could not be patched.
- Cleanup skipped: reference changes remain, but old CMP tracking or mapping records were not removed.
- Delivery defect: data migrated, but the editor, Graph query or frontend still cannot render the expected asset.
Optimizely identifies missing CMP credentials, external content-provider items, authentication errors and excessive rate-limit errors as cleanup stop conditions. Do not label the entire migration complete because visible production pages look correct. Reconcile every failure or document why the remaining record must stay.
Be precise about rollback
The CMS 13.3 job updates content versions in place and Optimizely says it cannot be undone from the admin interface. A rollback therefore needs more than redeploying the previous application package.
Define the recovery decision before production:
- what failure rate or customer impact triggers a stop;
- whether a resumable fix is safer than restoring the database;
- which application, database, Graph, cache and integration states must be aligned after recovery;
- how new editorial changes made during the window will be preserved or replayed;
- who can authorise restore, how long restore takes and what customer communication is required.
Optimizely's DXP documentation describes database export to a bacpac, but teams should validate the recovery mechanism for their own hosting arrangement and environment. A backup identifier is not proof of recovery. Record a tested restore procedure, responsible people, credentials, timing and post-restore validation.
Turn the migration guide into an owned release
A short plan gives content, development and operations teams time to prove readiness before production.
Week 1: inventory
Map DAM references, content shapes, languages, applications, Graph sources, owners and business-critical pages.
Week 1: prepare
Confirm CMS 13.3+, DAM activation, CMP credentials, tracking health, Graph synchronisation and recovery access.
Week 2: rehearse
Run against production-shaped content, measure duration and reconcile every migration and cleanup result.
Week 2: test
Validate editor, Graph, frontend, metadata, renditions, localisation, versions, trash and critical customer journeys.
Week 3: cut over
Use an approved window, named decision owner, monitored job and clear stop or restore thresholds.
Week 4: close
Disable the one-off job, retain tracking, review alerts, archive evidence and assign unresolved follow-up work.
Close the migration without weakening ongoing governance
After the result is accepted, Optimizely instructs teams to set Optimizely:Cms:DamMigration:Enabled back to false. This hides the one-off job so it is not started accidentally. Keep DAM tracking enabled so the recurring tracking job can continue reporting which assets are used.
Also add permanent checks:
- alert on failed DAM tracking and Graph synchronisation jobs;
- monitor broken asset responses and missing rendition URLs from outside the CMS;
- include asset-field, rich-text and locale regression cases in future CMS releases;
- record the Graph content sources and DAM instance as managed dependencies;
- review access to CMP credentials and rotate them under the organisation's secret policy;
- retain migration counts, approvals and test evidence with the upgrade record.
CMS upgrades are not complete when the application starts. They are complete when editors can work, customers receive the intended experience, operational signals are healthy and the team can explain how the result was verified.
Questions to ask your Optimizely partner
- Which CMS 12 content properties and applications contain legacy DAM references?
- Can you show that every required asset type has finished synchronising into the intended Graph instance?
- What before-and-after counts will prove that drafts, versions, languages, rich text, blocks and trash were covered?
- Has the migration been rehearsed against production-shaped data using the production package versions and configuration?
- How long did the rehearsal take, and what load or editor impact was observed?
- Which failures are safe to retry, and which require a database restore?
- How will editorial changes made during the migration window be handled if recovery is required?
- Which Graph queries, frontends and business journeys are included in acceptance testing?
- Who signs off the editor experience, customer experience, cleanup result and ongoing monitoring?
- What will be disabled, retained and monitored after the one-off job is complete?
A strong answer includes an inventory, baseline counts, job evidence, test results and named owners. A generic statement that the migration job completed is not enough for a business-critical website.
Sources checked
- Optimizely Developer Community: Migrate Optimizely DAM Assets from CMS 12 to CMS 13
- Optimizely: Configure the DAM asset picker for CMS 13
- Optimizely: CMS 13 overview
- Optimizely: Breaking changes in CMS 13
- Optimizely: Integrate external content sources with CMS
- Optimizely: Export and import database
- Optimizely: Scheduled synchronization
Sources were accessed on 8 October 2026. Confirm the exact package version, hosting process and current Optimizely documentation for your implementation before running the migration.