Migration technique 4.3 vers 4.4

Ce guide traite de la migration technique de votre application Ametys CMS d'une version 4.3.x à 4.4.0.
Reportez-vous également au guide de migration graphique.

  1. Tableau de compatibilité des plugins
  2. Fichiers de paramétrage (WEB-INF/param)
    1. Fichier runtime.xml
    2. Fichiers de workflow
  3. Types de contenus
    1. Type des attributs
    2. Les vues (metadata-set)
    3. Renommage des paramètres de requête metadataSetName
  4. Sources JAVA
    1. I18nizableText
    2. ContentValidator
  5. Points d'extensions
    1. CollectionSelectionAwareAddTaskClientSideElement
  6. Suppression des plugins default-***
    1. Suppression du plugin default-content
    2. Suppression du plugin welcome
    3. Suppression du plugin default-sitemap
    4. Suppression du plugin default-editionstyle (attention au pt sur le runtime.xml a faire même si vous n'avez pas le plugin)
    5. Suppression du plugin default-ctypes
  7. Applications Ametys ODF
  8. Autres plugins
  9. Solr et données indexées
  10. MySQL 8

Tableau de compatibilité des plugins

Reportez-vous au tableau de compatibilité des plugins et incrémentez les versions de vos plugins (prendre pour chaque plugin la version la plus récente compatible 4.4)

Fichiers de paramétrage (WEB-INF/param)

Fichier runtime.xml

Dans le fichier runtime.xml supprimez la ligne suivante:

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

Fichiers de workflow

Dans le répertoire WEB-INF/param/workflows de votre application, pour tous les fichiers de définition des workflow contenant des actions de copie (en général 111 et 222) :

  • La fonction org.ametys.cms.workflow.copy.EditContentByCopyFunction n'existe plus. Elle est remplacée par org.ametys.cms.workflow.EditContentFunction
  • Les fonctions CreateXXXByCopyFunction doivent maintenant avoir la EditContentFunction en suivant, ce qui donnera :
<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>

Par ailleurs, il y a eu renommage, à impacter par rechercher/remplacer dans les fichiers de workflow :

  • de la ValidateMetadataCondition en ValidateContentCondition
  • de la ValidateMetadataSynchronizeCondition en ValidationStepCondition

De plus, les fichiers de définition des workflow des utilisateurs user.xml et des entités de l'annuaire udorgunit.xml doivent être retouchés.

Dans l'action 200, ajoutez la pre-fonction ici après entre la section <restrict-to> et la section <results> :

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

 Vous devez posséder ces fichiers si votre application utilise le plugin Annuaire (user-directory).

Types de contenus

Type des attributs

Les types multilingual_string et rich_text utilisés dans la définition des attribut des types de contenus ont été renommés respectivement en multilingual-string et rich-text.

Recherchez dans la définition de vos types de contenus toutes les occurrences de type="multilingual_string" et type="rich_text" pour les remplacer.

Les vues (metadata-set)

Dans la définition d'un type de contenu, il n'est plus possible d'avoir 2 versions (view + edition) d'une vue avec le même nom.

La migration concerne tous vos types de contenus (spécifiques ou surchargés) et la vue "main". Deux cas de figure peuvent se présenter :

  • Soit les 2 vues (type="view" et type="edition") sont identiques, il suffit donc de supprimer la vue "main" avec type="edition"
  • Soit elles diffèrent, la vue "main" avec type="edition" doit alors être renommée en "default-edition". Il est alors préférable que cette vue "default-edition" soit privée. 

Renommage des paramètres de requête metadataSetName

Les paramètres de requêtes nommés metadataSetName, fallbackMetadataSetName et isEditionMetadataSet ont été respectivement renommés en viewName, fallbackViewName et isEdition

Recherchez toutes les occurrences de metadataSetName, fallbackMetadataSetName et isEditionMetadataSet dans vos fichier sitemap.xmap, vos sources java et vos fichiers JS pour les remplacer.

Sources JAVA

I18nizableText

Les paramètres d'un I18nizableText sont maintenant des I18nizableTextParameter, il peut donc y avoir des erreurs de compilation, faciles à résoudre.

 

ContentValidator

Dans la méthode #validate à trois arguments avec la Map de valeurs venant du formulaire, les valeurs seront maintenant toujours encapsulées dans une SynchronizableValue, pour simplifier.

Une façon simple de récupérer la valeur réelle est de passer par DataHolderHelper.getValueToValidate(value)

 

Points d'extensions

CollectionSelectionAwareAddTaskClientSideElement

Les points d'extensions portant la classe org.ametys.plugins.contentio.synchronize.clientsideelement.CollectionSelectionAwareAddTaskClientSideElement doivent désormais prendre la classe org.ametys.core.ui.SelectionAwareAddTaskClientSideElement et sous la balise class, les balises suivantes doivent être ajoutées :

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

Recherchez dans vos fichiers plugin.xml des éventuelles réferences à CollectionSelectionAwareAddTaskClientSideElement.

Suppression des plugins default-***

Suppression du plugin default-content

Dans le template web de demo, le plugin default-content a été supprimé.
Dans le template data de demo, le plugin default-content a été renommé "demo-content".

Ce plugin apporte un exemple de type de contenu ("Contenu simple").
Si vous possédez ce plugin dans votre application, vérifiez que ce type de contenu n'est pas utilisé (org.ametys.cms.default.Content.simple), et si c'est bien le cas, ce plugin peut-être supprimé.

Suppression du plugin welcome

Le plugin welcome a été supprimé des templates.
L'outil "Accueil" est désormais apportée par le noyau.
La personnalisation de cet outil (c'est à dire le texte qu'il contient) est lui apporté par chaque projet :

  • soit dans WEB-INF/param/welcome (message d'accueil commun à tous les sites)
  • soit dans skin/[SKIN]/welcome si vous voulez personnaliser le message d'accueil en fonction de la charte

Pour migrer ce plugin vous avez donc 3 possibilités :

  • si vous n'avez pas personnalisé ce plugin, ou que l'outil "Accueil" vous semble non nécessaire, vous pouvez simplement supprimer le plugin. L'outil ne sera plus disponible dans votre application (sauf pour les sites utilisant une surcharge de la charte ODF, cf encadré plus loin)
  • si vous souhaitez récupérer le texte de votre outil actuel :
    • déplacez les XSL index_**.xsl dans le répertoire WEB-INF/param/welcome de votre application
    • déplacez les ressources (css, img) dans le répertoire WEB-INF/param/welcome/resources de votre application
    • dans vos XSL index_**.xsl, quelques changement sont à faire :
      - rajoutez le namespace xmlns:ametys="org.ametys.web.transformation.xslt.AmetysXSLTHelper"
      - remplacez <xsl:param name="siteUrl"/> par <xsl:variable name="siteUrl" select="ametys:siteParameter('url')"/>
      - remplacez <xsl:param name="skin"/> par <xsl:variable name="skin" select="ametys:skin()"/>
      - remplacez <xsl:param name="contextPath"/> par <xsl:variable name="uri-prefix" select="ametys:uriPrefix()"/>
      - ajoutez <xsl:variable name="resource-uri-prefix"><xsl:value-of select="$uri-prefix"/>/param_resources/welcome</xsl:variable>
      - remplacez toutes les url du type {$contextPath}/plugins/welcome/resources/** par  {$resource-uri-prefix}/**

      En cas de doute, reportez-vous à l'exemple du template web.
    • Supprimez le plugin welcome
  • si vous souhaitez récupérer le texte de votre outil actuel et l'adapter pour chacune de vos chartes
    • déplacez les XSL index_**.xsl dans le répertoire skin/[SKIN]/welcome de vos chartes graphique
    • déplacez les ressources (css, img) dans le répertoire skin/[SKIN]/resources de vos chartes graphique
    • dans vos XSL index_**.xsl, quelques changement sont à faire :
      - rajoutez le namespace xmlns:ametys="org.ametys.web.transformation.xslt.AmetysXSLTHelper"
      - remplacez <xsl:param name="siteUrl"/> par <xsl:variable name="siteUrl" select="ametys:siteParameter('url')"/>
      - remplacez <xsl:param name="skin"/> par <xsl:variable name="skin" select="ametys:skin()"/>
      - remplacez toutes les url du type {$contextPath}/plugins/welcome/resources/** par  {ametys:skinURL('**')}

      En cas de doute, reportez-vous à l'exemple inclus dans la charte ODF.
    • supprimez le plugin welcome

Cas des applications ODF utilisant la charte ODF noyau
La charte ODF noyau apporte son propre message d'accueil.
En vous contentant de supprimer le plugin welcome, vous aurez par défaut un message d'accueil adapté à l'application ODF et à la charte ODF.
Vous pouvez personnaliser si besoin ce message dans votre charte qui étend la charte ODF noyau.
Vous trouverez une exemple de surcharge dans la charte "demo-odf" du template ODF web.

Dans vos XSL index_**.xsl vous avez désormais la possibilité :
- d'utiliser les méthodes du helper XSL org.ametys.web.transformation.xslt.AmetysXSLTHelper
- d'utiliser des clés i18n

Suppression du plugin default-sitemap

Le plugin default-sitemap a été supprimé des templates.

Les icônes et décorateurs du plan du site peuvent être apportées :

  • soit par un plugin (translation flagging par exemple pour le décorateur sur les traduction)
  • soit par la charte graphique (icône spéciale pour une rubrique par exemple)

L'ancien fichier WEB-INF/param/sitemap-icons.xml n'est plus utilisé.
Il contenait :

  • des icones/décorateurs liés à des fonctionnalités (décorateur pour les pages traduites par exemple)
  • des icones/décorateurs liés aux chartes graphiques (icônes différentes pour les rubriques par exemple)

Désormais, les icones/décorateurs de fonctionnalités sont apportés par le noyau et les plugins ; et les icônes de chartes doivent être apportés par les chartes graphiques.

Dans votre fichier sitemap-icons.xml, si vous aviez des icônes et/ou décorateurs propres à des étiquettes de charte (ex: SECTION, SUBSECTION, DIRECTACCESS, vous devrez créer dans chacune de vos chartes utilisant ces étiquettes :

  • un fichier skins/[SKIN]/conf/sitemap-icons.xml pour les icones
  • un fichier skins/[SKIN]/conf/sitemap-decorators.xml pour les décorateurs

Les icones et décorateur liées à des plugins sont déjà importés automatiquement (type de page container, link ou node ; exclusion des SEO, invisible, accès limité, traduction, publication programmée). Vous ne devez donc pas simplement déplacer votre ancien fichier, mais bien en filtrer le contenu.

Vos fichiers skins/[SKIN]/conf/sitemap-*.xml ne doivent donc contenir que des éléments liées à la skin.
Dans le template, ces fichiers ne comportent donc plus que très peu de règles : icones et décorateurs liés aux SECTION,SUBSECTION et DIRECTACCESS.

Exemple de fichier sitemap-icons.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>

Exemple de fichier sitemap-decorators.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>

Supprimez ensuite le fichier WEB-INF/param/sitemap-icons.xml ainsi que le plugin default-sitemap.

En supprimant le plugin default-sitemap vous allez perdre les clefs i18n en "plugin.default-sitemap:". Pensez donc à les déplacer dans les chartes graphiques d'abord.

Si votre charte est une charte qui étend la charte ODF noyau, il est inutile de créer les fichiers skin/[SKIN]/conf/sitemap-icons.xml et skin/[SKIN]/conf/sitemap-decortors.xml.
Ils sont en effet inclus dans la charte ODF.

Suppression du plugin default-editionstyle (attention au pt sur le runtime.xml a faire même si vous n'avez pas le plugin)

Le plugin default-editionstyle des templates a été supprimé.

Cas des applications web et non-web

Dans le fichier WEB-INF/param/runtime.xml supprimez la lignes suivantes:

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

Cas des applications data (non-web) seulement

Déplacez le fichier WEB-INF/param/edition-styles.xml dans le répertoire WEB-INF/param/edition-styles.
Dans ce fichier supprimez toutes les occurrences de : plugin.default-editionstyle et plugin="default-editionstyle"

Déplacez les répertoires i18n et resources du plugin default-editionstyle dans WEB-INF/param/edition-styles

Enfin, supprimez le plugin default-editionstyle.

Suppression du plugin default-ctypes

Le plugin default-ctypes a été supprimé du template web de demo. Il s'agissait d'un plugin uniquement présent à des fins de démonstration.
Si vous l'avez dans vos projets, il est probablement inutile et peut être supprimé.
Ce plugin apportait les resources et clé i18n liés à l'ajout des vues 2 et 3 colonnes sur les articles et les actualités et d'une vue "diaporama" pour les galeries photos. Ces 3 vues ont été supprimées et remplacées par des paramètres de vues.

Applications Ametys ODF

Si votre application est une application Ametys ODF, suivez le guide de migration de la version 4.3 à la version 4.4 de l'ODF.

Autres plugins

Suivant les plugins Ametys que vous utilisez, vous devez suivre les migrations techniques et/ou graphiques propres à chaque plugin :

Solr et données indexées

Le serveur Solr doit être réinstallé. 
Télécharger la version 4.4 http://releases.ametys.org/release/org.ametys/solr-app/4.4.x/4.4.0/zips/

Vérifier que le fichier setenv-solr.sh positionne Java 11 dans SOLR_JAVA_HOME (ou la jvm par défaut qui serait java11)

Après redémarrage du serveur Solr puis Ametys, lancez une indexation totale.

MySQL 8

Le connecteur JDBC MySQL est passé en version 8. La compatibilité annoncée avec les versions de MySQL ne changent pas mais dans la pratique vous aurez peut-être un souci de timezones (essayez sans rien faire, mais si ça plante, Ametys ne démarre pas, vous le verrez vite).

Sous Windows, il faut aller modifier la conf dans C:\ProgramData\MySQL\MySQL Server 5.7\my.ini (ou qq soit votre version) et rajouter par exemple :

default-time-zone = '+01:00'

Sous Linux ça se passe dans la conf de mysql (my.cnf ou équivalent suivant votre distrib) avec le paramètre :

default_time_zone = '+01:00'

La valeur de default-time-zone peut aussi se référer à une chaîne de caractères du style 'Europe/Paris' mais pour ce faire, il faut suivre les instructions de https://dev.mysql.com/doc/refman/8.0/en/time-zone-support.html

Il est possible de le faire au niveau d'Ametys dans la configuration de la source de données en ajoutant : serverTimezone=Europe/Paris, Ce qui donne par exemple : 

jdbc:mysql://localhost/Ametys_CMS?useSSL=false&serverTimezone=Europe/Paris
Retour en haut

Manuel de mise à jour