Content Type Change Management

If you have created (and published) entries using a content type, making changes to the content type schema may result in data loss of existing entries.

There are, however, specific guidelines, following which you can make changes to the content type without losing any data or impacting the content of your live site or app.

Note: Updates made to the content type schema will reflect on all the published entries of the content type in any environment.

In this document, we will discuss the various types of changes you can possibly make to a content type schema (listed below), and the guidelines you need to follow to make such changes safely.

• Add a new field to an existing content type
• Edit an existing field of an existing content type
• Delete an existing field of an existing content type
• Make multiple (and major) changes in the content type schema
  

To understand these scenarios, we will consider an example. You have a content type named Product, and there are several fields within the Product content type:

• Name: Single Line Textbox (String data type)
• Price: Single Line Textbox (String data type)
• Description: Rich Text Editor (String data type) for displaying product’s description

You have created and published multiple entries for the “Product” content type. Now let’s look at the changes that you want to perform and the steps to be followed to perform the changes.

Add a new field to an existing content type

There is no data loss when adding a new field since you are not modifying or deleting any existing fields with data.

You want to add a Manufacturer (Single line textbox) field to the Product content type. To do this, perform the following steps:

1. Edit the content type
   Go to the stack and edit the Product content type.
2. Add the new field
   Click on the “Insert a field” (“+”) button and select “Single Line Textbox”.
3. Publish entries on staging
   Edit all existing entries and add data in the new field. Then, save these entries and publish them on staging.
4. Make changes to UI code
   To display the content of this field, add the UID of this new field to your UI code. Push the changes on staging and check if it fetches the content of the new field.
5. Publish/push on production
   If everything is working as expected on staging, publish the entries and push the code on production.

Edit an existing field in an existing content type

When you edit a field in an existing field of an existing content type, there is a possibility of data loss.

For example, if you want to change the data type of Price from string to number, all the data that exists within the Price (String data type) field will be lost.

Being cautious and following the steps below will help you preserve the data while editing a field.

1. Add a new field
   Edit the Product content type and add a new field: Price_new. Now you have a Price field and a Price_new field in your content type.
2. Edit entries
   Manually edit all the existing entries, and enter new data in the Price_new field. Keep the data of the Price field as-is.
3. Publish entries
   Publish these entries on the staging environment to ensure mapping is successful.
4. Make changes to UI code
   Now, replace the price UID with price_new UID in your presentation code. This will ensure that your site/app fetches the new field’s content.
5. Test and publish
   Deploy the code on staging, to check if your site/app fetches the new data. If everything seems proper, first publish the entries on production and then deploy the code on production.
6. Delete the old field
   Once you have ensured that everything is working fine, delete the Price field from your content type and you are done.

Delete a field from a content type

When you delete a field from an existing content type, the data of that field will be lost temporarily (it can be restored).
For example, let’s consider you want to delete the “Description” field from the “Product” content type.

The following steps will help you achieve these goals.

1. Make changes to UI code
   If you have used the description UID anywhere in your code, remove it, and push the changes on the staging environment.
2. Delete the field
   Edit the Product content type, and delete the Description field.
3. Publish entries
   After making changes to the content type, you will notice that the field no longer exists in your existing entries. Save these entries and publish them again on staging.
4. Test on staging
   Check if everything is working as expected on the staging environment.
5. Publish/push on production
   If everything is working as expected on your staging site, publish the entries and push the code on your production environment.

Restore content of the deleted field

If you accidentally delete a field along with its data from an existing content type and you want to restore the field along with the data, you will be able to do so. For example, if you delete the Price field from the “Product” content type, all data for the Price field will be lost temporarily.

You can restore the field and its data using two methods, either through UI or through API.

Restore content through UI

To retrieve the field data using UI, perform the steps given below:

1. Add the deleted field to the content type
   Edit the content type and add the deleted field. Now, make sure you enter the actual UID of the field or else you will not be able to retrieve the data. If you are not sure of the deleted field's UID, go for the API method.
2. Retrieve the required version of the entries
   You can compare the versions of an entry to see which version of the specific entry contains the data for the updated field. (You need to do this for all the entries of the content type.)
3. Save the entry to make it the latest version
   When you retrieve the required entry version, open and save it to make this version the latest one. (You need to do this for all the entries of the content type.)

Restore content through API

To retrieve the field data using API, perform the steps given below:

1. Find the version of the content type that includes the field
   Retrieve the current version of the content type using the Get a single content type API Request (you will find the version number in the Response body.) Then, using the same API Request and the version parameter, find the content type version that contains the deleted field in the schema.
2. Restore the content type version that contains the field
   Copy the Response body of the content type schema that includes the deleted field. Remove all parameters except title, uid, schema, and options. Use the Update Content Type API Request and pass this updated schema in the Request body.
3. Retrieve the entries (Use the version API to retrieve the latest version of the entry)
   Use the Get a single entry API Request and query the latest version of the entry. If you do not find it in the latest version, try querying previous versions that contained the data of the deleted field. (You need to do this for all the entries of the content type.)
4. Update the entries
   Copy the Response body of the required entry version from the above request and use the Update an entry API Request to update the entry. (You need to do this for all the entries of the content type.)

Make major changes to the schema of a content type

If you plan to make major changes to the schema of a content type, follow the steps given below to ensure there is no data loss.

1. Create a copy of the content type
   
   Copy and create a content type which will be the replica of the content type you want to edit.
2. Edit the schema
   Make changes (add or remove fields) to this new content type.
3. Create entries
   Now, create new entries for this content type. Publish these entries on staging.
4. Make changes to UI code
   In your presentation code, use the UIDs of the fields of the new content type. This will ensure that your site/app refers to the new fields instead of the old fields.
5. Test on staging
   To check if the data has been mapped correctly, push the UI code on your staging environment. Confirm if it is good to go live.
6. Publish/push on production
   Once everything is working fine on staging, push the entries and push the code on production.
7. Delete old content type
   You can now safely delete the old content type.