Module definition checks
Upon deployment of a module and before installing it, Jahia performs a control check on the module to ensure that it is compatible with the existing system.
Checks for content type definitions are done at following points of deployment:
- Module Manager UI
- Provisioning API
- Rest API
These checks would prevent the module from being deployed/installed unless conflicts have been resolved or have been optionally bypassed (see Overriding definition checks section).
In addition, definition checks are also done in the Module Manager UI page (Administration > Modules and Extensions > Modules) for the following scenarios that shows a warning when conflicts have been detected:
- Loading of the Module Manager UI page triggers a check of all started modules against the latest registered CND definitions
- Starting up already installed modules
Definition check conflicts
In general, checks are done to ensure modules with multiple versions installed/started are safe/compatible against latest registered definitions. As a general rule, loosening of restrictions against existing content definition types is considered ok but tightening of restrictions would be flagged.
Definition checks during installation will prevent the user from installing said module unless overridden. Definition checks during module startup where the module has already been installed will still allow the operation but give a warning message to the users if any conflict is detected.
Some of the major conflicts flagged:
- Declared super types mismatch
- Changed mixin/abstract flag
- Removing child node/property
- Adding mandatory child node/property or modifying child node/property to mandatory
- Property value constraint changes
- Constraints added/removed/modified
- Required type changed to a specific type
- internationalized (i18n) flag changed
- multiple flag changed
- Child node definition changes (including above changes)
- changed sameNameSiblings flag to false
- Adding mandatory child node/property
Overriding definition checks
To bypass definition checks during installation/deployment:
- When using the provisioning, bypass can be done by including
- When using the Rest API, bypass can be done by adding
--form ignoreChecks=truein the call, e.g.:
curl --user root:root1234 --form email@example.com --form ignoreChecks=true http://localhost:8080/jahia/modules/api/bundles
- in Module Manager UI, user can uncheck Validate module definition checkbox
For performance reasons, verifying definitions of started modules when loading Module Manager UI can also be disabled by setting moduleManager.skipModuleDefinitionValidation=true in jahia.properties. This option doesn't affect startup/install of modules with conflicts whether it's set to true or false.
Resolving definition check conflicts
Conflicts within content type definitions could affect integrity of existing nodes and should be resolved whenever possible. Definition compatibility must always be backward compatible with the existing content.
Some guidelines on how to resolve compatibility conflicts:
- If possible, make sure the reason for conflict is identified and resolved to maintain backwards compatibility.
- If for some reason backward compatibility would need to be broken, it needs to be ensured that there are no nodes that exist with the current content type definition. Otherwise, a manual clean up of nodes would need to be done.
- Once manual clean up of nodes is done, existing definitions can then be rolled back using Installed definitions browser within modules/tools.