Migrating to Umbraco CMS: Key Considerations for Developers

Making a switch to a content management system platform is never an easy decision, especially when your content and integrations and workflows are deeply embedded in an existing system. If Umbraco is something you are considering it is probably because you have a good reason to consider Umbraco. It’s open source, built on ASP.NET Core and provides developers with an unusual amount of control without locking them into a rigid structure.

That said, a smooth migration doesn’t just happen. This is what developers need to consider before, during and after the move.

Understand What You're Moving From

Before writing a single line of migration code, lay out your current setup. What you leave behind is almost entirely responsible for the complexity of your migration.

Question yourself:

• What CMS are you migrating from WordPress, Sitecore, Drupal, a custom-built system?
• How is your content organised? Document types, well-defined or messy?
• Any custom plugins, third-party integrations or legacy APIs?
• Is your front-end closely tied to the existing CMS or headless?

This audit will drive everything your timeline, your data migration strategy and what Umbraco features to take advantage of.

First is content modelling

Replicating an existing CMS structure into Umbraco is often a significant error users typically experience during migration.

The document type is the primary component of the Umbraco content model. Document types contain definitions for the buildup and types of information (fields) defined by objects within the CMS and their various properties. To avoid defining each document type by directly copying an existing document type schema (also referred to as a "1:1" match), users should take the opportunity presented by the migration to reassess the overall design of their content architecture and begin fresh!

Points to consider:

• Create compositions (Umbraco’s mixins) to group reusable fields so you avoid duplicating properties across Document Types
• Plan your content tree carefully – Default Umbraco hierarchy is reflected in URLs
• Decide early if you're going coupled (Razor/MVC views) or headless (Content Delivery API) - this makes a big difference on how you model content

Data Migration: Expect Edge Cases

Migrations tend to fall down when it comes to moving content between systems. As Umbraco does not provide a generic import tool, you will probably need to write custom migration scripts.

Some practical points:

• For easier cases, use Umbraco's Content Import/Export (available in Umbraco 13+), but don't rely on it for complex or high-volume content
• Use the ContentService and MediaService APIs to programmatically bulk create and publish content
• Mapping your old rich text fields can be tricky – you’ll need to reconcile any embedded images, internal links and media references with Umbraco’s media library.
• Run your migration scripts against a staging environment a lot before touching production.
• Have a rollback plan. Always.

Handling Media and Assets

Media migrations tend to be underestimated. Umbraco has its own media library and its own folder structure. You won't be able to reference external URLs or raw file paths out of the box.

• Import assets in bulk to the Media section of Umbraco before migrating referencing content
• If you come from a CDN-heavy setup, decide if you are moving to Umbraco-managed media or keeping your CDN and referencing it via external URLs in your property editors
• If your editors are cropping images and using focal points you will need to reconfigure this in umbraco

Integrations and APIs

Although Umbraco can be integrated with other systems, it is likely that any existing integrations will require some modifications on your part to be able to work inside Umbraco.

• Forms: If you use a native CMS based tool to create forms, you must create forms using Umbraco's native functionality or integrate a third party web service (such as HubSpot or Typeform) to create a form.
• Search: Umbraco includes examine (which is based off lucene). However, if you want to provide a more advanced search option, you would look at integrating either algolia or azure cognitive search.
• Commerce, CRM, DAM: All integrations will need to be rebuilt using Umbraco’s service layer or Content Delivery API include this in your timeline.

Environment Setup and Deployment

Umbraco's backend is developed on the .NET architecture. That means if you're switching from a PHP based CMS, your host environment will differ from what you currently use.

• For Umbraco to operate correctly, you will need a host that supports the .NET Framework. Some examples of that are:

- Microsoft Azure

- Amazon Web Services (AWS)

- Windows or Linux servers you have total control over

• When getting started with Umbraco, it's a good practice to establish multiple environments (i.e., development, staging, production) at the same time. To maintain the same configuration across all of your environments, you can utilize Umbraco's uSync package.
• If you want someone to manage your hosting and environment setup you could consider Umbraco Cloud. This option is worth looking into especially if you have a team.

Plan for Editor Training

• A migration that is too technical and confuses the people who edit your content is not a migration. The back office of Umbraco is easy to use. It is different from what the editors are used to.
• You should make Document Types and data types that the editors can use easily not the developers.
• If the editors need a way to use the system you can make custom dashboard views for them.
• It is an idea to have a practice session with the editors before everything goes live this will save you a lot of trouble with support later.

The Things To Check Before You Go Live

• Content and media are all moved over. Checked to make sure they are correct
• All the links inside the website are checked to make sure they work
• The redirects for the website addresses are set up this is very important
• The search function is. Tested to make sure it works
• All the integrations are tested to make sure they work from start, to finish
• The website is tested to make sure it can handle a lot of users at the time
• The editors are. They agree that everything is ready to go live

Migrating to Umbraco needs a plan but it is worth it because Umbraco is very flexible. Umbraco can grow with your project so it does not matter if you are making a website with many pages or a headless API-first architecture. If you get the basics of Umbraco from the start you will not have to fix mistakes later on. This way you will save a lot of time when you are working with Umbraco.

Written by

Nishant Vaghasiya

Technical Architect

I'm Nishant Vaghasiya, a Technical Architect and Umbraco & Sitecore Certified Developer at Arroact Technologies. I specialise in building digital solutions with Umbraco and Sitecore that are practical, scalable, and built to last.

Over the years, I've learned that the best solutions aren't always the most complex ones, they're the ones that make a team's day-to-day work simpler and give them confidence that the system won't let them down.

That's what drives me writing code that performs well, stays reliable, and continues to create real impact long after it goes live.