Migrating Legacy Relationships documentation for the dotCMS Content Management System

As of the dotCMS 5.1 version, relationships have become more powerful through the use of one-sided relationship fields. However, legacy relationships require manual migration by editing the content type for EACH relationship. This documentation shows how to migrate legacy relationships and create new relationship fields automatically. There are several advantages to *migrating old relationships to the new relationsip fields:

  • relationship fields can be managed independently on each Content Type and display only one relationship
  • content can be searched by related content
  • content can be queried and pulled dynamically using the new relationships field(s)
  • relationships can be imported using lists of queries and/or content identifiers


*WARNING: REMOVING OLD RELATIONSHIPS AND MIGRATING TO NEW RELATIONSHIPS WILL REQUIRE REWRITTING FRONT END CONTENT PULLS OF RELATED CONTENT Before migrating relationships, read carefully thru the following documentation:


To migrate legacy relationships, first edit the Content Type (Types & Tags -> Content Types), click on the Relationships tab, and the edit icon next to the legacy relationship that you'd like to migrate.

Editing a Content Type

Click on the “CONVERT TO RELATIONSHIP FIELD” button to convert a legacy relationship.

Editing a Content Type

After clicking the button, read the warning message carefully to make sure you understand that front end pages and API calls that relied on the old relationship will need to be updated in order to display the related data.

Editing a Content Type

After migrating the legacy relationship, a new relationships field will be added to BOTH of the related Content Types.

Editing a Content Type

The new relationship appears on all the contentlets under either Content Type and the field should display existing relationships that were established before the migration. Use the new relationships field by clicking on the “Relate” button to add relationships to new or existing content.

Editing a Content Type