Was this page helpful?

Upgrade to customizable Compose content model

Table of contents

What is the customizable Compose content model?

The customizable content model of Compose gives you full flexibility to use any content model with Compose and works great with existing spaces that have been developed without adhering to the content model requirements of the legacy Compose content model.

To learn more about the benefits of the customizable Compose content model, refer to Customizable Compose content model.

Goal of this guide

The goal of this guide is to instruct you on how to upgrade from legacy to customizable Compose content model in an environment with existing content, including updating the content model, migrating the content, making changes to your website code and the space settings.

Who should upgrade?

This guide is only relevant for you if you have set up Compose in your space between March 2021 and April 21st 2022 using the legacy Compose content model.

Follow the instructions in this guide if you are using the legacy Compose content model in your environment with existing content and would like to switch to using the customizable Compose content model in that environment.

Since it is possible to extend the legacy content model of Compose with custom fields, we can’t guarantee that every content model can be easily upgraded. However, the best practices laid out in this guide should make the process smooth for the vast majority of Contentful customers.

Is upgrading required?

Compose supports both legacy and customizable content models.

Upgrading to the customizable Compose content model is totally optional. You can continue working with the legacy Compose content model if you prefer.

However, some future improvements for Compose may only be supported by the customizable content model due to technical reasons. Also, installing the legacy Compose content model in a newly added space is not supported.

In case support for the legacy Compose content model will be phased out in the future, we will give you enough time and tooling support to make the upgrade as frictionless as possible.

For the successful upgrade, we recommend that additionally to this guide you read the following documents:

  • Page types and legacy page types — Learn about the underlying content types of pages in Compose with customizable and legacy content models.
  • Aggregates — Learn how boundaries of a page are defined.
  • CMS as Code — Learn about CMS as code approach and how Contentful helps implement it.
  • Contentful CLI — Learn how to work with Contentful CLI.
  • Content Management API — Technical reference for content management API.

Overview of steps

Upgrading to customizable Compose content model is accomplished by going through the following major steps:

Step 1. Prepare for the upgrade — Create a dedicated environment for the upgrade and a backup copy of your content.

Step 2. Upgrade to the customizable Compose content model — Make changes to your content model and migrate the content.

Step 3. Update your space settings — Ensure your space settings are aligned with changes to the content model.

Step 4. Make changes to your website code — Update the code of your website to make API calls to load and render web pages based on the new customizable Compose content model.

Step 5. Move your changes to production — Apply the new content model to the production environment and deploy the updated code.

Step 1: Prepare for the upgrade

Create dedicated environment

We strongly recommend you to perform the Compose upgrading in a dedicated environment to ensure that your production content is not affected while you iterate on the migration and work towards the upgrade.

To set up a dedicated environment, clone the environment in which you use the legacy Compose content model.

Back up your content

Create a backup copy of your content to ensure you don’t lose anything during the upgrade.

We recommend doing the following kinds of backup:

  • Set up a backup environment — Create a backup environment (for example, “backup-master-compose-upgrade”) and clone your existing “master” environment into it. Don’t make any changes to the backup environment.

  • Export your content using our export tool — Save a copy of your current “master” environment on your local machine by exporting your content with Contentful CLI.

Step 2: Upgrade to the customizable Compose content model

Legacy vs Customizable Compose content model

The goal of the upgrade is to transform your legacy Compose content model into the customizable Compose content model.

The table below displays the structures of legacy and customizable Compose content models and explains the difference between them. The image and comments under the “Legacy Compose content model” refer to the Compose content model before the upgrade, and the image and comments under the “Customizable Compose content model” describe the content model you receive as a result of the upgrade.

Legacy Compose content model Customizable Compose content model
Legacy Compose content model Customizable Compose content model
  • A legacy Compose content model consists of “Compose: Page” parent content type and nested content types “Compose: SEO” and a page type.
  • A page type is a custom content type that defines how your page in legacy Compose looks (e.g. “Landing page”).
  • A page type and “Compose: SEO” are referenced under the tabs “Content” and “Page Settings” in the legacy Compose page.
  • The content model is based on a single content type called a page type.
  • The fields from “Compose: Page” content type are moved to the page type.
  • All fields are organized under the “Content” tab.
  • The “Compose: SEO” content type is referenced under the “SEO” field.

