Project migration for CMS 12 with Optimizely Graph

Migrate your CMS 12 project with Optimizely Graph to CMS 13 while preserving Graph functionality and minimizing downtime. Choose one of two migration options based on your tolerance for downtime and your deployment environment.

📘

Note

If you have not implemented Graph on CMS 12 and you use DXP, follow the standard upgrade process in PaaS Portal. Graph provisioning is an additional step in your existing CMS project in PaaS Portal. Deploy to Integration, then Preproduction, and then Production. In this scenario, no CMS 12 production instance runs in parallel with a CMS 13 production instance.

Option 1: Migrate to a CMS 13 environment (recommended)

Use the Project Migration tab to move to a CMS 13 project without affecting your live site. Breaking Optimizely Graph schema changes occur when you switch from CMS 12 to CMS 13, which causes downtime. This process creates a Graph instance in the target project.

Submit a ticket to Optimizely Support to initiate a Project Migration for CMS 13. After Optimizely Support completes the ticket, the Project Migration tab displays in your Developer portal project.

VPN, certificates, SendGrid, and ADE environments

Review the following considerations before you start a migration:

• If a warning displays about certificates, Virtual Private Networks (VPN), or Advanced Delivery Environments (ADE) when you start a migration, contact Optimizely Support to proceed.
• If your project uses the ADE environment, it does not appear in Project Migration. Contact Optimizely Support to provision an ADE environment in your CMS 13 project and migrate contents.
• If you use a VPN in the current project, provision and configure a VPN for the target project. Optimizely deletes the old VPN connection when you complete the migration.
• Configure and link a SendGrid service to the CMS 12 project. Contact Optimizely Support to proceed.

Delete the target project at any time by clicking Abort Migration if you no longer need it.

Deploy and validate the target environment

1. Generate API keys for your deployment tooling to deploy code packages and test them in the target environment.

2. Deploy the updated code to the environment and validate that it works. Add and configure the EPiServer.CloudPlatform.Cms package as described in Deploy a CMS site. Start with the Integration environment, then continue with Preproduction and Production.

   Consider the following options during deployment:

   • Copy content from the source to the target project to verify compatibility with the same data. Any environment is valid as the source.

   • Copy content during the go-live step to ensure you have the latest data when you finalize the migration.

   📘

   Note

   The content copy process applies to BLOB data and the CMS database only. After the copy completes, sync content and content types to Graph by running the Optimizely Graph Full Synchronization job in CMS.

   • Access tools and logs for troubleshooting in the Azure portal.

3. Copy hostnames to the target project to prepare for go-live. The system prepares the hostnames, but they remain inactive. Some older hostnames require DNS verification records to work in the project. Add these records during the following step.

4. Click Check DNS records to verify the DNS record status after you add the records.

After DNS verification completes, migrate the whole project or migrate hostnames individually.

Migrate the whole project

Sync content from the source to the target project before going live. Pause the environments in the source project during this final phase. Put each environment into maintenance mode to prevent data changes during the swap. After you enter maintenance mode, you cannot abort the migration until you cancel it.

Complete the migration

After you migrate the last environment from CMS 12 and move all hostnames to the target project, CMS keeps the CMS 12 environment for 14 days after the last go-live. A notification lets you extend this period by clicking Need More Time?

1. Activate maintenance mode through the Maintenance Page or by putting the source environment into Read Only mode. Read Only mode must be supported in the source project. Go to Configure database mode for implementation details.
2. Click Abort Maintenance Mode if you encounter a problem. After you activate maintenance mode, the environment is ready for go-live.

Test maintenance mode

Test maintenance mode and go-live on Integration and Preproduction before proceeding to Production because downtime is possible.

After you enter maintenance mode, follow these steps:

1. Click Go Live to make the environment live in the project.
2. (Optional) Click Cancel Go Live to reverse the operation if needed.

Migrate hostnames individually

If you do not need data consistency between the two projects, migrate one hostname at a time. With this approach, both projects are live, but some hostnames target the previous project while others are active in the target project.

