Cette page est destinée aux intégrateurs.
Références
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 contenus dans une instance de base de données en version 3.2 vers une instance de base en version 4.x. 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.
La description de la procédure générique décrite ci-dessous a été testée et validée sur l’environnement suivant :
- 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.x servant de socle pour l’import des données exportées depuis le portail en version 3.2.
A l’heure actuelle, il semble en effet impossible de réaliser ce genre de migration avec la démarche inverse, consistant à installer une version 4.x du portail sur une instance de base de données d’une version 3.2.
Il est donc nécessaire pour réaliser cette migration d'installer la version 4.x cible en créant :
- 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.x.
Export des données de la version 3.2
Après installation de la version 4.x, 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:
ant.sh db.export -Ddir="PATH/TO/DIRECTORY/WERE/DATA/WILL/BE/SAVED" -Dtype=all
, avec :
- « PATH/TO/DIRECTORY/WERE/DATA/WILL/BE/SAVED » correspondant au répertoire dans lequel les données exportées seront sauvegardées.
- « -Dtype=all » correspondant aux éléments qui seront exportés. En voici la liste dans ce cas précis :
- all-layouts
- all-profiles
- all-permission_sets
- all-channels
- all-channel-types
- all-users
- all-themes
- all-structures
- all-entity-types
- all-group_memberships
- all-fragment-definitions
Après export de ces éléments, les répertoires suivants devraient être créés dans le répertoire d’export:
- channel
- channel-type
- entity-type
- fragment-layout
- group_membership
- layout
- permission_set
- profile
- structure
- theme
- user
Après cette procédure d’export, il est fortement recommandé de vérifier les logs afin de s’assurer que la procédure d’export s’est déroulée correctement. Ceux-ci sont sauvegardés dans le répertoire : « UPORTAL_ROOT/target/data-import-reports » où « UPORTAL_ROOT » correspond au répertoire d’installation du portail en version 3.2.
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.x.
Import des données dans la version 4.x
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.x, 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).
Pour cela un script Shell Unix : « Migration-channel-type.sh » utilisant SED a été développé. Celui-ci permet de :
prendre en argument le répertoire contenant tous les « channel-type » à transformer.
Exemple de commande en résultant:Migration-channel-type.sh « ./V3-EXPORT/channel-type »
- ajouter l'entête de définition XML dans le fichier.
modifier la balise ouvrante :
<channel-type script="classpath://org/jasig/portal/io/import-channel-type_v2-6.crn">
par la balise:
<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">
- modifier la balise fermante : </channel-type> par </portlet-type>
- supprimer la ligne contenant la balise <type> qui n'est plus nécessaire pour les « portlet-type »
- modifier l'extension du fichier « .channel-type » par l'extension « .portlet-type.xml » utilisée en version 4.x
Exemple pour le channel-type « Bookmarks_Portlet.channel-type »
Fichier « Bookmarks_Portlet.channel-type » avant transformation :
<channel-type script="classpath://org/jasig/portal/io/import-channel-type_v2-6.crn"> <name>BookmarksPortlet</name> <type>org.jasig.portal.channels.portlet.CSpringPortletAdaptor</type> <desc>UWisc Bookmarks Portlet</desc> <uri>/edu/wisc/my/portlets/bookmarks/BookmarksPortlet.cpd</uri> </channel-type>
Fichier « Bookmarks_Portlet.portlet-type.xml » résultant de la transformation:
<?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>