Project migration for CMS 12 with Optimizely Graph

If you are currently using Optimizely Graph on your CMS 12 instance, use one of the following options to initiate your migration to CMS 13.

Option 1: Project migration to a new CMS 13 environment (recommended)

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

To create a project that supports CMS 13 and is immediately accessible, you can migrate in a few steps, as explained below.

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

VPN, certificates, Sendgrid, and ADE environments

If you are prompted with a warning regarding certificates, Virtual Private Networks (VPN), or Advanced Delivery Environments (ADE) when you start a migration, contact Optimizely Support to proceed.
If your current project has the ADE environment, it is not visible in the Project Migration. Contact Optimizely Support to provision an ADE environment in your CMS 13 project and migrate contents.
If you actively use a VPN in the current project, you must provision and configure a new VPN for the target project. Optimizely deletes the old VPN connection when you complete the migration.
You must set up and link a SendGrid service to the CMS 12 project. Contact Optimizely Support to proceed.

If you no longer need the target project after provisioning it, you can delete it using Abort Migration.

Set up access for your deployment tooling by generating API keys so you can deploy the code packages and start testing them in the new environment.
Deploy the updated code to the environment and validate that it works. Make sure you add and configure the EPiServer.CloudPlatform.Cms package as described in Deploy a new CMS site. Begin by setting up the Integration environment, then continue with Preproduction and Production to ensure it works there.

a. You can copy content from the source to the target project to ensure compatibility with the same data.

b. You can choose any environment as the source environment.

c. You can also copy content during the Go-live step to ensure you have the latest data when finalizing the migration to the new project.

📘
Note
This content copy process only applies to BLOB data and the CMS database. After the copy occurs, you must sync content and content types to Graph by running an Optimizely Graph Full Synchronization job in the CMS.

d. You can access more tools or logs for troubleshooting in the Azure portal.
Prepare for go-live by copying the hostnames to the target project. In this step, the system prepares the hostnames, but they remain inactive. Some older hostnames may require DNS verification records to work in the project; you can add these records during the following step.
Click Check DNS records to verify the DNS record status after the records are added.

Next, you can migrate the whole project or migrate hostnames individually.

Migrate the whole project

The final step is to go live. You can first sync content from the source to the target project. Pause the environments in the source project during this final phase. Put each environment into maintenance mode to prevent data changes during the swap. When you enter maintenance mode, you cannot abort the migration until you cancel it.

Complete the migration

When you finish migrating 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 time by clicking Need More Time?

Maintenance mode – You can activate maintenance mode with the Maintenance Page or by putting the source environment into Read Only mode. Read Only mode must be supported in the source project for use. See Configure database-mode documentation for information on implementation.
Click Abort Maintenance Mode if you encounter a problem after entering the mode. After you activate maintenance mode, the environment is ready for Go live.

Maintenance mode testing

You must test maintenance mode and Go live on Integration and Preproduction before proceeding to Production because it may cause some downtime.

After entering maintenance mode, click Go Live to make the environment live in the project. You can click Cancel Go Live if needed.

Migrate hostnames individually

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

Click a hostname to preview it.
If the hostname renders as expected, click Ready for Go live.
When the hostnames that should go live are Ready for go live, click Go live.
Hostnames marked as Ready for go live will now be live in the new project.
After the Integration, Preproduction, and Production environments are live, click Complete Migration. The resources in the source project are no longer needed and will be scheduled for decommissioning.

When migrating hostnames, make sure you do either of the following steps:

Migrate all hostnames from the previous project to your new CMS 13 project using the migration tool provided.
Delete unused hostnames from your old project that you do not want to move over to the new one. To complete the migration, all hostnames must be migrated to the new CMS 13 project.

If you are on a headless implementation (either hosting with Optimizely or externally), you must make a new deployment to the frontend after you complete the CMS migration steps. For Optimizely-hosted frontends, you can request a new frontend through an Optimizely Support ticket. After this, you can deploy your frontend code to it and move the hostnames with the help of Optimizely Support.

You are now ready to use your CMS 13 project and Optimizely Graph.

You should not manually recreate hostnames you want to move from the old project to the new one.

To finish, click Complete Migration manually. Optimizely keeps the source project for seven days before removing it. You cannot cancel the Complete Migration action.

Auto-complete the migration

When 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 time by clicking Need More Time?

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

This option explains how to use deployment slots in Optimizely DXP Management Portal and how to create, validate, and promote deployments using the DXP self-service deployment workflow as you upgrade to CMS 13, as an alternative to the Project Migration tooling. This option is faster than migrating to a new project, but it introduces a risk of downtime for the site.

Deployment slots enable safe releases by letting you validate code before it replaces the live site. This will be relevant in your CMS 13 upgrade path, especially if you are already using Optimizely Graph on CMS 12.

What is a deployment slot?

A deployment slot is a temporary cloned version of a website that DXP creates during deployment.

It allows new code to be deployed and validated before replacing the live site.

The deployment engine automatically creates and manages slots. You do not manually create them yourself. During deployment, DXP Management Portal creates a slot that mirrors the current production configuration, deploys new code into it, warms it up, and then swaps it into production if validation succeeds.

Deployment slots enable the following capabilities:

Zero-downtime releases (this requires a Maintenance Page in the CMS 13 migration, however)
Pre-go-live validation ("smoke testing")
Safe rollback if something fails
Production-like testing before traffic switch

Steps to take during a deployment

When you start a zero-downtime deployment, follow these steps:

Log in to the DXP Management Portal at https://paasportal.episerver.net.
Locate the organization and project you want to deploy changes for, and click on the project name to open it.
Click the Deployments tab to see options for a deployment that has been started.
When using Zero downtime mode, the Use maintenance page system automatically selects the checkbox.
Zero downtime mode – For CMS 13 migrations, select one of the following options:
- Read Only (recommended) – The cloned site runs in Read Only mode, so the system applies no changes to the temporarily cloned copy. No data loss occurs during the deployment.
- Read Write – (Data loss likely) The cloned site runs in Read Write mode and lets data be written to it.
  
  ❗️
  Warning
  Any data written to the cloned database while the deployment is running will be lost at the end of the deployment. The ReadWrite mode increases compatibility with more features and add-ons, but should be used only when data loss is acceptable for the site. (You should make editors aware that no updates should be made to the site during this phase of the deployment.)
Use maintenance page checkbox – Because the deployment includes database schema updates or changes to content types, select to display a maintenance page while the site is offline.
Click Start Now. A progress bar displays the progress of the deployment. When the first part of the deployment is done, a confirmation message displays in the portal.
Click View output log to see the details of the deployment step.
You can click Cancel to stop the deployment and roll back the changes if needed.
When done, click the Preview link to verify that the sites in the slot are working as expected. For this to work, configure your Optimizely site to respond to the slot address. You can use routing rules to validate the site in the slot as well.
If the site works as expected, it is swapped into the site's production slot of the current target environment (Preproduction or Production), and the system stops the old slot. If the site in the slot does not behave as expected, the system aborts the swap and stops the slot site. The system saves the files for troubleshooting or until a new deployment is attempted.
When everything works as expected on lower environments (Integration and Preproduction), proceed with Production-level changes.

If you are on a headless implementation (either hosting with Optimizely or externally), you must deploy to the front end after completing the CMS migration steps.