Contentful is one of the leading headless and composable content management system (CMS) platforms on the market, attracting existing commerce retailers to migrate to its platform to take advantage of innovative capabilities to build dynamic, personalized experiences, reduce developer load, and scale with ease.
In this guide, we will draw from our experience migrating clients to Contentful and our recent report on Contentful, which draws insight from 300 Contentful users. From this, we’ve put together some of the most common challenges that retailers may face when replatforming to Contentful—and solutions to overcome them, including:
- Not taking the time for migration planning
- A lack of experience with / migrating to headless or composable architecture
- Incorrect content model
- Lack of platform expertise
- High learning curve for end users
Are you ready to take the leap to Contentful today? We can help.
Tell us moreUnderstanding the Migration Process
As a CMS, Contentful’s primary job is to support sales and marketing efforts by making creating, editing, and publishing content to any channel easier. Contentful has some of the best tools for the job, with a composable design, intuitive tools for editors, and fast-track developer resources—all to make it faster and easier to meet consumer demand for personalized experiences.
As big fans (and partners) of Contentful, we understand why you’ve chosen it to replace your current CMS—whether WordPress, Drupal, HubSpot, Joomla, or another. But there is no question that migrating to a new CMS—a process called replatforming—is a big job, one we can loosely think of in four stages:
- Planning: The most critical step in any migration process to understand how your platform currently works with all its integrations and data structure and any deficiencies you’re looking to correct by shifting to Contentful.
- Designing platform architecture: Deciding on how the current platform works with your broader ecosystem, considerations when using Contentful, and what integrations or custom features you may need to meet your goals.
- Migrating data: Moving structured and unstructured content from your current system into Contentful. Because of Contentful’s sophisticated content modeling, ensuring you’re successfully bringing overall content types and metadata can be a complex challenge.
- Testing and Optimization: Any migration should include significant testing to optimize for performance, security, SEO, and user experience.
Each of these stages is critical in ensuring the success of your migration, but as you’ll see, they are also the most common areas where we see businesses rush, often with sub-par results that fail to free up developer resources, contribute to editorial inefficiencies, or result in slow web performance—all of which fail to deliver on the intended ROI of investing in Contentful.
In the remainder of this guide, we will look closely at how these problems could be avoided through better migration planning.
Common Migration Challenges with Contentful
While it is common to face migration challenges in any platform shift, your first step in a successful Contentful migration is to get to know Contentful, which you can do in our straightforward Guide to Contentful and by opening a free Contentful account. A free account will help you experiment with content modeling and Contentful’s language, like Spaces, Locales, a Domain Model, and the Data Model.
Before you start any migration, it’s critical that you take the time to be aware of the most common challenges you will face when moving to Contentful. We’ll go through what we consider the five top challenges in turn, including insight from Contentful users we’ve surveyed and tips on overcoming them.
Problem #1 – Not taking the time for migration planning
It is very common to see businesses migrate to Contentful with an abstract belief that it will pay for itself, but without taking the time to document their current state or where they want to be. Without consulting with all stakeholders and documenting deficiencies, it’s very easy to repeat the same mistakes in setting up Contentful. For example, if your developers do not know that both editors and customers find your site difficult to navigate, they are likely to repeat the same mistakes in the new content model.
Contentful’s unique architecture and tools also require careful planning. For example, Contentful uses a specific rich text format that may require custom transformation scripts in order to avoid the loss of rich text.
A failure in migration planning may result in:
Solution: Migration Planning Best Practices
- Audit your existing platform so you know what customizations, integrations, or capabilities you need to replace or build and what technical debt you want to eliminate.
- Document deficiencies and pain points with the current platform, whether performance issues, lack of features, lack of channel support, etc.
- Audit your content to understand where it lives (on pages, in databases) and create a plan to:
- Map data – Know where all data is. Ensure you capture all data types (customer data, tracking data, third-party data, multimedia, metadata such as alt text and tags, page content, product data, rich text, etc.). Categorize data to help inform which fields you need and their relationships to content types.
- Clean content – Remove duplicate or unnecessary content, identify content needing updates.
- Plan to convert data – Create a plan to shift content into a structured format of discrete content types and fields. Map all existing content to future content to ensure nothing is overlooked.
- Plan locales – Define the locale strategy if you have international site(s) or content. Note that Contentful handles locales differently than other platforms, so it’s best not to assume familiarity with locales.
- Backup data – Create a solid backup of all data types.
- Define KPIs that express the improvements you’re looking for to guide the migration to Contentful and to set measurable objectives.
- Conduct a risk assessment to understand where migration issues may arise (e.g., data migration, SEO impact, etc.).
- Create an SEO plan, which includes benchmarking the current state with a web crawler (top pages, issues) and creating a plan to maintain and/or improve SEO (e.g., content updates, new structure) and redirect any removed content pages.
- Create a user role plan, mapping existing user roles to Contentful’s permission system.
- Create the technical migration plan. Understand how to extract content from your current platform (are there tools, what is the export format?). Know which tools or automated scripts can assist to reduce risk. In most cases, teams will need to develop custom migration scripts and tools to transform content and map legacy content to the new content model while preserving relationships and SEO. Plan to use Contentful’s Management API and Migration CLI tools to take advantage of unique syntax and capabilities.
- Create a robust error-handling strategy to handle failed content imports.
- Set up space management and environment workflows before you begin migration.
- Start with a pilot project to validate the content model and workflows before expanding organization-wide.
- Work within Contentful API limits, as rate limits impact migration.
There are a lot of ways to move from one CMS to another.
Problem #2 – A lack of experience with / migrating to headless or composable architecture
Moving from a traditional CMS to a decoupled, headless CMS is a powerful way to make content accessible for any device or channel, but the shift will require developers who:
- Are familiar with headless architecture
- Know how to move a site from traditional to headless architecture
- Have some experience in front-end development
- Understand how the shift impacts integrations
- Understand how tech stack decisions may impact the migration
Content Considerations
For most merchants moving from a traditional to a headless architecture, which decouples the content management from the content presentation, one of the biggest obstacles is that existing content is unstructured. In contrast, Contentful leverages structured content—small building blocks of data that can be easily repurposed and support personalization. However, moving unstructured content into Contentful can pose several challenges:
Inconsistent Taxonomies
To move from unstructured to structured content, developers must move existing content from single pages into fields and blocks and become familiar with new ways to manage content (via API). For data stored in databases (e.g., product data), differing naming conventions, product categorizations, and tagging schemas could lead to data fragmentation if not adequately planned for.
Overlapping Content
Multiple redundant product descriptions, landing pages, or promotions can create confusion when creating the data model and when moving existing data into the new content model.
Content Migration
The front-end development team needs to use Contentful’s Content Delivery API and GraphQL API to fetch content. Content migration requires careful planning and execution. Teams will need to be prepared to develop and use migration scripts to transform existing content into Contentful’s data structure, to map legacy content types to new content models, and create custom migration tools using Contentful’s Management API.
The migration process will include handling media assets, maintaining content relationships, and ensuring URL structures are preserved for SEO purposes.
Design Considerations
Migrating to Contentful requires a complete re-implementation of your site design, as legacy CMS systems rely on inflexible templates and style sheets that do not align with Contentful’s modular approach.
Rigid Legacy Templates
Existing CMS setups often rely on inflexible templates that don’t align with Contentful’s modular approach.
Frontend Considerations
The benefit of headless is the ability to choose the frontend framework(s) of your choice. The choice then is how many front-ends do you want and using which frameworks? This is usually informed by the content strategy, developer preference, and framework maturity (particularly in areas of performance and scalability).
Most Contentful developers prefer a JavaScript framework for front-end development, following the JavaScript SDK and starter kits for Next.js, React, Astro, Vue, and others. SDKs are also available for Java, PHP, Android, iOS, Python, Ruby, and .NET.
If your team does not have the skills to manage specific front-ends, an experienced Contentful partner can be both a short and long-term option to supplement your development team.
Backend Considerations
While Contentful is ideally set up to be the backend of your content infrastructure, there is the option to instead use a development framework. This choice can have an impact on the speed and manageability of your implementation, so consult with an experienced Contentful partner if you have questions.
Integrations and Extensions
Based upon your audit, you likely have several integrations that will need to be set up in Contentful to connect to systems of record (e.g., PIM, CRM, ERP, eCommerce) as well as third-party services in one or more ways:
- Retiring third-party services – In some cases, Contentful can replace the role of third-party services. Be sure to export any relevant data before closing accounts.
- Replacing third-party services – Finding a new third-party service provider to help consolidate or upgrade services or take advantage of a pre-built integration in the Marketplace.
- Custom integrations – Build a custom integration (via an app) to support a preferred service or extension of Contentful capabilities.
The Contentful App Framework was created to simplify the modular aspect of Contentful, helping developers to create apps to customize a Contentful space or to support integration with a third-party service or system of record. Apps available in the Contentful Marketplace now also use the same App Framework.
The Contentful App Framework supports creating apps to modify the user interface (frontend) as well as apps to run on your servers to interact with the Content Management API, providing more flexibility over using webhooks. Ideally, integrate with services or build apps one-by-one, starting with the most critical integrations, so you can test each integration/app (in staging) before going live.
Problem #3 – Incorrect content model
One of the first steps in setting up Contentful is establishing the content model—and this is the top area that developers struggle with, often resulting in delaying migration timelines. Unfortunately, an incorrect content model can result in a variety of downstream issues including:
- Slow editorial timelines
- A lack of design control
- Excess use of developer resources
- Page performance issues
Content models can be difficult to visualize, as the same content can look very different depending on where and how it’s used (each content type and presentation layer/front-end). This abstraction can make it very difficult to get started.
The most common mistakes we see in Contentful content models include:
- Too few content types, failing to reflect stakeholder needs and increasing developer reliance for changes.
- Too many content types, making the content model difficult to manage and resulting in editorial inconsistencies.
- Too many or too specifically labeled content fields, leading to excess database queries that slow content delivery and page rendering.
- A lack of clarity in field naming, leading to confusion and design inconsistency.
- Incorrect field types, leading to issues in content creation (e.g., a page body text field that does not support markdown) or future model upgrades (e.g., not using reference fields).
- Too rigid in design, often constraining editorial choice. Guardrails are important, but don’t go too far.
- A lack of guardrails (field validations) to enforce consistency.
- Incorrectly configured database, a missed opportunity to improve page performance.
As you can see, there are many ways a content model can go wrong, and it’s not always clear where the sweet spot is when designing the model.
How to Avoid Content Model Mistakes
Contentful offers a training module on content modeling as well as some content model patterns in its help center, but there are pros and cons to each pattern and often businesses don’t fit neatly into one pattern type (hence all the confusion). The Contentful AI Content Type Generator can also be helpful for simple websites, but may not be adequate if you have a large or complex website to migrate.
Every content model is unique, but in general, you can follow some best practices to avoid making a mistake:
- Get stakeholder buy-in from all end-users (sales, marketing, content, designers) to understand what kind of content they create and any specific channel needs (e.g., unique fields needed for video pages).
- Make content types as reusable as possible, rather than creating new content types for small variations. When editors use Contentful, the choice in content type should be obvious, with fields that are clear and easy to use.
- Avoid deeply nested references and keep content models flat where possible.
- Consider content relationships carefully, as too many references can make maintenance more challenging.
- Do not use the website taxonomy as a guide for content types, as many pages in a website can use the same content type (e.g., a landing page, webinar sign-up, and contact form could all use the same structured content type).
- Use descriptive field names and enforce consistent naming conventions.
- Use meaningful IDs and slugs to minimize the future need for changes.
- Leverage reusable components for common content patterns rather than duplicating fields across content types.
- Build for scale, ensuring you have set up a content model that can support future localization or channel needs. Even if you don’t think you need it now, it’s ideal to plan for localization from the start.
- Limit custom validations to essential business rules only.
- Plan for change, as the content model is unlikely to be perfect on the first attempt.
Rather than reading all the articles, taking the Contentful ‘Content Modeling’ course, or working with generic tips (yes, even these), we suggest working with an experienced Contentful partner who understands the platform, has experience working with complex content models, and has seen both the good and bad of content models to set you up for success.
Skip the complexity and hire a global expert and certified Contentful partner.
Read MoreHow an Incorrect Data Model Impeded Marketing Agility for a Global Fintech Firm
A fintech organization specializing in crypto and advanced trading came to us recently to optimize their Contentful implementation. Global content teams continued to rely on developers to publish or update landing pages or product pages—at scale, this created issues for editorial teams creating multi-channel content across 70 countries.
A Contentful content model is intended to support all the kinds of content editorial teams want to create, but our client’s content model was missing crucial data types. Further, the database layout was not optimized to support Contentful, resulting in poor page performance.
Net Solutions worked with the client to revise the content model and to ensure each content type contained the appropriate structure and fields to support editorial teams and page performance. Read how here.
Problem #4 – Lack of Platform Expertise
Contentful is a robust CMS, but it can be a big shift for developers used to working with a traditional CMS platform. Beyond the monumental shift to headless architecture and all that entails, Contentful’s API-first approach, the Contentful CLI (command line interface), and its wide range of SDKs (software development kits) can be overwhelming for new users—even experienced developers. However, other platform features need to be navigated.
Contentful APIs
Developers working with Contentful need to be familiar with front-end development and able to navigate how Contentful has designed its APIs to manage different types of content or perform different actions. Contentful APIs are all based on REST and GraphQL, including:
- Content Delivery API (CDA) – Retrieves content to display.
- Content Management API – Creates or updates content (see App SDK).
- Content Preview API (CPA) – Retrieves unpublished content.
- Images API – Retrieves and/or transforms images.
- GraphQL Content API – Retrieves published and unpublished content using GraphQL.
- User Management API – Manages users.
- SCIM API – Manages memberships and teams.
- Sync API – Keeps a local copy of content up to date via delta updates.
Take the time to become familiar with each API in a testing environment, as how you use each API and how you set up caching for the APIs can have an impact on performance.
Webhooks
Important: Contentful pricing tiers limit API calls per month. Webhook misconfigurations can negatively impact Contentful costs.
Webhooks are used to notify when data in Contentful has changed, crucial for displaying the most recent content to end users and for integrating with other services. Contentful’s marketplace is full of helpful Webhook Templates you can use to get started, but it’s common to see webhooks configured incorrectly, triggering unnecessary builds, performance issues, or over-using API resources.
Some best practices include:
- Use tools and/or automated alerts to review webhook responses and errors to help identify and correct performance issues, timeouts, and other failures.
- For security, set up webhook request verification in Contentful and/or using the Content Management API.
- Use a backoff strategy to reduce API calls if a webhook fails.
- Only use webhooks for simple triggers such as content publication or asset-related events like uploads, deletions, or transformations. For example, using webhooks to track changes in content relationships and references. When content entries referenced by other content entries are modified, the webhook should trigger updates to all dependent content.
Contentful also offers a more straightforward way to manage events using the Contentful App Framework.
Workflows
The Contentful Workflows app (Premium plans only) enables developers to set up processes to support collaboration, editing, reviews, and approvals based upon clear roles and responsibilities, with notifications sent to either email and/or Slack. You can set up multiple workflows to run in parallel, but this can get complex, so it’s critical to involve stakeholders (editorial, design, legal, etc.) to vet each review process’s steps.
Problem #5 – High Learning Curve for End Users
40% of users highlighted difficulties in navigating Contentful’s features.
The learning curve can be high for content teams (Marketing, eCommerce, or Sales), causing delays in getting teams and projects moving quickly in the new platform. In the initial days or weeks, this could cause campaign delays and frustration.
In order to reduce this friction, ensure you have set up your users for success, ensuring:
- Appropriate user roles and permissions are set.
- Approval workflows follow a pre-defined editorial path.
- All existing channels are supported.
- Content editor workflows have been tested to ensure they work correctly and are easy to understand (ideally tested by your Content Champion, the stakeholder most involved in working with your IT team).
Change Management Best Practices
Change management efforts include creating training materials and hosting workshops, with at least one “champion” within the organization to drum up excitement and work directly on change efforts. The ideal champion(s) are managers or those who work directly as part of the content team. While Contentful offers many helpful videos in its Learning Center, the most effective training will focus on your specific implementation, highlighting:
- How to navigate Contentful’s interface
- When and how to use each content type
- An introduction to fields (as users are used to a WYSIWYG interface)
- How and where to upload new multimedia
- How to push content to different channels
- An introduction to collaboration and governance, specifically @mentions and any review workflows
Tools to Support Migrating to Contentful
To ensure a successful migration to Contentful CMS, several essential tools can facilitate the process. Here’s a list of key tools and their purposes:
- Contentful Migration CLI
- Data Extraction Tools
- Transformation and Loading (ETL) Tools
- Quality Assurance (QA) Testing Tools
- Version Control Systems
- Project Management Tools
- Web Crawlers
- SEO Optimization Tools
- Monitoring and Analytics Tools
By leveraging these essential tools, organizations can enhance their migration experience to Contentful CMS, ensuring a smooth transition that minimizes disruption while maximizing content management capabilities.
Measuring the Success of Your Migration and Next Steps
After successfully migrating to Contentful, merchants can now realize the flexibility to more easily adapt to market changes, scale content operations, and deliver exceptional digital experiences.
After migration, it is critical to re-measure against the benchmark data to ensure KPIs are being met and to set up regular intervals to optimize content models and monitor performance, security, SEO, and user experience.
How Net Solutions Can Help
While migrating to Contentful can be complex, particularly if you are dealing with a legacy CMS or with a large and complex website, the right planning, tools, and training can overcome these hurdles.
Once successfully implemented, Contentful’s modular, headless architecture empowers eCommerce and marketing directors to respond rapidly to new trends, streamline content workflows, and maintain a consistent brand presence across all channels with minimal use of development resources.
Net Solutions is a proud Contentful partner, offering full-service development and design support to help you plan and execute your migration, design your architecture and integrations, and optimize your implementation to support all stakeholders.
