Publishing a page with a module who's definition is not published will cause a Sync Error. This is by far the most common sync issue that customers experience and it is easily avoidable.
The Agility Content Server will prevent any publishing of a page and it's module from syncing until the module definition in question has been published.
This article will explain why this happens, how you can resolve it, and how you can prevent this sync error from occurring in the future.
Why does Agility require you to Publish your Module Definitions?
Given the decoupled nature of the CMS and your website, modules are defined in the cloud which require updating content schemas (i.e. the fields within your module input form). These schemas are ultimately synchronized down to your web servers just like content.
The problem this introduces is that a developer could do something like remove a field from a module definition that is currently being used in production. If this schema change were to take effect immediately and pushed the the production web server - this could cause an application error when trying to access a field that no longer exists.
To help solve this problem and minimize risk, whenever you make a potential "breaking" change to a module definition, Agility will place the module definition in staging mode. While the module definition is in staging mode, and attempts to publish modules or pages that have modules that link to this definition will fail. They will fail until the module definition is published.
A developer should only publish a module definition when they are sure it will not cause any issues in production.
What Constitutes a potential Breaking Change to a Module Definition?
- Changing the Output Template
- Removing an existing field
- Changing the Field Type of an existing field
- Changing the Field Name of an existing field
- Disabling any UGC features such as Comments, Voting, Likes, Approve/Disapprove, or Ratings
What are Safe Changes to a Module Definition?
- Adding a new Field
- Updating the extended properties of a Field (such as Validation, Language Properties, Access etc.)
- Updating the Description of a Field
- Updating the Description of the Module
- Updating the Title of the Module
- Updating the Hidden value of the Module (i.e. allow editors to add it to a page or not)
- Editing Custom Scripts used in the Agility input form
How can you Test/Preview your Module Definition before Publishing it?
Testing your module definition is just like testing content - you should preview your page/module on your website prior to publishing it.
This means locating a page that has an instance of this module on it and clicking Preview from the action bar to launch a new window in Preview Mode. When the website is in preview, the latest module definition schema will be pulled down from the cloud and used instead of the last synced/published version.
In Preview, you will be able to inspect the module's functionality and test for any breaking changes.
If you do find that a recent update has introduced a breaking change, you have two options on how to proceed:
- Revert the breaking changes to the module definition by 'undoing' the changes.
- Deploy an update to the code base that resolves the breaking changes.
Testing Module Definition Updates with Live Content (Not Preview)
There are some cases where testing a module definition update in Preview Mode is not sufficient. This may be because there are other pieces of associated content that is not published yet. For example, the module may work fine in Preview, but on Live it is trying to access an item from Shared Content that is not yet published and remains in staging mode. This could result the Live website throwing an application error - until you publish the associated Shared Content it is trying to access.
One way to thoroughly test your module definition update with Live content is to temporarily deactivate your production syncing web server. Deactivating your production syncing web server simply prevents ANY publishes/syncs from occurring in your production environment. This allows you to publish any type of content or module definition to your stage/uat environment for review, prior to having that sync to to your live website.
Once you've confirmed on your stage/uat environment that all published content and definitions are working as expected, you can then proceed to reactivate the production syncing web server. Setting the web server to active will sync all pending updates to that web server since it was deactivated.
Publishing a Module Definition
Once you are certain there aren't any breaking changes to a module definition in production, you may publish the module definition.
Publishing the module definition can be done by navigating to Settings > Module Definitions, then selecting the appropriate module definition(s) and clicking on the Publish button.
Help! Module Definition has been Published, but still getting Sync Errors!
Once a module definition has been published, any pending syncs on modules that use that definition will be allowed to sync and should complete successfully. However, as of July 2018, there is a known bug which will prevent any pages that were attempted to be published that have the affected module on the page will need to be manually re-published. This can be accomplished by finding the pages in Agility in the page tree and publishing them again. To find the 'list' of affected pages you need to re-publish you can view the Detailed Sync Status Report found in Reports > Detailed Sync Status.
Below is an example of this report, highlighting a page that must be manually re-published again:
How to Avoid Issues with Unpublished Module Definitions
To avoid sync errors and minimize impact, risk and testing, it is recommended to avoid introducing breaking changes to a module definition. See breaking changes for more details.
If you avoid breaking changes altogether, you can immediately publish the module definition after making a safe change and it will not affect the functionality of the live website.
If you must perform a breaking change (i.e. the removal of a field), then you have two options on how to proceed:
- Ensure that you thoroughly test your code base on all environments prior to syncing the new module definition schema
- Make a copy of the existing module definition and make all updates in the copied module definition
Comments
Please sign in to leave a comment.