Note: Legacy relationship fields have been deprecated for years, and are approaching end of life; forthcoming content-editing features will not support legacy relationship fields whatsoever. dotCMS recommends legacy relationship field users transition to standard relationship fields, as described below, by the end of 2024.
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 through the following documentation:
- Relationships
- Pulling Related Content
- Importing Related Content
- How to Relate Content
- What to Know before Push Publishing Related Content
Migrating a Legacy Relationship
Note: If you migrate your Legacy Relationships at different times, you need to perform steps 1 and 2 each time you perform a conversion. If you migrate multiple Legacy Relationships at the same time, you only need to perform steps 1 and 2 once before performing multiple conversions.
1. Write down the name of the Legacy Relationship
You will need this name to find and update your code (please see step 4, below).
2. Delete all old Bundles
Delete all old Bundles in all three tabs in the Publishing Queue Tool:
- Pending
- Status / History
- Bundles
Failure to delete these Bundles could result in old versions of the Legacy relationships coming back after the Relationships have been upgraded.
Important: If you have one or more Push Publishing environments configured, you must delete old bundles on all senders and all receivers.
3. Clear the cache
- Open the System -> Maintenance Tool.
- Select the Cache tab.
- In the Action field, select All Caches.
- Press the Flush button.
Important: If you have one or more Push Publishing environments configured, you must clear the cache on all senders and all receivers.
4. Migrate the Legacy Relationship
A. Open the Content Model -> Content Types Tool.
B. Click on one of the Content Types containing the Legacy Relationship to convert, to edit the Content Type.
C. Select the Relationships tab
D. Click the Edit icon next to the legacy relationship that you'd like to migrate.
E. Click the CONVERT TO RELATIONSHIP FIELD button.
F. Read the warning message carefully.
- Front end pages and API calls that relied on the old relationship will need to be updated in order to display the related data.
- Your existing content pulls will fail as soon as you convert the Relationship, and you will need to update your code before it will work again.
G. Review both Content Types.
- After migrating the legacy relationship, a new Relationships Field will be added to both of the Content Types that were part of the previous Legacy Relationship.
- All previous relations between content items that existed in the Legacy Relationship will now appear instead in the Relationship Fields.
- The previous Legacy Relationship will be deleted, and will no longer appear in the Relationships tab for either Content Type.
- You may wish to rearrange the new Relationship Fields in each Content Type, to make them easily accessible by your content creators.
5. Update all old references to the Legacy Relationship
Find and update all references to the old Legacy Relationship. This will primarily involve uses of the $dotcontent.pullRelated() Velocity method which reference the now-deleted Legacy Relationship, but may include some other references (such as references in REST API calls).
You can search for files and widgets within dotCMS that reference the old Legacy Relationship by using a Lucene Query similar to the following in the Query Tool:
+catchall:legacyRelationship-Name
where you replace legacyRelationshipName with the name of the Legacy Relationship you wrote down in step 1.
