Migrate from CMS 12 to CMS 13 with Optimizely Graph

CMS 13 introduces a breaking Optimizely Graph schema change. A CMS 12 site and a CMS 13 site cannot share the same Graph instance without migrating the schema, so upgrading Optimizely Graph is part of the CMS 13 upgrade.

Upgrade in place using DXP deployment slots. Handle Optimizely Graph during the upgrade in one of two ways:

If you have not implemented Optimizely Graph in your CMS 12 project, follow the standard DXP upgrade. Deploy to Integration, then Preproduction, and then Production. Graph provisioning is not part of your upgrade, and none of the Graph steps in this article apply.

For related information, see the following:

A deployment slot is a temporary cloned website that DXP creates during a deployment. DXP mirrors your production configuration, deploys your code to the slot, warms it up, and swaps the slot into production if validation succeeds.

Deployment slots provide the following capabilities:

Use this path if you already use Optimizely Graph on CMS 12 and want to avoid Graph downtime. This path is opt-in. If you prefer, run a smooth rebuildsmooth rebuild on your existing instance instead.

In DXP Management Portal, open the Optimizely Graph Service Configurations panel on the API tab. While Graph Service is enabled, click Prepare for CMS 13. The portal does the following:

In the previous screenshot, Prepare for CMS 13 displays next to Disable Graph Service. The table lists your current CMS 12 Graph configuration for each environment, including gateway address, app key, secret, and single key. These credentials stay in use until you deploy CMS 13.

The Content Graph keys panel shows a status badge for each environment as the migration progresses:

New CMS 13 keys are tagged Live when they take effect for an environment. The old CMS 12 keys are tagged About to be decommissioned when key rotation is scheduled.

When migration is underway, the panel shows two tables: the existing configuration and a New CMS 13 Configurations table. Each environment migrates independently.

In this example, Integration migrated to CMS 13 and its old CMS 12 keys are rotated. In the existing configuration table, its row shows CMS 13 migration: Keys Rotated On Old Instance, with a note that the CMS 12 keys are about to be decommissioned. In the New CMS 13 Configurations table, its new key is tagged Live. Preproduction and Production have new CMS 13 instances prepared but are not yet live, so they appear in both tables: their CMS 12 keys in the existing table and their new keys in the new table.

Migrate one environment at a time, starting with the lowest. Deploy to Integration, then Preproduction, and then Production, and validate each environment before you move up so that issues surface in a lower environment before Production.

This zero-downtime flow removes the Graph schema reason for a maintenance page, because the new instance already has the CMS 13 schema and the schema migration (smooth rebuild) is not part of the swap. You may still need a maintenance page, or zero-downtime read-only or read-write mode, for the CMS 13 release itself, depending on the changes it contains, such as breaking database or content-type changes.

If your project has linked front-end hosting environments, deploy each one so that it picks up the new Graph credentials.

If your project integrates Digital Asset Management (DAM), part of Optimizely Content Marketing Platform (CMP), with Optimizely Graph, DAM does not yet work with the CMS 13 Optimizely Graph instance. Support for DAM on CMS 13 is planned for a later release. If you depend on DAM, factor this into your migration timing, and contact Optimizely Support for guidance.

After CMS 13 is live, the old CMS 12 Graph instance is retired in two stages, so that any remaining consumers of the old Graph keys have time to switch over.

Stage 1 – Key rotation (soft delete) runs when both of the following are true:

Key rotation disables the old instance keys, so any service still on the old credentials starts to fail visibly. This surfaces stale configuration before the instance is removed.

Stage 2 – Hard delete removes the old Graph instance after a further grace period (default 30 days) following Stage 1.

If you do not provision a new instance, migrate the schema on your existing Graph instance. This path requires downtime. The CMS 13 schema change is breaking, so the site must be offline behind a static maintenance page during the rebuild. You cannot use zero-downtime read-only or read-write mode for this path.

Consider this path if your site is not yet live, or if some downtime behind a maintenance page is acceptable. It keeps your existing Graph instance and credentials, so external consumers of Optimizely Graph do not need updating. This can make it simpler than provisioning a new instance.

Run this path in Integration and Preproduction first. This lets you measure how long the rebuild takes so that you can size the maintenance window before you run it in Production.

For the full deployment-slot process, including packaging, slot creation, warmup, and swap, go to Deploying (DXP)Deploying (DXP). The following steps cover the zero-downtime options relevant to the CMS 13 Graph migration.

For headless implementations, deploy each linked front-end environment as part of the upgrade. The portal applies the new Graph credentials automatically when you do. For details, go to Frontend (headless) environments.