Historique de la page

...

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.

...

 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:
  

  Bloc de code
  language bash linenumbers true
  Migration-channel-type.sh « ./V3-EXPORT/channel-type ».

• ajouter l'entête de définition XML dans le fichier.

• modifier la balise ouvrante : 

  Bloc de code
  language html/xml linenumbers true
  <channel-type script="classpath://org/jasig/portal/io/import-channel-type_v2-6.crn">

  par la balise:

  Bloc de code
  language html/xml linenumbers true
  <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 concret pour le channel-type « Bookmarks_Portlet.channel-type » exporté depuis la version 3.2 :

Fichier « Bookmarks_Portlet.channel-type » avanttransformation :

<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>