Reference Field Upgradation

On 29th July, 2019, we introduced a new version of the Reference field that provides referencing to multiple content types. For stacks created after 29th July, 2019, you will automatically be using the upgraded Reference field. All previously created stacks will continue referencing a single content type, but you can switch to the new version (and back to the older version) at any time by performing the following steps.

Steps to Upgrade your Reference Field

If your stacks were created before 29th July, 2019, chances are that you are using an older version of the Reference field in your content types. Now, to switch to the new version, perform the following steps and upgrade your old Reference field to the new version.

1. When you create a content type, add the Reference field.
2. Click on the field to edit the field properties.
3. Under Referenced Content Type dropdown, you will find a note and an Upgrade button. Click on it.
   
   
4. You will see a modal with the following message. Click on Upgrade.
   
5. Click on either Save or Save and Close button to save your content type.

Your Reference field will get updated and you will be able to select multiple content types as reference.

Note: When selecting content types, at a time, you can add up to 10 content types as reference into a single Reference field. For more limitations, refer to the Limitations section.

When you create entries for this content type, you will see the new version of Reference field where you can select entries of multiple Content Types as references.

Warning: The upgradation impacts the include referencing of your existing published entries. In the case of all published entries, you need to save them again so that your Reference field format changes to the upgraded format, and then publish these entries again.

Breaking changes in upgraded Reference field

Upgrading your Reference field introduces certain API Changes. The primary change being the input format of your Reference field changes from array of strings to array of objects.

The change in the format of the Reference field is as follows:

{
  ...
    "ref_field": ["blt33a3333333df3c33",...]
  ...
}

{
  ...
    "ref_field": [{
      "uid": "blt1111fe11e111111f",
      "_content_type_uid": "footer"
    },
  ...
}

You can refer to the API Change Log document to know more about it.

SDK

You need to update your SDK versions to the latest one in order to use the multiple content type referencing feature.

DataSync

We have updated DataSync and added support for the new Reference field. You need to update it to the latest version.

Contentstack Express Framework

We have updated Contentstack Express Framework and added support for the new Reference field. You need to update it to the latest version.

Revert to Your Existing Reference Field

To switch back to your older version of Reference field, you need to downgrade it.

Now, to switch to the old version of Reference field, perform the following steps:

1. Open the Content Type Builder page of the content type, and click on the Reference field to edit the field properties.
2. Under Referenced Content Type dropdown, you will find a note and a Revert button. Click on it.
   
3. You will see a modal with the following message. Click on Revert.
   
4. Click on either Save or Save and Close button to save your content type.

Your Reference field will get downgraded and you will be able to select only one content type as reference. Now, when you create entries for the content type, you will see the new version of Referenced field where you can select entries of only a specific content type that has been set as the reference. For more limitations, refer to the Limitations section.

Warning: The degradation impacts the include referencing of your existing published entries. In the case of all published entries, you need to save them again so that your Reference field format changes to the upgraded format, and then publish these entries again

Breaking changes in downgraded Reference field

Now, downgrading your Reference field will revert the introduced API Changes. The primary change being the input format of your Reference field changes from array of objects to array of strings.

The change in the format of the Reference field is as follows:

{
  ...
    "ref_field": [{
      "uid": "blt1137fe73e677645f",
      "_content_type_uid": "footer"
    },
  ...
}

{
  ...
    "ref_field": ["blt33a5572529df8c30"],
  ...
}

You can refer to the API Change Log document to know more about it.

SDK

You do not need to downgrade your SDK versions as they are backward compatible.

DataSync

You do not need to downgrade your DataSync version as they are backward compatible.

Contentstack Express Framework

You do not need to downgrade your Contentstack Express Framework version as they are backward compatible.

Publish entry

After upgrading/downgrading the Reference field, you need to save the entry and then publish it to see the field in action.

Limitations

• The max number of content types that can be added into a single Reference field is 10.
• The max number of entries that can be added in a multiple content type Reference field is 100.
• The "include reference" depth for multiple content type Reference field is 3.