Technical migration 4.3 to 4.4

This guide covers the technical migration of your Ametys CMS application from version 4.3.x to 4.4.0.
See also the graphical migration guide.

  1. Compatibility table plugins
  2. Parameter files (WEB-INF/param)
    1. Runtime file.xml
    2. Workflow files
  3. Content types
    1. Attribute type
    2. Views (metadata-set)
    3. Renaming query parameters metadataSetName
  4. Sources JAVA
    1. I18nizableText
    2. ContentValidator
  5. Extension points
    1. CollectionSelectionAwareAddTaskClientSideElement
  6. Delete plugins default-***
    1. Deleting plugin default-content
    2. Delete plugin welcome
    3. Deleting plugin default-sitemap
    4. Delete plugin default-editionstyle (beware of the pt on the runtime.xml to be done even if you don't have plugin)
    5. Deleting plugin default-ctypes
  7. Applications Ametys ODF
  8. Other plugins
  9. Solr and indexed data
  10. MySQL 8

Compatibility table plugins

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

Parameter files (WEB-INF/param)

Runtime file.xml

In the file runtime.xml delete the following line:

<org.ametys.cms.repository.comment.CommentManagerExtensionPoint>org.ametys.web.repository.comment.WebCommentManagerExtensionPoint</org.ametys.cms.repository.comment.CommentManagerExtensionPoint>

Workflow files

In the WEB-INF/param/workflows directory of your application, for all workflow definition files containing copy actions (generally 111 and 222) :

  • The function org.ametys.cms.workflow.copy.EditContentByCopyFunction no longer exists. It has been replaced by org.ametys.cms.workflow.EditContentFunction
  • The functions CreateXXXByCopyFunction must now have the EditContentFunction following it, giving :
<function type="avalon">     
    <arg name="role">org.ametys.XXX.CreateYYYByCopyFunction</arg> 
</function> 
<function type="avalon">
    <arg name="role">org.ametys.cms.workflow.EditContentFunction</arg>
</function>

In addition, there has been a renaming, to be impacted by search/replace in workflow files:

  • of the ValidateMetadataCondition at ValidateContentCondition
  • of the ValidateMetadataSynchronizeCondition at ValidationStepCondition

In addition, the workflow definition files for users .xml and udorgunit directory entities .xml need to be reworked.

In action 200, add the pre-function here after the section <restrict-to> and the <results> :

<pre-functions>
    <function type="avalon">
        <arg name="role">org.ametys.cms.workflow.EditContentFunction</arg>
    </function>
</pre-functions>

 These files are required if your application uses the plugin directory (user-directory).

Content types

Attribute type

The multilingual_string and rich_text types used in the definition of content type attributes have been renamed multilingual-string and rich-text respectively.

Search your content type definitions for all occurrences of type="multilingual_string" and type="rich_text" to replace them.

Views (metadata-set)

In the definition of a content type, it is no longer possible to have 2 versions (view + edition) of a view with the same name.

The migration concerns all your content types (specific or overloaded) and the "main" view. There are two possible scenarios:

  • Either the 2 views (type="view" and type="edition") are identical, so simply delete the "main" view with type="edition".
  • Either they differ, and the "main" view with type="edition" must be renamed to "default-edition". In this case, it is preferable to make the "default-edition" view private. 

Renaming query parameters metadataSetName

Named query parameters metadataSetName, fallbackMetadataSetName and isEditionMetadataSet were renamed in viewName, fallbackViewName and isEdition

Search for all occurrences of metadataSetName, fallbackMetadataSetName and isEditionMetadataSet in your files sitemap.xmapyour sources java and your files JS to replace them.

Sources JAVA

I18nizableText

The parameters of a I18nizableText are now I18nizableTextParameterThis means there may be compilation errors, which are easy to resolve.

 

ContentValidator

In the #validate to three arguments with the Map of values coming from the form, the values will now always be encapsulated in a SynchronizableValuefor simplicity's sake.

A simple way to retrieve the actual value is to use DataHolderHelper.getValueToValidate(value)

 

Extension points

CollectionSelectionAwareAddTaskClientSideElement

Extension points carrying the org.ametys.plugins.contentio.synchronize.clientsideelement.CollectionSelectionAwareAddTaskClientSideElement class must now take the org.ametys.core.ui.SelectionAwareAddTaskClientSideElement class and under the class tag, the following tags must be added:

<class>     
    [...]     
    <schedulable-param-name>collectionId</schedulable-param-name>     
    <selection-target-id>^synchronizableContentsCollection$</selection-target-id>     
    [...] 
</class>

Search your plugin.xml files for any references to CollectionSelectionAwareAddTaskClientSideElement.

Delete plugins default-***

Deleting plugin default-content

In the demo web template, plugin default-content has been removed.
In the demo data template, plugin default-content has been renamed "demo-content".

This plugin provides an example of a content type ("Simple content").
If you have this plugin in your application, check that this content type is not used (org.ametys.cms.default.Content.simple), and if this is the case, this plugin can be removed.

Delete plugin welcome

The plugin welcome has been removed from templates.
The "Welcome" tool is now provided by the kernel.
Customization of this tool (i.e. the text it contains) is provided by each project:

  • or in WEB-INF/param/welcome (welcome message common to all sites)
  • or in skin/ [SKIN ] /welcome if you want to personalize the welcome message according to the charter.

To migrate this plugin you have 3 possibilities:

  • if you haven't customized this plugin, or if the "Home" tool seems unnecessary, you can simply delete the plugin. The tool will no longer be available in your application (except for sites using a ODF charter overload, see box below).
  • if you wish to retrieve the text of your current tool:
    • move XSL index_**.xsl to your application's WEB-INF/param/welcome directory
    • move the resources (css, img) to your application's WEB-INF/param/welcome/resources directory
    • in your XSL index_**.xsl, a few changes need to be made:
      - add the namespace xmlns:ametys="org.ametys.web.transformation.xslt.AmetysXSLTHelper"
      - replace <xsl:param name="siteUrl"/> by <xsl:variable name="siteUrl" select="ametys:siteParameter('url')"/>
      - replace <xsl:param name="skin"/> by <xsl:variable name="skin" select="ametys:skin()"/>
      - replace <xsl:param name="contextPath"/> par <xsl:variable name="uri-prefix" select="ametys:uriPrefix()"/>
      - add <xsl:variable name="resource-uri-prefix"><xsl:value-of select="$uri-prefix"/>/param_resources/welcome</xsl:variable>
      - replace all url type {$contextPath}/plugins/welcome/resources/** by  {$resource-uri-prefix}/**

      If in doubt, refer to the web template example.
    • Delete the plugin welcome
  • if you wish to retrieve the text from your current tool and adapt it for each of your charters
    • move XSL index_**.xsl to the skin/[SKIN]/welcome directory of your graphic charts
    • move resources (css, img ) to the skin/[SKIN]/resources directory of your graphic charts
    • in your XSL index_**.xsl, a few changes need to be made:
      - add the namespace xmlns:ametys="org.ametys.web.transformation.xslt.AmetysXSLTHelper"
      - replace <xsl:param name="siteUrl"/> by <xsl:variable name="siteUrl" select="ametys:siteParameter('url')"/>
      - replace <xsl:param name="skin"/> by <xsl:variable name="skin" select="ametys:skin()"/>
      - replace all url type {$contextPath}/plugins/welcome/resources/** par  {ametys:skinURL('**')}

      If in doubt, refer to the example included in the charter ODF.
    • delete the plugin welcome

Case of ODF applications using the ODF kernel
charter The ODF kernel charter brings its own welcome message.
By simply deleting the plugin welcome, you'll have a default welcome message adapted to the ODF application and the ODF charter.
You can customize this message if required in your charter, which extends the ODF kernel charter.
You'll find an example of overloading in the "demo-odf" charter of the ODF web template.

In your XSL index_**.xsl you can now :
- use helper methods XSL org.ametys.web.transformation.xslt.AmetysXSLTHelper
- use keys i18n

Deleting plugin default-sitemap

The plugin default-sitemap has been removed from templates.

Site map icons and decorators can be added :

  • or by plugin (translation flagging, for example, for the decorator on translations)
  • or by the graphic charter (special icon for a section, for example)

The old WEB-INF/param/sitemap-icons.xml file is no longer in use.
It contained :

  • icons/decorators linked to functions (e.g. decorator for translated pages)
  • icons/decorators linked to graphic charters (different icons for different sections, for example)

From now on, feature icons/decorators are provided by the kernel and plugins ; and chart icons must be provided by graphic charts.

In your sitemap-icons.xml file, if you had icons and/or decorators specific to charter labels (e.g. SECTION, SUBSECTION, DIRECTACCESS), you will have to create them in each of your charters using these labels:

  • a file skins/[SKIN]/conf/sitemap-icons.xml for icons
  • a skins/[SKIN]/conf/sitemap-decorators file.xml for decorators

Icons and decorators linked to plugins are already imported automatically (page type container, link or node; exclusion of SEO, invisible, limited access, translation, scheduled publication). So don't just move your old file, filter its contents.

Your skins/[SKIN]/conf/sitemap-*.xml files should therefore contain only elements linked to skin.
In the template, these files contain very few rules: icons and decorators linked to SECTION, SUBSECTION and DIRECTACCESS.

Example of a sitemap-icons file.xml:

<icons>         
    <!-- Validated sections -->         
    <icon>             
        <order>5</order>             
        <glyph>ametysicon-file94 validated</glyph>             
        <conditions>                 
            <tags>                     
                <tag>SECTION</tag>                 
            </tags>                 
            <live />             
        </conditions>         
    </icon>         
    <!-- Sections -->         
    <icon>             
        <order>6</order>             
        <glyph>ametysicon-file94</glyph>             
        <conditions>                 
            <tags>                     
                <tag>SECTION</tag>                 
            </tags>             
        </conditions>         
    </icon>     
</icons>

Example of a sitemap-decorators file.xml:

<decorators>         
    <!-- Direct access -->         
    <decorator id="direct_access">             
        <label i18n="true">PLUGINS_WEB_SITEMAP_DECORATOR_DIRECT_ACCESS</label>             
        <glyph>ametysicon-link23</glyph>             
        <conditions>                 
            <tags>                     
                <tag>DIRECTACCESS</tag>                 
            </tags>             
        </conditions>         
    </decorator>     
</decorators>

Then delete the file WEB-INF/param/sitemap-icons.xml as well as plugin default-sitemap.

By deleting the plugin default-sitemap you will lose the i18n keys in "plugin.default-sitemap:". So remember to move them to the graphic charts first.

If your chart is a chart that extends the ODF kernel chart, there is no need to create the files skin/[SKIN]/conf/sitemap-icons.xml and skin/[SKIN]/conf/sitemap-decortors.xml.
They are included in the ODF chart.

Delete plugin default-editionstyle (beware of the pt on the runtime.xml to be done even if you don't have plugin)

The plugin default-editionstyle template has been removed.

Web and non-web applications

In the file WEB-INF/param/runtime.xml delete the following lines:

<org.ametys.cms.clientsideelement.styles.HTMLEditorStyleExtensionPoint>org.ametys.cms.clientsideelement.styles.StaticHTMLEditorStyleExtension</org.ametys.cms.clientsideelement.styles.HTMLEditorStyleExtensionPoint>

Data (non-web) applications only

Move the file WEB-INF/param/edition-styles.xml in the WEB-INF/param/edition-styles.
In this file delete all occurrences of : plugin.default-editionstyle and plugin="default-editionstyle"

Move the i18n and resources directories of plugin default-editionstyle to WEB-INF/param/edition-styles

Finally, delete plugin default-editionstyle.

Deleting plugin default-ctypes

The plugin default-ctypes has been removed from the demo web template. It was a plugin for demonstration purposes only.
If you have it in your projects, it's probably useless and can be removed.
This plugin provided resources and key i18n related to the addition of 2 and 3 column views for articles and news, and a "slideshow" view for photo galleries. These 3 views have been removed and replaced by view parameters.

Applications Ametys ODF

If your application is a Ametys ODF application, follow the migration guide from version 4.3 to version 4.4 ofODF.

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.4 http://releases.ametys.org/release/org.ametys / solr-app/4 .4.x/4.4.0/zips/

Check that the setenv-solr.sh 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.

MySQL 8

The JDBC connector MySQL has been upgraded to version 8. Advertised compatibility with versions of MySQL remains unchanged, but in practice you may have a problem with timezones (try doing nothing, but if it crashes, Ametys won't start, so you'll soon see).

Under Windows, you need to modify the conf in C:\ProgramData\MySQL\MySQL Server 5.7\my.ini (or whatever your version) and add, for example :

default-time-zone = '+01:00

Under Linux, this is done in the mysql conf (my.cnf or equivalent, depending on your distribution) with the parameter :

default_time_zone = '+01:00

The default-time-zone value can also refer to a string such as 'Europe/Paris', but to do this you need to follow the instructions at https://dev.mysql.com/doc/refman/8.0/en/time-zone-support.html

This can be done at theAmetys level in the data source configuration by adding: serverTimezone=Europe/Paris, which gives, for example: 

jdbc:mysql://localhost/Ametys_CMS?useSSL=false&serverTimezone=Europe/Paris
Back to top

Update manual