1. Click a hostname to preview it.
2. Click Ready for Go live if the hostname renders as expected.
3. Click Go live when all hostnames that should go live display Ready for go live.
4. Verify that the hostnames marked Ready for go live are live in the target project.
5. Click Complete Migration after the Integration, Preproduction, and Production environments are live. The system schedules resources in the source project for decommissioning.

When you migrate hostnames, complete one of the following actions:

• Migrate all hostnames from the previous project to your CMS 13 project through the migration tool.
• Delete unused hostnames from the old project that you do not want to move. All hostnames must be migrated or deleted to complete the migration.

📘

Note

Do not manually recreate hostnames you want to move from the old project. Use the migration tool to transfer them.

For headless implementations (Optimizely-hosted or external), deploy to the front end after you complete the CMS migration steps. For Optimizely-hosted front ends, request a front-end environment through an Optimizely Support ticket. Deploy your front-end code and move the hostnames with Optimizely Support.

Click Complete Migration to finish. Optimizely keeps the source project for seven days before removing it. You cannot cancel Complete Migration.

Auto-complete the migration

After you go live with the last environment from CMS 12 and move all hostnames to the target project, CMS keeps the CMS 12 environment for 14 days after the last go-live. A notification lets you extend this period by clicking Need More Time?

Option 2: In-place upgrade with DXP deployment slots (downtime risk)

Use deployment slots in DXP Management Portal to upgrade to CMS 13 as an alternative to Project Migration. This option is faster than migrating to a project, but it introduces a risk of downtime.

Deployment slots let you validate code before it replaces the live site. This approach is relevant for CMS 13 upgrades when you already use Optimizely Graph on CMS 12.

Understand deployment slots

A deployment slot is a temporary cloned version of a website that DXP creates during deployment. The deployment engine creates and manages slots automatically.

During deployment, DXP Management Portal creates a slot that mirrors the current production configuration, deploys code into it, warms it up, and swaps it into production if validation succeeds.

Deployment slots provide the following capabilities:

• Zero-downtime releases (requires a Maintenance Page in the CMS 13 migration).
• Pre-go-live validation (smoke testing).
• Safe rollback if the deployment fails.
• Production-like testing before the traffic switch.

Deploy through a deployment slot

Follow these steps when you start a zero-downtime deployment:

1. Log in to DXP Management Portal at https://paasportal.episerver.net.

2. Locate the organization and project you want to deploy, and click the project name to open it.

3. Click Deployments to view deployment options.

4. Select Zero downtime mode. The system selects the Use maintenance page checkbox automatically.

5. Select one of the following zero-downtime options for CMS 13 migrations:

   • Read Only (recommended) – The cloned site runs in Read Only mode. The system applies no changes to the cloned copy, and no data loss occurs.

   • Read Write – The cloned site runs in Read Write mode and accepts data writes.

     ❗️

     Warning

     The system discards data written to the cloned database when the deployment completes. Read Write mode increases compatibility with more features and add-ons, but use it only when data loss is acceptable. Inform editors that no updates should be made during this phase.

6. Select the Use maintenance page checkbox because the deployment includes database schema updates or content type changes. This displays a maintenance page while the site is offline.

7. Click Start Now. A progress bar displays the deployment progress. A confirmation message displays when the first part completes.

8. Click View output log to review deployment step details.

9. (Optional) Click Cancel to stop the deployment and roll back changes.

10. Click Preview to verify that the sites in the slot work as expected. Configure your Optimizely site to respond to the slot address. Use routing rules to validate the site in the slot.

11. Verify the swap result. If the site works as expected, the system swaps it into the production slot of the current target environment (Preproduction or Production) and stops the old slot. If the site does not behave as expected, the system aborts the swap and stops the slot site. The system saves files for troubleshooting or until a new deployment is attempted.

12. Proceed with Production-level changes after Integration and Preproduction work as expected.

For headless implementations (Optimizely-hosted or external), deploy to the front end after you complete the CMS migration steps.