Historique de la page

Cette page est destinée aux intégrateurs.

Références

• Documentation officielle pour la migration vers la version 4 d'uPortal : https://wiki.jasig.org/display/UPM40/Upgrading

Outils

• Script Shell permettant la mise en conformité des channel-type pour une migration d'uPortal 3.2 vers 4.0: Migration-channel-type.sh
• Script Shell permettant la mise en conformité des fragment-definition pour une migration d'uPortal 3.2 vers 4.0: Migration-fragment-definition.sh

Contexte

Dans le cadre de la maintenance et de l’évolution de leur portail, le consortium ESUP a souhaité s’intéresser davantage quant à la migration de données d’un portail uPortal contenues dans une instance de base de données en version 3.2 vers une instance de base en version 4.0. Ce processus n’étant pas totalement défini et validé par Jasig, il est important d’en définir ses limites ainsi que la liste exhaustive des données traitées.

...

• Système d’exploitation du serveur : Windows XP
• Serveur d’application : Tomcat 6.0.32
• Serveur de base de données des bases uPortal : PostgreSQL 9.0.4
• Migration réalisée depuis une version 3.2.2 d’uPortal vers la version 4 présente sur le repository Git d’ESUP (https://github.com/EsupPortail/esup-uportal)
• Les différents outils développés ont également été testés sur un environnement Unix afin d’en valider leur bon fonctionnement.

Prérequis

Comme indiqué sur la page de Jasig, le processus de migration nécessite une installation d'une version 4.0 servant de socle pour l’import des données exportées depuis le portail en version 3.2.

...

• une nouvelle base de données configurée avec le même utilisateur que la version 3.2.
• une nouvelle instance du serveur d'application qui « contiendra » l'application uPortal en version 4.0.

Export des données de la version 3.2

 Après installation de la version 4.0, il est nécessaire de réaliser l'export des données de la base de la version 3.2. Ceci se fait via la commande Ant suivante:

...

Il est également recommandé, une fois l’export terminé, de copier l’ensemble du répertoire d'export obtenu vers un répertoire de travail qui fera l’objet de différentes modifications nécessaires à la procédure de migration vers une version 4.0.

Import des données dans la version 4.0

Import des « channel-type »

Afin de réaliser un import de données cohérent, il est nécessaire de ne conserver dans le répertoire de travail que les fichiers « .channel-type » personnalisés, c’est-à-dire tout ceux qui ne sont pas natifs à une version 3.2 non-personnalisée. Tous les autres fichiers peuvent alors être supprimés.

Afin de réaliser cette opération avec précaution, nous proposons d’appliquer une méthode de comparaison entre le répertoire « channel-type » exporté depuis la version 3.2 « personnalisée »  et le répertoire « channel-type » situé dans « UPORTAL_ROOT/uportal-impl/src/main/resources/properties/db/entities » d’un portail en version 3.2 et non-personnalisé.

Transformation des « channel-type »

Pour les « channel-type » restant, c’est-à-dire ceux à importer en version 4.0, il est alors nécessaire de les transformer en fichiers « .portlet-type.xml » tout en modifiant la définition contenu dans chacun des fichiers (Cf. https://wiki.jasig.org/display/UPM40/Upgrade+Data+Import).

...

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<portlet-type xmlns="https://source.jasig.org/schemas/uportal/io/portlet-type" xmlns:ns2="https://source.jasig.org/schemas/uportal/io/permission-owner" xmlns:ns3="https://source.jasig.org/schemas/uportal/io/stylesheet-descriptor" xmlns:ns4="https://source.jasig.org/schemas/uportal/io/portlet-definition" xmlns:ns5="https://source.jasig.org/schemas/uportal" xmlns:ns6="https://source.jasig.org/schemas/uportal/io/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0" xsi:schemaLocation="https://source.jasig.org/schemas/uportal/io/portlet-type https://source.jasig.org/schemas/uportal/io/portlet-type/portlet-type-4.0.xsd">
	<name>Bookmarks Portlet</name>
	<description>UWisc Bookmarks Portlet</description>
	<uri>/org/jasig/portal/portlets/bookmarks/BookmarksPortlet.cpd.xml</uri>
</portlet-type>

Import des « channel-type » dans uPortal v4.0

Après transformation des fichiers « channel-type » l’import peut être réalisé dans le portail en version 4.0 via la commande :

...

Si l'import s'est déroulé avec succès, un message « Build successful » devrait alors être affiché dans la console. Dans le cas échéant, un message « Build failed » sera alors affiché et les traces détaillant les différentes erreurs rencontrées seront alors visibles dans le répertoire « UPORTAL_ROOT/target/data-import-reports » du portail en version 4.0.

Import des « entity-type »

Dans le but de réaliser un import de données cohérent, il est nécessaire pour les « entity-type » de ne conserver seulement ceux qui sont personnalisés et qui ont été définis « manuellement » dans le portail 3.2 servant de socle de migration. Ainsi, identiquement aux « channel-type », tous les « entity-type » inclus nativement dans la version 3.2 pourront être supprimés du répertoire de travail utilisé pour l’import des données en base en version 4.0.

...

Si l'import s'est déroulé avec succès, un message « Build successful » devrait alors être affiché dans la console. Dans le cas échéant, un message « Build failed » sera alors affiché et les traces détaillant les différentes erreurs rencontrées seront alors visibles dans le répertoire « UPORTAL_ROOT/target/data-import-reports » du portail en version 4.0.

Import des « user »

Pour effectuer l'import dans le portail v4.0 des utilisateurs depuis les données exportées en v3.x, il suffit juste de jouer la commande Ant ci-dessous :

...

Si l'import s'est déroulé avec succès, un message « Build successful » devrait alors être affiché dans la console. Dans le cas échéant, un message « Build failed » sera alors affiché et les traces détaillant les différentes erreurs rencontrées seront alors visibles dans le répertoire « UPORTAL_ROOT/target/data-import-reports » du portail en version 4.0.

Import des « group-membership »

Afin de pouvoir importer dans la version 4.0 les groupes exportés depuis la version 3.2 il est nécessaire de réaliser deux modifications majeures dans la configuration  d’uPortal v4.0.

Modification de la configuration de la version 4.0

Les modifications permettant la mise en conformité des groupes concernent deux fichiers XML :

...

Une fois ces modifications effectuées, il est recommandé de redéployer et redémarrer l’application en version 4.0 afin de s’assurer que les modifications apportées n’ont pas affecté son bon fonctionnement.

Import des données

Suite à la vérification précédente, il suffit d’importer les données issues de l’export de la version 3.2 via la commande Ant suivante :

...

, avec Ddir ayant pour valeur le chemin vers le répertoire « group_membership » contenant les données exportées depuis la version 3.2.

Import des « channel »

NOTE: Si la servlet ExternalURLStats était utilisée dans votre ancien portail, les URL des channels de type InlineFrame seront très probablement de cette forme : "ExternalURLStats?fname=myService&service=https://my.univ.fr/iframe". Il est donc nécessaire de modifier cette valeur puisque la servlet ExternalURLStats n'est pas transposée dans cette v4. Pour cela, il suffit de lancer la commande suivante avant d'effectuer l'import : sed -i "s/ExternalURLStats.*service=//g" ./V3-EXPORT/channel/*channel

...

Ce message n’est cependant pas bloquant et les channel restants seront tout de même traités par la procédure d’import.

Import des « channel » et problème de Duplicate Key

Il se peut que durant la phase d'import des channels, certaines définitions de portlets ne puissent être importées à cause d'un problème de "Duplicate Key". Ceci signifie que les champs fname et name de la portlet à importer existent déjà dans la table de la base de données et ceci lève donc une exception suite à une contrainte d'unicité définie sur ces champs là. Une procédure manuelle a été cependant élaborée afin de palier à cette anomalie : elle consiste à réaliser une comparaison entre les deux fichiers causant l'anomalie (fichier exporté et fichier de la nouvelle version) pour en cibler les principales modifications :

...

La solution dans ce cas consiste à renommer le champ "name" de l'ancienne portlet afin que celui-ci soit unique en base. Nous proposons dans ce cas de la renommer de façon plus explicite en fonction de la fonctionnalité liée à la portlet, par exemple en la renommant : "Recherche de contenu" à la place de "Recherche".

Import des « fragment-layout »

Identiquement aux « channel », la procédure d’import des « fragment-layout » est relativement basique. Celle-ci se fait via la commande Ant :

...

, avec « IChannel1.fragment-layout » correspondant au fichier « fragment-layout » contenant un ou plusieurs IChannel et n’ayant donc pu être importé lors de la première tentative d’import.

Import des « permission_set »

L’import des « permission_set » ne devrait nécessiter aucune étape supplémentaire de traitement ou modification. Il suffit juste d'importer tout le contenu du répertoire dans la version 4.0 via la commande Ant :

...

Si l'import s'est déroulé avec succès, un message « Build successful » devrait alors être affiché dans la console. Dans le cas échéant, un message « Build failed » sera alors affiché et les traces détaillant les différentes erreurs rencontrées seront alors visibles dans le répertoire « UPORTAL_ROOT/target/data-import-reports » du portail en version 4.0.

Migration des « fragment-definition »

A partir de la version 4.0.4 d'uPortal, la définition des fragments a été revue. En effet, désormais celle-ci n'est plus gérée par défaut via le fichier « dlm.xml » situé dans le répertoire « UPORTAL_ROOT/uportal-war/src/main/resources/properties » mais directement en base de données via un bean Java associé.

...

• la première solution consiste à modifier le comportement d'uPortal v4.0 afin de revenir à une gestion des définitions de fragment via le fichier « dlm.xml ».
• la deuxième consiste à laisser la gestion des « fragment-definition » en base des données et à créer les fichiers « fragment-definition » associés à ceux de la version 3.2.

Import des « fragment-definition » via dlm.xml

Comme indiqué précédemment, depuis la version 4.0.4 d’uPortal la gestion des fragments est persistée en base et n’est plus gérée via le fichier « dlm.xml » tel que c’était le cas auparavant. Cependant Jasig permet toujours dans ces dernières versions de basculer la gestion des fragments via le fichier « dlm.xml » afin de faciliter notamment les procédures de migration telles que celle-ci. Pour effectuer cette manipulation deux actions sont alors à effectuer :

...

ant clean deploy-war -Dmaven.test.skip=true

Import des « fragment-definition » via base de données

La deuxième méthode d’import des « fragment-definition » permet quant à elle de conserver la gestion des fragments en base de données telle qu’elle a été mise en place à partir de la version 4.0.4 d’uPortal.

...

• Si l’import est effectué avec succès le message « build successful » devrait alors être affiché dans la console, le fragment défini précédemment est désormais présent dans le portail uPortal v4.0.

Migration des « theme », « structure », « profile » et « layout »

Tous ces éléments ne correspondant pas à des « données brutes » mais plutôt à la présentation, aucune procédure n’a été définie. De ce fait, aucun de ces éléments ne sera migré vers la version 4.0 d’uPortal.

Migration des données spécifiques aux développements

Dans le cas où le portail ESUP 3.2 comprendrait des données en base liées à des développements spécifiques réalisés par ESUP, il sera nécessaire de définir des procédures de migration propre à chacun de ces développements. En effet, la procédure décrite dans la page courante permet de traiter l’ensemble des données génériques gérées par uPortal et non les données qui peuvent être issues de développements spécifiques.