Technical migration 4.2 to 4.3

This guide covers the technical migration of your Ametys CMS application from version 4.2.x to 4.3.0.
See also the graphic migration guide and the data migration guide.

  1. Compatibility table plugins
  2. Parameter files (WEB-INF/param)
    1. Scripts file.xml
    2. Workflow files
  3. Content types
    1. Reserved key words
    2. Checking content views
    3. Private reference tables
  4. Feature deactivation
  5. Logs
  6. Applications Ametys ODF
  7. Other plugins
  8. Solr and indexed data

Compatibility table plugins

Refer to the plugins compatibility table and increment the versions of your plugins (take the most recent 4.3-compatible version for each plugin ).

Parameter files (WEB-INF/param)

Scripts file.xml

The WEB-INF/param/scripts file.xml lets you define your own script functions that can be executed from the script console.
The XML format of this file has changed in 4.3. If you have your own file, you will need to migrate it to 4.3 format.
Please refer to the script

Workflow files

Pour que l'import des contenus d'une archive fonctionne, le workflow des contenus (de tout type) doit contenir l'action avec id=0.
Vérifiez que les fichiers de workflow se trouvant dans le répertoire WEB-INF/param/workflows contiennent bien cette action et si non, ajoutez-là dans la section <initial-actions> comme dans l'exemple ci-dessous :

<action id="0" name="plugin.default-workflow:WORKFLOW_ACTION_CREATE">         
        <unconditional-result old-status=" " status=" " step="1" />         

Content types

Reserved key words

The following keywords are reserved and can no longer be used as field names in your content types:
creator, icon-small, workflow-step, rowBodyLoaded, creationDate, lastMajorValidationDate, contributorDisplay, site, contributor, lastValidationDate, rowBodyContent, firstValidationDate, workflow-step-id, icon-glyph, icon-decorator, name, lastModified, id, workflow-icon-small.

If your content types declare a field named with one of these reserved words, your application won't start, and an error log will specify which fields conflict with this list.

You must then :

  • rename this field in the content type declaration.
  • search and replace in your XSL rendering the use of this field
  • check that this field is not used in your java classes for other processing (exports, etc.)
  • run a script migration on your data (not currently provided except for the "site" field)

If the conflict concerns the "site" attribute, the data migration guide provides an example of script to migrate this "site" field to another "location" attribute.    

Checking content views

Within a content type, if a view (metadata-set) references an attribute (metadata-ref) that is not defined by that type, an exception is thrown and Ametys starts up in safe mode.

In this case, simply delete the references in the relevant views.

Private reference tables

The "Reference table" menu now excludes "private" reference tables.
If your reference tables no longer appear in this menu, they are probably declared as "private" when they shouldn't be.

Recherchez dans la définition de vos types de contenus, les types contenant l'étiquette <cms:tag>reference-table</cms:tag>.
Pour chacun d'eux, supprimez l'étiquette privée <cms:tag>private</cms:tag> si elle s'y trouve alors que vous souhaitez accéder à vos tables de référence via le menu "Table de référence".

Feature deactivation

If your application has its own plugins (apart from plugins default-** and welcome), you'll need to check all the "features" that deactivate others. To do this, search the plugin.xml files of these plugins for the keyword "deactivates":

<feature name="..." deactivates="...">        

In some cases, the desired behavior is notdeactivates, butoverrides. Each case needs to be studied and, if necessary, modified.


Log files are now encoded in UTF-8.

Open the WEB-INF/log4j.xml (and WEB-INF/log4.xml.deliver) files for the CMS and site applications and add them:

<appender ...>      
     <param name="Encoding" value="UTF-8" />
<!-- à faire sur tous les <appender> en début d'appender -->           

In order to track automatic migrations (new in 4.3), it is advisable to set the log level of the relevant extension point to INFO in the WEB-INF/log4j.xml file (and WEB-INF/log4j.deliver.xml if applicable):

<appender name="migration" class="org.apache.log4j.rolling.RollingFileAppender">
<param name="Encoding" value="UTF-8" />
<rollingPolicy class="org.apache.log4j.rolling.TimeBasedRollingPolicy">
<param name="FileNamePattern" value="${ametys.home.dir}/logs/migration-%d.log"/>
<layout class="org.apache.log4j.PatternLayout"> 
<param name="ConversionPattern" value="%d %-5p [%c] (%t;%X{requestURI}) %m%n"/>
<filter class="org.ametys.core.util.AmetysExceptionFilter"/>

<category name="org.ametys.core.migration.MigrationExtensionPoint" additivity="false">
<priority value="info"/>
<appender-ref ref="migration"/>

This operation must be performed on the CMS application and on the SITE application.

Applications Ametys ODF

If your application is a Ametys ODF application, follow the migration guide from version 4.1 to version 4.3 of theODF

Other plugins

Depending on the plugins Ametys you use, you must follow the technical and/or graphic migrations specific to each plugin :

Solr and indexed data

The Solr server must be reinstalled.
Download version 4.3 / solr-app/4 .3.x/4.3.0/zips/

Check that the file sets Java 11 in SOLR_JAVA_HOME (or the default jvm, which would be java11).

After restarting the server Solr then Ametys, run a full indexing operation.

Back to top