Migrating to a headless CMS: what to consider from a developer’s perspective

Migrating to a headless CMS is a complex journey that brings big benefits to both editors and developers . The process does not only involve moving to a new stack but also requires a clear plan for the content.

Here are two options:

1. Create a new project from scratch. Content will be rewritten or completely re-inserted by hand on the new CMS.
2. Transfer some of the content. In this case, the structure of the site may still change, but the amount of data you inherit from the previous project is still significant.

In any case, moving to headless should be seen as a perfect opportunity to rethink the project in many respects, such as the architecture, content model, and editorial processes.

These aspects may have been greatly affected by the rigidity of a legacy CMS, and thus need to be redesigned in light of the flexibility gained by moving to headless.

Refactoring the content model

Redesigning the content model is a step that should be considered in any case since we are talking about migrating from a legacy solution. However, this work should also be considered when moving from one headless system to another since the flexibility of content modeling is different from platform to platform.

This activity also affects developers because they will be the ones who have to create the components in the CMS and code.

It is critical to understand very well, together with your content editors, the content modeling options of the new platform and to think about what the structure should look like and what degree of flexibility you want. This will create a solid foundation on which the rest of the migration will rest.

What to migrate and why

Content migration is often taken for granted, but is it really necessary to copy all or even part of your content as is? The idea that you necessarily have to use a tool to import text and assets from one CMS to another is wrong because, in most cases, you will want to avoid creating a carbon copy of your existing site.

Start by creating a map of what you want to migrate and why. In this map, you must then make a distinction between pages that you will move by hand, and those that you will import with a dedicated tool or a custom script.

Typically, you would want to differentiate between the following types of entries:

• Entries to be migrated by hand: mainly landing pages. It is very difficult to transfer them programmatically because of the very varied content model. These pages are usually made up of several sections, and re-mapping fields from the old CMS to the new modular structure of components will be too hard a task. Therefore, it is necessary to take care of it manually and benefit from the new and improved content model.
• Entries to be bulk migrated: content such as blog entries, products, or other types that have a fixed structure and are present in large numbers. The fields on these pages are easier to map to the new ones because of the fixed structure of their data. Each field in the old CMS can be transferred to a field in the new one, transforming the content programmatically where needed.

Data transformation

When you migrate content, you may need to transform some data.

Let's start with the conversion from strings to JSON objects. What might be simple text in the old CMS, such as the URL of an asset or a link to an internal page, may be an object in the new CMS.

For example, in the case of Storyblok, the asset selection field is an object that contains several properties, such as filename, id, alt, focus, and other information specific to that instance of the file inside the content of a page.

Another very common case is text fields with formatting. If a WYSIWYG was used in the old CMS, the content will have HTML tags. During migration you will have to transform the format to be compatible with the data structure of the rich text field in the new platform.

For example, Storyblok stores rich text field data in JSON format so that the developer has full control of the presentation. In this case, a conversion from HTML to JSON will be needed.

The same transformation should be performed when the field in the previous platform is plain text without any HTML tags. In this case, one will go directly from string to JSON.

Depending on the project, other types of conversion may be required, which is why it is important to do a thorough analysis before starting.

Bulk migrating content

There are three common options to bulk migrate entries:

• API access: this is the best case. If the previous platform has APIs for extracting content, you can create a script that makes use of them and then writes the data to the new CMS.
• DB access: you do not have APIs available, and then you have to query the legacy system DB directly. This can be a problem in some cases, especially if the structure of the tables is very complex, because you will have to take time to understand it and then perform data aggregation queries.
• Content scraping: this is the last resort before despair. In the event that the previous platform is inaccessible, there remains the possibility of retrieving content with a script that scrapes directly from published pages. If the HTML structure of the pages is still the same, it will be possible to do a mapping between data extracted from specific DOM nodes and fields in the new CMS.

Transferring via API is quick, and thousands of entries can be imported in a matter of minutes.

It would be ideal for the import script to be idempotent because you are likely to have to run it multiple times due to changes in the content model during the migration or because you realize after that something went wrong in transferring some fields. After an error during the process, being able to simply change the mapping or data transformation layer and re-run the script without having to worry about creating duplicate entries in the CMS will help speed up the work and ensure a good result.

Once the import is finished, you can also check the entries and validate their data. You can then create a log with validation problems, such as a required field that is instead blank, and proceed to fix them either with a script if there is a common pattern among the errors of multiple entries or manually.

Need for customization on the new CMS

In the new CMS, it may be necessary to recreate features needed by editors from the old one, such as custom fields or dashboards.

You need to consult the documentation of the new platform to understand how to customize it and be able to bridge any gaps with the old one.

Storyblok offers several tools to extend its basic functionalities , and you can then accommodate your editors' needs.

Assets migration

Usually, with a monolithic CMS, users rely on its internal asset manager, and it is, therefore, less common to use a third-party DAM.

In case you have to migrate assets as well, you will have to import all of them to the new CMS or DAM chosen for your composable stack.

You must then run a script to clone assets from one system to another, making sure to copy the meta data associated with them as well.

Some basic points need to be taken into consideration:

• It is very useful to generate, during the migration script execution, a mapping between the old and new URLs in a log to be shared among the team of developers involved in the project.
• In case of problems during the import process, you should take care of not loading the same assets multiple times.
• Inside the imported entries, the old URL of each asset should be replaced with the new one. This can be done via the API by checking all entries in the new CMS and replacing the URL string in the content.
• In the case of an external DAM, you will have to use an integration for the new system. If an official package is not available, you will have to evaluate the cost of developing one.
• SEO: if there are assets with high search engine rankings, you need to decide what to do with them because changing the URL to a document means losing the ranking you have obtained. For example, you can consider leaving those specific files at the current address. In this case, those files should be excluded from the import.

In the case of a migration to Storyblok, you will get a DAM with a free service for image transformation , an editor directly inside the CMS, and other features, such as the ability to mark assets as private. In addition, you can use external DAMs thanks to integrations with some of the most popular services , and you can create your own custom one with an open-source starter kit .

Talk to your editors

A very important final recommendation: talk to your editors before, during, and after the process, and work closely together.

Editors need to have a good experience with the CMS since they will be using it on a daily basis. In addition, they are able to support the developers in verifying that the data migration is correct.

As with almost any other phase in the life of a web project, migration is as much work for developers as it is for editors, and collaboration is the key to success.