Devtools synchronization details

This guide explains how objects are synchronized between the CMS and the filesystem with the help of the Devtools feature.

1 Adding objects to packages

Objects, that are added to a package will immediately be written to the filesystem (regardless of whether automatic synchronization is enabled or not).

2 Automatic synchronization

Initially, after the CMS is started, the automatic synchronization is disabled. This means that changes of objects in the CMS will not be reflected in the filesystem and changes in the filesystem will not be reflected in the CMS.

The automatic synchonization can be enabled in the UI by checking the checkbox Automatic synchronization in the packages list.

Automatic synchronization is enabled for the current user, which means that when the automatic synchronization mechanism changes objects in the CMS, this will be done on behalf that user (regarding edit locks, permissions and log entries). Automatic synchronization is always enabled/disabled for all packages.

The following table shows the relationship between initiating actions, triggered actions and automatic synchronization:

Initiating action Triggered action Depends on autosync
Create package in CMS Create package directory in fs No
Delete package in CMS Delete package directory structure in fs No
Add object to package Write object to fs No
Remove object from package Delete object directory in fs No
Change object¹ in CMS Write object to fs Yes
Delete object¹ in CMS Delete object directory in fs Yes
Update file in fs Modify object in the CMS Yes
Create (consistent) file structure for object Modify/create object in the CMS Yes
Remove object files/directory in fs No triggered action No
Remove package directory structure in fs No triggered action No

Initiating actions marked with ¹ only trigger actions, if the object acted upon is already part of a main package (but not, if the object is only part of a sub package).

3 Objects in multiple packages

It is possible to add the same object to multiple packages. When automatic synchronization is enabled and the object is changed in the CMS, the object will be synchronized with all packages it is part of.

4 Trigger chain reactions

With the automatic synchronization enabled, some actions might trigger other actions which then become the “initiating” actions and trigger other actions themselves.

Examples:

  • An object is changed in one package, automatically synchronized into the CMS and then automatically synchronized to other packages.
  • The gentics_structure.json file of a datasource is changed to contain a new entry (without specification of a global ID). The datasource is automatically synchronized into the CMS, which will create a global ID for the new entry. Then the datasource is automatically synchronized back into the filesystem, which will change the gentics_structure.json file to contain the global ID.

5 Manual synchronization

Besides the automatic synchronization it is also possible to synchronize a single package manually either from the filesystem into the CMS or the other direction.

6 Exceptions from synchronization

Some objects have attributes, which are partially or completely excepted from synchronization.

Attribute Description
contentrepository.username The username of a contentrepository will not be synchronized, unless it is set via a property (e.g. ${env:CR_USERNAME}).
contentrepository.password The password will never be synchronized, but the passwordProperty will be synchronized.
contentrepository.url The url of a contentreporitory will not be synchronized, unless it is set via a property (e.g. ${env:CR_URL}).

7 Referenced objects

References to other objects (e.g. default value for a “URL (image)” tagpart) will be stored as the global ID of the referenced objects. When syncing from the filesystem to the CMS the references will work immediatelly if the object already exists in the CMS. Otherwise the reference will be set as soon as the target object becomes available via Content Staging.

8 Object property node assignments

The nodes to which an object property is assigned is also synchronized via the nodes global IDs. When syncing an object property from the filesystem to the CMS, it will be assigned to the same nodes.

Assignment of object properties to nodes requires edit permissions on the respective node, so the sync will fail if an object property cannot be assigned to one of its nodes.

Assignment to nodes is only done during the sync itself. When a node to which an object property was assigned becomes available only after the sync, it will not be assigned to the node.