Upgrade your Content Fragments for UUID References

Last update: November 21, 2024

CREATED FOR:

  • Admin
  • Developer
IMPORTANT
Various features of the GraphQL API for use with Content Fragments are available through the Early Adopter Program.
To see the status, and how to apply if you are interested, check the Release Notes.

To optimize the stability of your GraphQL filters, you can upgrade the content and fragment references in your Content Fragments so that they use universally unique identifiers (UUID).

Originally Content Fragment Models provided the data types of Content Reference and Fragment Reference. Both of these references use a path to point to the referenced resource, and this path can become outdated if the resource is moved. Although such references are more than sufficient in most scenarios, Content Fragment Models have been extended to also provide references based on a UUID:

  • Content Reference (UUID)
  • Fragment Reference (UUID).

These new reference types can be used both in new Content Fragment Models and Fragments, and to extend existing instances.

To upgrade existing Content Fragments and Models, you can run the procedure documented here.

CAUTION
Before running the upgrade procedure you should always Execute a dry run to highlight any potential issues with your content.

What is upgraded

The following updates are made:

  • Fields of the data types:

    • Content Reference are converted to Content Reference (UUID)
    • Fragment Reference are converted to Fragment Reference (UUID)

  • The values of the path based references held in these fields are replaced by the corresponding UUIDs

NOTE
After the upgrade both Data Types are still available in the Content Fragment Model editor. You can create new fields based on both types (though it is anticipated that you will use the UUID based types) and rerun the upgrade if required.

What is NOT upgraded

The following references are not upgraded:

  • Page references - UUIDs are not supported yet

  • Any invalid references; for example, where the target of the Content Fragment path, or Asset path, does not exist

    • Invalid references are not upgraded, as if the Content Fragment path, or Asset path, is invalid there is not a corresponding UUID to assign. The original reference remains untouched.

    • Use a dry run to detact any invalid references.

    NOTE
    Being invalid, they are not usable, irrespective of the upgrade.

When you should not upgrade

Do not upgrade:

  • When any of your Content Fragments use page references; as UUIDs are yet not supported for page references

Limitations of UUID references

Currently the following limitations apply when using references based on a UUID:

  • Models

    • New Content Fragment Models with either Content Fragment UUID or Content Reference UUID fields cannot be created via OpenAPI.
    • The id field for models has not been changed to be UUID based. It uses the base64 decoded path of the model. Models cannot be moved, therefore, this value is still stable.

  • Assets

    • When creating a Content Fragment via OpenAPI,fragment-reference or content-reference field types must be used for specifying references to a fragment or an asset respectively - even when setting the value of a UUID based reference field.

Upgrade Planning

There are a few preparation steps before running your upgrade.

Execute a dry run

It is recommended that every time you upgrade your content, you first perform a dry run. This will create log files with entries that highlight any potential issues:

  • Invalid references
  • Page references

Run the content upgrade in dryRun mode to:

  • identify any invalid references; by listing them in the log files
    You can then fix these references, before running the actual content upgrade.
  • identify any page references; by listing them in the log files
    When page references are detected you should not run the content upgrade.