Module definition checks

November 14, 2023

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).

Module start-up

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 ignoreChecks: true option
  • When using the Rest API, bypass can be done by adding --form ignoreChecks=true in the call, e.g.: 
    curl --user root:root1234 --form bundle=@database-connector-1.4.0.jar --form ignoreChecks=true http://localhost:8080/modules/api/bundles
  • in Module Manager UI, user can uncheck Validate module definition checkbox

module-definition-check.PNG

 

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.