Common reasons of synchronisation failures

A common complain of the users which edit content using the CMS Cockpit is that the synchronisation stops working quite often. During September and October 2015 I solved around 37 cases and found 16 different causes of sync errors. This is a summary of the categories of errors and tips or measures to prevent them.

Hybris usually only reports “An exception occurred during synchronization” in the logs, so you have to further analyse that the cause of the failure is.

• Check the log files. The synchronisation code logs little information but by reading the log you get how the synchronization was triggered.
• Go to Backoffice > System > Types
• Look for the type CatalogVersionSyncCronJob
• Open the type
• Click two times on the arrow on the upper right corner to search instances
• In the field Job select the catalogue which is failing
• Open the last cronjob with has last result error or system error.
• Click on the log tab
• Download and check the last log file if it exists.
• Click on the administration tab
• Download the dump medias
  • The first one contains the list of items which were schedule for the synchronisation
  • The second and last ones have the same information. It is the list of PKs of the items which couldn't be synchronized with the following columns: PK of the source object, PK of the target object and PK of the synctimestamp.
• For each source PK use HAC > Platform > PK Analyser to get its type
• Now the cause of the error in the synchronisation must be found:
  • SQL queries may show rows with nulls on mandatory fields or pks to objects which doesn't exist any more.
  • With SQL you can also check if two components, medias or content slots share the same uid and are on the same catalogue version.
  • The catalogue version of the objects referenced by these items may be wrong
  • There is an old object with the same UID in the online catalog version and they have different types.
  • The SyncJob will only synchronized objects of the types which are in his configuration.

• It can synchronize components with errors like missing values in mandatory fields. It allows the developers to ignore data errors in the CMS catalogue.
• It can end successfully without synchronizing the navigation nodes and entries. The cause of this bug is still unknown.
• The legacy mode is deactivated by default. The setting is called synchronization.legacy.mode

The main causes are mandatory fields with null or invalid PKs values and CMS items using with a wrong catalogue version. These errors may be originated on these cases:

• WCMS
  • Removal of a page, a CMS link component or media linked to a CMS Navigation Entry. A remove interceptor can be written to prevent the removal of the item if it is associated to a navigation entry.
  • Unlink a CMS Navigation Entry from a Navigation Node. The WCMS doesn't delete the navigation entry.
  • Removal of a page without removing the contentSlotForPages after editing them. A remove interceptor can prevent this situation.
  • Add a reference in CMS component to a product within a CMS catalogue version and the sync job of it is configured to synchronize only CMS medias, relations and items.
  • Add a reference to a item in another catalogue which has references to the actual one. This will generate a circular reference between the catalogues. For example: A restrictions in an old catalogue is used by CMS components in the new catalogue.
  • Remove a page and create a new page with the same ID without synchronising. After the removal of the page, the catalogue must be synchronized.
  • A CMS component or a navigation entry references a media in the same catalogue but the sync job isn't configured to synchronized this type.
• Impex Errors
  • Removal of a contentslot without removing all the associated contentSlotForTemplate and contentSlotForPage. An sync error will only be triggered if the second objects were modified or a full synchronisation of the catalogue is done.

In every case the item with the error must have been modified after the last synchronization. If it isn't, the sync process is going to ignore it unless you select “force update” on the synchronisation wizard in hMC. To teach the WCMS users to synchronize any change before removing a component, page or navigation node and to remove access to other catalogues reduces the occurrence of the above cases.

If you get an error similar to:

d.h.p.c.j.s.AbstractItemCopyContext : An exception occured during synchronization for item: 8796388590637 of type: Content Slot-Beziehung für eine Seitenvorlage

Put a breakpoint inside de.hybris.platform.catalog.jalo.synchronization.GenericCatalogCopyContext#copy(de.hybris.platform.catalog.jalo.synchronization.ItemCopyCreator, de.hybris.platform.jalo.Item, de.hybris.platform.jalo.Item, de.hybris.platform.catalog.jalo.ItemSyncTimestamp) to find out what exception was thrown.

The cause are usually validate interceptors or after save listeners which prevent creating the target hybris item.

You can enable logging of stacktraces in the sync jobs by setting synchronization.itemcopycreator.stacktraces to true. You need log level INFO or finer at the Logger de.hybris.platform.catalog.jalo.synchronization.ItemCopyCreator. Please see https://help.sap.com/docs/SAP_COMMERCE_CLOUD_PUBLIC_CLOUD/aa417173fe4a4ba5a473c93eb730a417/1c60bf4de9bf4ada99b587f569bbb9ec.html?locale=en-US

select {c.id} catalog, {cv.version} catalogVersion, {ne.uid} UIDEntry, {ne.pk} pkEntry
from {CMSNavigationEntry as ne
    JOIN CatalogVersion as cv
	  ON {cv.pk} = {ne.catalogVersion}
	JOIN Catalog as c
	  ON {c.pk} = {cv.catalog}
}
where {ne.item} is null
or NOT EXISTS ({{
        SELECT 1
        FROM {CMSItem AS i}
        WHERE {i:pk} = {ne.item}
    }})

In one project the synchronisation created duplicate same code or uid medias, contentslots and navigation nodes. Although the multi-threading in the synchronization was turned off²⁾, the system kept generating duplicate medias. The cause of the error is still unknown but unique indexes for the column catalogVersion and code/uid on the tables medias, contentslot, cmscomponent, cmsnavigationnode, cmsnavigationentry, slotsfortemplate and slotsforpage solved the issue. After the creation of the index no error message or stack trace is shown in the logs, so further investigation of the issue couldn't be done.

• If you a validate interceptor is throwing exceptions during the synchronization, you can turn off its validation by checking if the following attribute is true:

this.getSessionService().getCurrentSession().getAttribute("catalog.sync.active");

–Tested on SAP Hybris 2005 and 5.6