Rebuild your content model

Even though all the steps below can be done manually, we strongly recommend programmatically migrating your content types and content by writing your own migration scripts. Due to the special nature of this migration we recommend using contentful-management.js instead of the contentful-migration library.

To rebuild your legacy Compose content model, perform the following steps:

Update the page types

The following steps need to be performed for all of your existing page types.

To update a page type:

Compose upgrade 701

  1. Duplicate the fields from the “Compose: Page” content type to the page type content type:

Update each content type that you currently use in Compose as a page type by adding all the fields from “Compose: Page” to it.

Keep in mind to correctly duplicate localization settings, validations and the appearance of each field.
You might run into a situation where you are about to create a field with an ID that is already present on the page type itself (e.g. you already added a “Title” field on the page type). To make an informed decision on which of the fields (or both of them) to keep and how to migrate their content, take into consideration your content model and what kind of data those fields contain.

Compose upgrade 702

  1. Add the “Aggregate Root” annotation to the page type:

For Compose to recognize your page types, assign the “Aggregate Root” annotation to each content type that represents a page type in your content model.

  1. Activate the page type:

Activate your content type via the corresponding API calls.

Compose upgrade 703

  1. Copy content from “Compose: Page” into duplicated fields of the page type:

Go through all entries of “Compose: Page” and move the values from the fields you duplicated in step one to the respective page type entry. In our example, the values from the “Page title”, “Slug” and “SEO Metadata” fields are copied from the parent “Compose: Page” entry to the target “Landing page” entry.

For referenced fields, copy the references. For example, in the “SEO Metadata” field of “Compose: Page” copy the referenced entry “SEO Metadata” and move it to the respective “SEO Metadata” field of the target “Landing page” entry.

Update the content types

The following steps need to be performed on every content type except “Compose: Page”.

Compose upgrade 704

  1. Replace “Composition relationship” setting with an “Aggregate Component” annotation:

Check all your reference fields to find the ones that have the “Composition relationship” setting enabled and assign an “Aggregate Component” annotation to them.

Read about page components here.

Compose upgrade 706

  1. Replace validations that restrict linking to “Compose: Page”:

Check the validations for single reference, multi reference and Rich Text fields. If any of those fields is restricted to link to the “Compose: Page” content type, replace that validation to allow entries to link to every page type (e.g. “Landing page” and “Help center article”) instead.

Pay extra attention to Rich Text fields as they might have multiple validations—one for every way of linking entries into the Rich Text.
  1. Update and activate the content type:

Update and activate your content type via the corresponding API calls.

Update the entries

The following steps need to be performed on every entry except the ones that are of the content type “Compose: Page” and the ones that are archived.

Compose upgrade 705

  1. Update references linking to a “Compose: Page” entry:

In the entries, replace references to the entries “Compose: Page” with the references to the relevant page types.

You can find the relevant page type linked in the “Content” field of the “Compose: Page” entry.
Be sure to look at all single reference, multi reference and Rich Text fields of all entries. Also, ensure to cover all the locales of these fields in case that field is localized.
  1. Publish entry:

After going through all the fields of an entry that need to be updated, publish the entry to apply the changes.

Test the migrated content in Compose

After rebuilding your content model to support customizable Compose and completing the content migration, you can view and manage pages within Compose.

Before moving to the next steps of updating the space settings and adjusting your website code, manually verify if the content migration was successful by reviewing your pages in Compose against the checklist below:

  • Are all pages visible in Compose?
  • Are all page types available in Compose?
  • Does each page type have the right amount of pages?
  • Are the page and SEO settings correctly migrated and contain the expected values?
  • Is the content of the pages correct and complete?
  • Are references and links between entries and assets correct?
  • Have all content type customizations been migrated?
  • In the reference fields, have all “Composition relationship” settings been replaced with “Aggregate Component” annotations?
  • In the reference fields, have all links to “Compose: Page” been replaced with links to relevant page types?

