Jalios produit deux nouvelles versions de JCMS par an, une version majeure et une mineure. Ces nouvelles versions contiennent des nouvelles fonctionnalités mais aussi des correctifs qui renforcent la robustesse et la stabilité de votre gestion de contenu. Si vous avez souscrit une maintenance évolutive, vous disposez d'un accès gratuit aux nouvelles versions. Mais une fois la dernière version de JCMS téléchargée et installée, il faut y réintroduire vos données, vos paramétrages et vos développements spécifiques. Pour vous assister dans cette tâche qui peut se révéler complexe, JCMS dispose d'un outil de migration, le gestionnaire des changements. Après avoir présenté ce qui doit être migré, cet article décrit l'usage du gestionnaire des changements et conclut sur les précautions à prendre pour faciliter les futures migrations.

1. Préparation pour la migration

Avant toute migration, vous devez installer dans votre environnement de développement :

la webapp source : une copie de la webapp à migrer
la webapp cible : la webapp contenant la nouvelle version de JCMS sur laquelle vous souhaitez migrer. Celle-ci doit être dans la même langue que la webapp JCMS dont vous êtes partie.
la webapp base : la webapp JCMS à partir de laquelle les développements ont été réalisés. Celle-ci pourra être nécessaire pour résoudre certains conflits.

Le temps nécessaire à la migration est variable et fonction de la quantité de changement. Cela peut prendre de quelques minutes pour un cas simple à plusieurs heures pour un cas complexe comportant de nombreux conflits. La complexité augmente d'autant plus que l'écart de version entre votre version de JCMS et celle sur laquelle vous migrez est important. C'est pour cela qu'il est conseillé de migrer régulièrement afin de maintenir un écart faible.

Enfin, pour réduire le temps de migration, il est conseillé de se faire assister d'une personne connaissant bien l'ensemble des développements et des correctifs qui ont été réalisés sur la webapp. Celle-ci pourra prendre les bonnes décisions lors de la résolution des éventuels conflits.

2. Les spécificités client

JCMS est un logiciel fortement adaptable. Bien qu'il soit livré sous forme d'une webapp prête à l'emploi, il doit paramétré et, plus généralement, spécialisé pour correspondre aux attentes du client. Puis le client alimente JCMS en données (contenus, portlets, catégories, …) et en documents. Tout ceci constitue les spécificités clients qui doivent être préservées et migrées sur la nouvelle version. Si la majeure partie des spécificités client est localisée dans le répertoire WEB-INF/data, certaines ressources (JSP, documents, développements spécifiques) doivent se situer dans des répertoires imposés de la webapp. La première étape de la migration consiste donc à identifier et à localiser l'ensemble de ces ressources éparses.

2.1 Le paramétrage

