How to migrate from a legacy CMS system to a headless CMS without risk

The good old world

What once began as a fully integrated content management solution and all-in-one system can increasingly become an obstacle to innovation in today's fast-paced digital world. New delivery channels such as online platforms and native apps require CMS data to be machine-readable and flexibly transformable in order to adapt it to specific needs.

For example, a new blog post should be automatically published on Bluesky and displayed as a push notification in a mobile shopping app. This is often a difficult challenge for closed systems.

However, switching to a modern CMS also comes with challenges: The initial effort for configuration, training, and data migration can be high, as can the hurdle of establishing a new content editor among users. Examples of modern headless CMS systems include FirstSpirit CaaS from Crownpeak, Contentful, and Magnolia, which we have already covered in detail in other blog posts.

In this blog post, I will focus on the predictable, sustainable, and smooth migration of a large amount of content to a new CMS system.

The incremental CMS introduction

Let's assume a classic CMS that has been regularly filled with relevant content over many years and is of great importance for marketing purposes, paying customers, or SEO optimization, for example. The website is highly optimized but strongly linked to the CMS. If, for example, an HTML tag needs to be changed on the website to display a heading more prominently, this must be done in the CMS in the HTML template—even if the text of the heading does not change.

The first step is therefore to decouple the CMS, the content, and the presentation in the form of the website. To do this, an interface is introduced that serves as a new contract between the legacy CMS and the front end. Both systems can define different data structures.

Important aspects for the front-end API contract are:

• Only provide the necessary data (for example, no unnecessary metadata).
• All relevant, linked data is provided.
• A simple structure that can be processed top-down.

API Contract
An API contract describes the formal agreement or specification of how two systems or applications communicate with each other via an API (application programming interface). It defines the structure of the requests and responses that the API expects or delivers.

But: “My CMS can only generate HTML, not structured data!”

HTML is also structured and machine-readable. If HTML can be generated, it is entirely possible to create JSON, for example, which can be consumed by the new content API.

But: "Now that my old CMS and the front end are decoupled, new features can be implemented super fast. Actually, I don't need a new CMS anymore..."

Congratulations! It is often possible to expand an existing CMS into a headless CMS with the help of a new module. One example of this is the CMS FirstSpirit, which supports a headless architecture with the help of the CaaS or Headless2Go modules.

No risk. Lots of fun.

You now want to proceed with the introduction of the CMS. You see numerous advantages for editors, such as a modern WYSIWYG editor, a tidy drag-and-drop library for page elements, new storytelling concepts, and a workflow for publishing content across multiple channels.

Migrating data from the old to the new CMS often involves a lot of effort. However, this also provides an opportunity to optimize existing data, remove content that is no longer needed, and reduce technical debt. If old dependencies in the code can be removed, the loading time of a website can often be accelerated, which in turn has positive SEO effects.

Basically, there are two common types of migration:

• Big Bang Migration
  The data is transferred from the old to the new CMS in a single step. This method is particularly suitable for smaller amounts of data. If an error occurs, the migration must be performed again.
• Permanent Migration
  Changes in the old CMS are mirrored in real time in the new CMS. The old CMS remains the primary system, while the new CMS is initially used for read-only access.

Permanent migration is particularly suitable for large amounts of data and an agile way of working, where results need to be productive quickly and generate economic added value. In one project, for example, certain live blog content was initially migrated to the new CMS, while agency reports continued to be played out from the old CMS. The editors were extremely satisfied with the new, significantly simpler editor, and the efficiency gains for newly created content were measurable.

This was also achieved thanks to the rapid feedback from key users, who were the first to use the new CMS in productive use and provided optimization suggestions at an early stage. These first users acted as multipliers and inspired their colleagues, which led to a high level of acceptance of the new software.

Not just migrations: Headless in application

When launching a new customer website, a headless architecture was used from the outset to provide content flexibly and across channels. The content is maintained in the FirstSpirit CMS and automatically stored in Elasticsearch when published via the Headless2Go module. The Next.js front end accesses this data in real time, prepares it for rendering, and delivers finished pages directly to users (server-side rendering for SEO optimization). After the initial playout, the website loads new content via a JSON interface and renders it directly to the user – quickly and efficiently.

Setting the right course
Another advantage of the content API as a link between CMS and output channels is its function as a switch. For example, it can be specified that only certain areas of the website are played from the new CMS or that the new page is initially only made available to a defined group of “beta” users or testers.

Future-proof

No matter what new requirements you face in the future, with a decoupled architecture for your online presence, you are well prepared:

• A new design for your website or a new output channel can be implemented without making any changes to the CMS.
• Extensions can be made to the CMS without affecting consumers of the content API.

Content API: Backend-for-frontend
In the backend-for-frontend architecture pattern, the preparation of data for output and presentation in the CMS is decoupled, similar to the decoupling of content. The data is tailored to each channel. This reduces complexity and avoids unnecessary data load, for example in single-page applications. The backend brings together different data sources and makes them available via a clearly defined, uniform interface.

Our Digital Experience business line offers your company the ideal combination of strategic and technical consulting, in-depth industry knowledge, diverse project experience, and technical expertise for CMS migrations of any size.