In case you detect any errors, you can either manually correct them or adjust your migration scripts and re-run the migration in a new environment.

Delete “Compose: Page” content type and its entries

  1. Delete “Compose: Page” entries:

After updating the entries as described in Update the entries, delete the entries of “Compose: Page”.

To delete the entries, first unpublish them.
Keep in mind that it is required to delete the entries, and not archive them. Archiving will block you from deleting the “Compose: Page” content type in the next step.
  1. Delete “Compose: Page” content type:

Delete the “Compose: Page” content type from your environment.

Optional: Create tabs for a page type

After the process of rebuilding your content model is finished, the fields in your page types will be displayed under a single “Content” tab in the Compose page editor. To add more tabs and move your fields between them, group your fields as described in Set up field groups.

Step 3: Update your space settings

Revise the space settings that are affected by the content model changes as follows:

  • Revisit your webhooks — Make sure your automations are configured to listen to events for page types instead of the legacy “Compose: Page” content type. It may affect any automations or integrations (e.g., your build process, search indexing) if you don’t.
  • Edit custom roles — Update your existing custom roles that were set up for the legacy Compose content model to work with the customizable Compose content model following the instructions in Roles and Permissions for Compose.
  • Reconfigure the website previews for each page type to enable the editors to preview content changes within Compose.

Step 4: Make changes to your website code

Update your API request code

After your Compose content model is upgraded, it is necessary to update code in your frontend applications to load and render Compose pages.

In your code, you most likely have functionality to resolve URLs using slug fields on your legacy page types which triggers API calls to Contentful to load the requested page data. In this stage, you need to adjust the existing API calls to the top-level “Compose: Page” content type to query the newly migrated Compose page types instead.

Let’s consider an example where a page of a page type called “Landing page” is queried. With legacy Compose content model, a query to the REST API looks as follows:

  limit: 1,
  include: 10,
  'fields.slug': ‘my-homepage-slug’, // the slug of the requested page
  content_type: ‘page’, // query on “Compose: Page” content type
  'fields.content.sys.contentType.sys.id': ‘landing_page’, // the page type of the referenced page needs to be a “Landing page”

With customizable Compose content model, a call to the REST API looks as follows:

  limit: 1,
  include: 10,
  'fields.slug': ‘my-homepage-slug’, // the slug of the requested page
  page_type: ‘landing_page’, // query on “Landing page” page type

As you can see, the additional layer for the “Compose: Page” content type is gone and you can query directly the page type you are looking for.

Once the pages load and render, adjust the rendering of page and SEO metadata.

You can see examples of how to load and render web pages in our open source Next.js repo on Github.
Additionally, you might need to revise other parts of your code base that deal with pages: rendering links to pages, website navigation, sitemaps, etc.

Test the code changes on a staging server

After making changes to the website code, verify that your website works as expected according to the following criteria:

  • Are all pages available and rendering correctly?
  • Do links between pages still work?

Step 5: Move your changes to production

We highly recommend having a content freeze (no content created or edited) while bringing changes live, in case any issues occur and your website has to be rolled back to an earlier version.

After testing the content model and website code changes, move your changes to the production environment.

Apply content migration to production environment

Apply the content model updates and the content migration from the dedicated environment that you created for upgrading to the customizable Compose content model to your production environment. We recommend applying your content migration to the production environment according to one of the following ways:

  • Use environment aliases to switch to your production environment.

  • Apply all migration scripts to your production environment.

Before applying the migration scripts to the production environment, make sure to create a backup environment.
You can find more details for both approaches in our tutorial on deploying changes with environment aliases.

Deploy the updated version of the website

After the content model updates and content migration are applied to your production environment, deploy your website code changes to your production server.

We recommend orchestrating your deployment using a CI/CD pipeline to minimize potential downtime.

Once deployed, do a last round of testing to check if your website works as expected.