Le premier niveau de spécialisation concerne le paramétrage de JCMS. Celui-ci se fait via l'éditeur de propriétés de JCMS qui permet d'agir sur les paramètres de base de JCMS (nom du site, type d'accès, langues, ...) ainsi que sur la configuration de l'infrastructure (serveur LDAP, serveur SMTP, proxy, réplication, ...). L'ensemble de ces données est stocké dans le fichier WEB-INF/data/custom.prop. Dans la majeure partie des migrations, ce fichier doit être repris tel quel.

2.2 Les données et les modèles de workflows

Les objets (les publications, les espaces de travail, les groupes, les membres, les catégories, ...) sont sauvegardés dans le fichier WEB-INF/data/store.xml. Les modèles de workflows sont stockés dans le fichier WEB-INF/data/workflow.xml. Les définitions des rôles sont des objets et stockés, en tant que tel, dans le store.xml. Dans la majeure partie des migrations, ces deux fichiers doivent être repris tel quel. Les documents (les fichiers déposés sur JCMS par les contributeurs) se situent dans le répertoire upload/.

2.3 Les types de publications

L'une des principales caractéristiques de JCMS est de permettre aux administrateurs de développer et de faire évoluer les types de publication (types de contenu, de portlet et de formulaire). La structure de chaque type est enregistrée dans le fichier WEB-INF/data/types/NomDuType.xml. Les types pouvant hérités (au sens objet du terme) les uns des autres, il est impératif de récupérer l'ensemble de la hiérarchie des types modifiés.

2.4 Les gabarits de présentation

Les gabarits de présentation sont associés aux types de publications. Ils sont déclarés dans le fichier XML du type et sont matérialisés par des fichiers JSP. Tous les JSP d'un type se situent dans le répertoire types/NomDuType/. Lors de la génération des ressources associées à un type, JCMS génère deux JSP de présentation (doNomDuTypeFullDisplay.jsp et doNomDuTypeResultDisplay.jsp). Ces JSP (au moins le FullDisplay) sont généralement retravaillés pour intégrer la charte graphique du client. De plus, un type de publication peut disposer d'autres JSP de présentation. Lors de la migration il faut identifier parmi les fichiers du répertoire du type, ceux qui ont été modifiés ainsi que nouveaux fichiers (JSP mais aussi images, CSS, ...)

2.5 Les skins des portlets

Les portlets sont des types de publication et disposent, comme les types de contenu, de gabarits de présentation. Néanmoins, ces gabarits concernent le contenu de la portlet. Le décorum autour de la portlet est géré par la skin associée à la portlet. Les skins sont des gabarits de présentations (c'est-à-dire des JSP) attachées au type AbstractPortletSkinable. Lors des migrations, des conflits sont souvent détectés sur le fichier AbstractPortletSkinable.xml du fait des changements sur ses gabarits de présentations.

2.6 CSS

JCMS utilise des feuilles de style CSS pour agir sur la présentation des données. Il y a principalement 3 fichiers de CSS qui peuvent être modifiés :

custom.css : Ce fichier est inclus dans toutes les pages du front-office produites par JCMS. Il est livré vide et est destiné à accueillir les styles spécifiques de la webapp.
css/jalios.css : Ce fichier contient les feuilles de style utilisées par les portlets
css/wysiwyg.css : ce fichier contient les feuilles de style utilisés par l'éditeur wysiwyg.

2.7 Les développements spécifiques

JCMS dispose de nombreuses fonctionnalités qui le rende rapidement opérationnel par un simple paramétrage et des développements de types et de gabarits. Néanmoins, dans bien des cas, le site construit avec JCMS, doit s'intégrer dans un environnement particulier. Pour cela, il peut-être nécessaire de faire quelques développements spécifiques. L'architecture de JCMS a été conçue pour accueillir des codes de traitement spécifique (gestion des authentifications, gestion des droits, déclenchement d'actions lors de modification des données, ...). Il est recommandé de placer l'ensemble de ces développements dans le package custom (WEB-INF/classes/custom).

2.8 Les modifications apportées au code de JCMS

Dans certains cas, les points de débranchement n'existent pas et des modifications d'une partie du code de JCMS sont nécessaires. Il s'agit la plupart du temps, de modification de JSP tels que display.jsp, doInitMember.jsp ou doEmptyHeader.jsp. Bien que ces modifications soient aisées, elles doivent néanmoins être limitées au minimum car le risque de conflits est important lors des migrations.

Enfin, il peut aussi s'agir de correctifs fournit par Jalios (JSP, JAR, classes, ...). Ces correctifs ont été intégrés aux nouvelles versions de JCMS et ne doivent surtout pas être repris lors des migrations.

2.9 Les autres fichiers

Enfin, il existe d'autres fichiers, qui ne posent pas de problème particulier lors des migrations :

upload/ : répertoire des fichiers téléchargés
WEB-INF/data/lucene/ : repertoire de l'indexation des fichiers déposés par téléchargement (alimenté par JCMS Universal)
WEB-INF/data/logs/ : répertoire contenant les journaux d'accès (1 fichier par jour)
WEB-INF/data/jsynclog/ : répertoire contenant les journaux des transactions jsync (1 fichier par jour)
WEB-INF/data/webapp.prop : ce fichier contient les propriétés propres à la webapps.

2.10 Exemples de spécificités client

A titre d'exemple, voici une arborescence des spécificités clients.

Cette arborescence contient :

du paramétrage (custom.prop, workflow.xml)
des données (store.xml, upload/)
la définition d'un nouveau type (FicheProduit) et celle d'un type modifié (AbstractPortletSkinable)
un gabarit (doFicheProduitFullDisplay.jsp)
une skin (MyCustomSkin)
un CSS modifié (custom.css)
des correctifs ( JSP et classes)

3. Le gestionnaire des changements

Comme nous venons de voir, les possibilités d'adaptations de JCMS sont nombreuses et concernent des fichiers disséminés dans toute l'arborescence de la webapp. Aussi, pour simplifier la collecte de ces changements lors des phases de migration, JCMS dispose d'un outil intégré : le gestionnaire des changements. Cet outil permet de rapidement détecter tous les fichiers ayant été modifiés et les modifications entrant en conflit avec la nouvelle version. Il produit un fichier zip reprenant l'ensemble des spécificités clients qui sont ensuite déployées sur la nouvelle version de JCMS.

3.1 Les signatures

Pour détecter les changements, JCMS utilise des signatures numériques (MD5). Il s'agit d'une emprunte numérique de 128 bits représentant un condensé d'un fichier. Le moindre changement dans le contenu du document, entraînera une signature totalement différente. Le fichier WEB-INF/jalios/signature.xml contient la signature de tous les fichiers tels qu'ils ont été livrés.

A tout moment, le gestionnaire des changements permet de générer un nouveau fichier de signatures, reflétant l'état actuel de la webapp. En comparant ce fichier (la source) avec celui livré (la base), JCMS fait ressortir les fichiers qui diffèrent, c'est-à-dire, qui ont été créés, modifiés ou supprimés. En intégrant un troisième fichier de signatures (la cible) représentant la webapp vers laquelle on souhaite migrer, JCMS peut alors détecter, parmi les fichiers différents, ceux qui sont conflictuels avec ceux de la nouvelle version.

Certains fichiers ne sont pas inclus dans les fichiers de signature, car il s'agit de fichiers dont on sait a l'avance comment les traiter.

3.2 Sens de la migration

La migration peut s'effectuer de deux manières :

soit en migrant les spécificités client sur la nouvelle version de JCMS ;
soit en appliquant les nouveautés de la nouvelle version de JCMS à la webapp client.

Si votre webapp a été développée sur une version supérieure ou égale à JCMS 4.0.3, le premier sens est recommandé. C'est celui qui est exposé ci-dessous.
Si votre webapp est inférieure à JCMS 4.0.3 ou si les spécificités clients sont très nombreuses, il peut être intéressant d'envisager l'autre sens. Dans ce cas, on procède de la même façon mais la source devient la webapp contenant la nouvelle version de JCMS et la webapp client devient la cible.

3.3 Détection des changements (diff2)

La première étape consiste à signer la webapp client. Pour cela, authentifiez-vous en administrateur. Allez dans l'espace d'administration, choisissez le menu Gestion des changements et cliquez sur le bouton "Signer le site". Une fois cette signature effectuée, elle apparaît dans la liste des signatures sources. En cliquant sur le bouton "Montrer les changements", JCMS liste les fichiers différents ainsi que le type différence :

Création (C) en jaune
Modification (U) en orange
Suppression (D) en gris.

3.4 Détection des conflits (diff3)

La détection des éventuels conflits avec la nouvelle version consiste à repérer les fichiers ayant été modifiés ou supprimés à la fois sur la webapp source et la webapp cible (les conflits de création sont aussi identifiés mais rarissimes). Pour ce faire, on compare les signatures des trois webapps : base, source et cible. Il est donc nécessaire de disposer de la signature de la webapp cible. Pour cela, cliquer sur le bouton "Déposer une signature cible". Une fenêtre de téléchargement apparaît permettant de sélectionner le fichier de signature. Celui-ci se trouve dans nouvelleVersion/WEB-INF/jalios/signature.xml. Une fois le téléchargement terminé, sélectionnez cette signature comme cible et cliquez sur "Montrer les changements". Les fichiers conflictuels apparaissent en rouge.

3.5 Résolution des conflits

Pour chaque conflit, il est nécessaire de prendre une décision :

Faut-il prendre le fichier source (p. ex. store.xml) ?
Faut-il prendre le fichier cible, i.e. ne pas prendre le fichier source (p.ex. un correctif) ?
Faut-il faire une fusion entre le fichier source et le fichier cible (p.ex. AbstractPortleSkinable.xml) ?

Les cas 1 et 2 consistent simplement à cocher ou non la case en face du fichier conflictuel. Le cas 3 ne concerne que les fichiers texte (la fusion de fichiers binaire ayant généralement peu de sens) et est plus délicat car JCMS ne fournit pas de support pour la fusion. Par défaut, le gestionnaire des changements applique le cas 2.

D'une manière générale, il est recommandé de ne pas prendre les fichiers conflictuels de la source à l'exception des fichiers de paramétrage et de données : custom.xml, store.xml et workflow.xml.

Les fichiers conflictuels contenant des modifications à migrer (p. ex. un gabarit ajouté à AbstractPortletSkinable) ne doivent pas être cochés et feront l'objet d'une fusion ultérieure.

3.6 Génération du fichier zip

Une fois la sélection terminée, le fichier zip peut être généré. Outre les fichiers choisis dans la liste des changements, ce zip peut inclure les répertoires de logs, d'indexation Lucene, des documents ainsi que les fichiers générés pour les types sélectionnés (ceci évitera une re-génération lors du déploiement). Lorsque vous cliquez sur le bouton "Générer le zip", le zip est généré et votre navigateur vous propose de le sauvegarder sur votre disque.

3.7 Fusion des modifications

Lorsqu'un conflit porte sur des modifications qui doivent être intégrées à la cible, il faut réaliser une fusion. Afin de ne pas commettre d'oublis lors des fusions, il est recommandé d'utiliser un outil dédié à cette tâche. Il existe de nombreux outils de fusion de fichier mais assez peu font des comparaisons à trois fichiers (base, source, cible). Or ce type d'algorithme de comparaison (diff3) permet de faire des fusions automatiques en cas de changement non conflictuels (i.e. de changement qui ne concernent pas les mêmes lignes). Jalios préconise l'outil Open Source kdiff3 disponible en téléchargement sur le site :

http://kdiff3.sourceforge.net/

kdiff3 permet de comparer graphiquement les différences entre un fichier source et un fichier cible en faisant intervenir le fichier de base. kdiff3 résout automatiquement les divergences lorsque celles-ci ne portent pas sur les mêmes lignes. Dans le cas contraire, il est nécessaire d'indiquer quelles lignes de la source ou de la cible doivent être retenues. kdiff3 produit alors un fichier intégrant les modifications retenues. Pour plus de détail, nous renvoyons le lecteur à la documentation de kdiff3 (http://kdiff3.sourceforge.net/doc/). Le résultat de la fusion doit ensuite intégrer manuellement au fichier zip.

3.8 Déploiement des changements

Le fichier zip est construit de manière à ce que tous les chemins de fichiers soient relatifs à la racine de la webapp. Le déploiement consiste simplement à décompacter le fichier zip à la racine de la nouvelle webapp JCMS (la cible). Une fois le déploiement terminé, la webapp doit être redémarrée. Il ne reste alors plus qu'à tester que l'ensemble des spécificités clients a bien été correctement migré.

3.9 Si la webapp ne redémarre pas correctement

Il peut arriver que la webapp migrée ne redémarre pas correctement. Consultez l'état du site avec status.jsp. Si le canal n'est pas démarré (channel == null), il s'agit très certainement d'un problème lié à la compilation des ressources partagés. Effacez les fichiers FileIndexListener.* et LinkIndexListener.* du répertoire WEB-INF/classes/generated/, puis redémarrez. Si le problème persiste, contactez le support Jalios.

4. Précautions à prendre

Le respect de quelques précautions facilitera les phases de migrations :

Limiter les modifications sur les JSP livrés avec JCMS. Lorsque cela est possible localiser les ajouts dans un JSP dédié que l'on inclue dans le JSP modifié.
Placer vos développements spécifiques dans les points de spécialisation prévues par JCMS (custom.prop, webapp.prop, le package custom, doInitCustom.jsp, adminCustom.jsp, ...)
Documenter vos modification, en particulier lorsqu'il s'agit de modification sur de JSP de JCMS
Utiliser une convention de nommage sur vos fichiers
Ne pas modifier les retours chariots des fichiers livrés avec JCMS. En cas de modification, le gestionnaire des changements détectera un changement (ce qui augmente fortement les risques de conflit). Attention en particulier à certains outils, tels que UltraEdit, qui ont tendance à modifier le type de retour chariot lors de l'ouverture d'un fichier.
Enfin, ne pas hésiter à contacter le support Jalios pour faire part de vos besoins spécifique. Nos équipes vous aideront à faire les choix les plus pertinent, en particulier pour simplifier les migrations. De plus, si tout ou partie de ces besoins révèlent un caractère générique, ils seront peut-être intégrés en standard dans une future version de JCMS.

Réussir ses migrations avec JCMS