Migration from 8 to 13 - A Basic Step-by-Step Guide - Part 1

A Basic Step-by-Step Guide

Migrating an Umbraco project can be complex, requiring careful planning and execution. This guide provides a basic step-by-step approach to ensure a smooth migration from Umbraco 8 to Umbraco 10, and eventually to Umbraco 13.

So at Tres, we are actively migrating versions from Framework to Core. Previously we did migrations from 7 to 10 but now comes the big step from Umbraco 8 to 13. 

Because  Umbraco 13 sees Nested Content as legacy we also want to convert this data to the blocklist editor to be ready for 14 and higher. 

While these steps offer a general framework, specific situations may require deviations. Always be prepared to adapt as needed. In the next few weeks, I will work on some specific steps for example, and provide you with some tips or steps.

All the posts regarding Migration are as is. So Always validate your work and see this as a tips blog post instead of the way to go.

Database Migration Steps

  • Place Database Locally
    Start by placing a copy of your database on a local environment to perform the initial validation and testing.
  • Validate Functionality in Umbraco 8
    Ensure that everything works correctly in your Umbraco 8 project. Fix any issues before proceeding. Please don't forget the media and that forms are stored in the database!
  • Export uSync (+ Content Edition) for Umbraco 8
    This step is crucial. Export your uSync configuration, including content editions, and use the latest version of usync suitable for Umbraco 8.
  • Create a Backup of the Umbraco 8 Database
    Always back up your database before making significant changes.
    This is because if you continue and something goes wrong you can go back to this backup!

  • Copy Database to clientname-V10
    Create a copy of your database, preparing it for the upgrade to Umbraco 10.
  • Test Umbraco 10 Project to the Database
    Connect your test Umbraco 10 project to the copied database.
  • Upgrade the Database to Umbraco 10
    Follow the upgrade process to convert your database to the Umbraco 10 format.
  • Backup the Umbraco 10 Migration
    Create a backup of your Umbraco 10 database post-migration.
  • Copy uSync from Original to Umbraco 10 Project
    Transfer the uSync files from the original project to the Umbraco 10 project.
  • Start uSync Migrations - Convert Files
    • Run uSync migrations to convert files where you choose nested content to content blocks.
    • Address any warnings or errors that arise during the process.
  • Import All via uSync Migrations
    Import all data and configurations via uSync, checking logs for any errors.
  • Create a Backup of clientname-V10
    Back up your Umbraco 10 database to safeguard your progress.
  • Restore Backup to clientname-V13
    Restore your Umbraco 10 backup to a new Umbraco 13 database.
  • Clear Property Data via SQL Query
    Run an SQL query to clear property data for specific editors to avoid import issues. In this case, we do this for all Nested Content Property Data. 

    This will help with usync import.

  • Verify Block List Functionality
    Ensure that the environment with the block list is functioning correctly.
    • Can you open the blocklist? 
    • Do you see all the expected editors? 
      • if you are missing one maybe the package is already migrated, if not you can extend usync migrations to convert that datatype to a new format.

Code Steps

  1. Create a Separate Project for Models (V10 & V13)
    Set up a new project for your models. I like to separate them from the original project. Read Umbraco Docs for this.
  2. Generate Models and Link to Your Website Project
    Generate the necessary models and integrate them with your website project. Does everything build? Then continue
  3. Execute Query on Original V8 Database
    Retrieve all active element types used in nc editors. Migrate these views and content types to the new setup. This way you don't need to migrate stuff that isn't used anymore.
  4. Start with Layout Development
    • Comment out the page template logic but start with your basic layout. 
  5. Build and Verify Head and Foot Layouts
    • Implement basic scripts for the head and foot sections.
    • Verify functionality before proceeding.
  6. Continue with Other Templates
    • Extend the layout development to all other templates.
    • Ensure each template has a working basic layout.

In our solutions, we used to have a lot of surface controllers called by the HTML.RenderActions. This can be replaced by ViewComponents, but we had a lot of logic where we shared the same stuff. In some cases, a view component is more work than creating a service that you can inject when needed into your cshtml. 

By following these basic steps and being prepared to adjust as necessary, you can effectively migrate your Umbraco project to newer versions, ensuring a smooth transition and minimizing downtime. Remember, each migration is unique, and flexibility is key to success.

In the next blog post I will explain usync migrations and tips and tricks.

And if you need some advice just contact me.