Understanding the Impact of Changes to your CMS Architecture

Once an Agility website has launched, its really just the starting point to the customer's digital experience. Over the course of time it is expected there will be numerous updates to content definitions/schemas and the website code base itself. This guide's purpose is to walk developers and architects through this process using Agility's established best practices.

Environments

It is important to note that due to the decoupled nature of the CMS and your website, you can have as many website environments as you see fit. For example, a typical setup will involve having a local development website environment, a uat/staging website environment as well as a production website environment. This allows you to develop locally, and test and review code updates in uat/staging prior to deploying your code to production.

While you can have multiple website environments, there is only one Agility CMS instance that houses your configuration settings and content. Therefore, care must be taken to ensure that any breaking changes in the CMS are not synchronized to the production website environment until they have been tested on the staging/uat website environment.

Changes that Require Publishing to be Synchronized with Web Servers

When making changes in the CMS, the following types of changes are synchronized with your list of syncing web servers upon being published:

• Pages 
• Modules 
• Shared Content Lists
• Shared Content Items
• Nested/Linked Content Lists
• Nested/Linked Content Items 
• Module Definitions
• Inline Code

Changes that are Synchronized Immediately with Web Servers

When making change sin the CMS, the following types of changes are synchronized with your list of syncing web servers immediately after saving a change:

• Content:
  • Updates to Image Galleries
  • Modifying the default sort settings of a list
•  Settings:
  • Global Content
    • Global Scripts
      • Top Scripts
      • Bottom Scripts
    • Tag Defintions
    • URL Redirections
  • Customization/Development
    • Development Framework
    • Content Editor
    • Page Templates
      • Creating a new page template
      • Deleting a page template
      • Modifying content zones
      • Modifying output template
  • Site Configuration
    • Caching
    • Domain Configuration
    • External File Storage
    • User Agents
    • Languages
  • Content Manager
    • Global Configuration

When making changes that will sync immediately to your production environment, you need to evaluate the impact this will have. You can temporarily deactivate the content sync to your production web server in order to test on your uat/staging web server. When in doubt, email support@agilitycms.com and we'll be happy to assist.

Potential Breaking Changes

A breaking change can be described as a type of change to core architecture that you make within your CMS instance that has the potential to cause an application error or unintended change of functionality in production. Errors can occur if a potential breaking change is made within the CMS by you, and is synchronized to the production web sever without proper testing.

The following types of changes you can make in the CMS are examples that are known to have the potential to be a breaking change:

• Removing a field from a Module or Content Definition - This can result in production code trying to access the field and getting a NULL value on any NEW content that has been created using the definition. Existing values for that field will remain intact. If you add the field back, existing values will remain available as well and continue to function as it did before.

• Changing the Field Type of an existing field in a Module or Content Definition - This can change the expected format of data as it is deserialized.

• Changing the Field Name of an existing field in a Module or Content Definition - Similar to removing a field, this can result in production code trying to access the field by a different name and resulting in a NULL value.

• Changing the Output Template of a Module Definition or Page Template - This can cause the production website to attempt to execute code that has not yet been deployed causing an application error.

• Disabling any UGC features such as Comments, Voting, Likes, Approve/Disapprove, or Ratings from any Content or Module Definition - This can result in UGC reference names being NULL and can cause existing production UGC functionality to fail.

• Deleting a Shared Content Item or a Shared Content List - Deleting a Shared Content Item (not an item within a list) or a Shared Content List can result in production code trying to reference this item/list by reference name and getting a NULL value in return.

• Moving or Renaming the path for a Dynamic Page - Dynamic page routes are often referenced by static paths in the application to produce fully qualified URLs. Modifying the path in the CMS could cause static paths to result in a 404.

• Removing or Renaming a Language Code - Any changes to an existing language code will require a full re-sync to all web servers.

• Changes to the Development Framework Settings - Any changes to include/exclude the language code in the URL, or updating the framework language will synchronize immediately to all web servers. Updates to these settings should be conducted carefully, and we recommend deactivating the content sync  production syncing web server so the change can be tested on the stage/uat environment prior to syncing to the production web server.

• Renaming or Removing a Content Zone within a Page Template - This can cause the production web server to attempt to render a content zone that does not exist anymore by the reference name causing ALL modules within that content zone to fail rendering.

It is best practice to avoid introducing unnecessary potential breaking changes. In most cases, this means creating a new Module/Content/Page Template definition if you have major changes, or creating a new field as opposed to modifying an existing one.