HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Migrate to CMS 12 or Optimizely Customized Commerce 14

Describes how to migrate your project for use with Optimizely Content Management System (CMS) 12 and Optimizely Customized Commerce 14).


Complete other steps first!

This is Step 3: Upgrade the Service Environment from the topic Upgrade to CMS 12.

You can use the Project Migration tab to move to a project that supports .NET 6 for CMS 12 and Customized Commerce 14. The migration can be done in a few steps, as explained below.

  1. Click Start Migration in the Project Migration tab to provision project resources.

    This creates a project that supports CMS 12 or Customized Commerce 14 and is immediately accessible.



    It might take some time before the new project is visible in the Azure portal. Log out and log back in, or wait for a few minutes and it should show up automatically.

    The system creates a new find index for the target project. Find data stored directly in Find's DB does not migrate: Connectors, Synonyms, Boosting (UnifiedWeights), Related Queries (DidYouMean), Autocomplete


    VPN & Certificates

    If you are prompted with a warning regarding certificates or VPNs when you start a migration, contact Support to proceed.

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

  2. Start by setting up access for your deployment tooling by generating API keys so you can deploy the code packages and start testing it in the new environment.

  3. 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 Create a CMS site and deploy. Begin by setting up the Integration environment, then continue with Preproduction and Production to ensure it works there.

    • You can copy content from the source to the target project to ensure compatibility with the same data.
    • You can choose any environment as the source environment.
    • 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.
    • You can access more tools or logs for troubleshooting in the Azure portal.
  4. Prepare Go live by copying the hostnames to the target project. In this step, the hostnames are prepared but not active.

    Some older hostnames may require new DNS verification records to work in the new project, which can be done during the following step.

  5. Click Check DNS records to verify the DNS record status after the records are added.

Next, you can migrate the whole project or migrate host names 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. Each environment should be put into maintenance mode to prevent changes to data during the swap. When you enter maintenance mode, you cannot abort the migration until it is canceled.

  1. Maintenance mode – You can activate maintenance mode with 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 database-mode documentation for information on implementation.

  2. 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.

  3. 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 data consistency between the two projects isn't needed, then migrating one hostname at a time is also possible. With this approach, both projects are live, but some hostnames will target the previous project while others live in the new one.

  1. Click a hostname to preview it.
  2. If the hostname renders as expected, click Ready for Go live
  1. When the hostnames that should go live are Ready for go live, click Go live
  1. Hostnames marked as Ready for go live will now be live in the new project.
  2. 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.


Complete migration automatically

If all environments went live, Project Migration is completed automatically after 14 days since the last go-live was completed and all hostname are moved to the target project