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 new 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 new project resources.

    This creates a new project that supports CMS 12 / 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 and/or VPNs when you start a migration, please contact support to proceed.

    If you no longer need the target project after it is provisioned, you can delete the target project 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 here. 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 that you have the latest data when finalizing the migration to the new project
    • You can access more tools/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 either choose to migrate the whole project or migrate hostnames individually.

Migrate the whole project

The final step is to Go live. You can sync content from source to target project first. 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 to use it. 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 new project. You can click Cancel Go live if needed.

Migrate hostnames individually

If data consistency between the two projects isn't needed, then it is also possible to migrate one hostname at a time. With this approach, both projects are live but some hostnames will target the previous project while some hostnames are live in the new project.

  1. Click a hostname to preview it.
  2. If hostname renders as expected, click Ready for Go live
  1. When all the hostnames that should go live are Ready for go live, click Go live
  1. All 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