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>
Import des « channel-type » dans uPortal v4.x
Après transformation des fichiers « channel-type » l’import peut être réalisé dans le portail en version 4.x via la commande :
ant data-import -Ddir="./V3-EXPORT/channel-type"
, avec Ddir ayant pour valeur le chemin vers le répertoire contenant les « channel-type » exportés et transformés.
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.x.
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.x.
Afin de réaliser cette tâche de manière rigoureuse, il est également conseillé d’effectuer une comparaison entre le répertoire « entity-type » obtenu depuis l'export et le répertoire « entity-type » du portail natif en version 3.2 (situé dans « UPORTAL_ROOT/uportal-impl/src/main/resources/properties/db/entities/entity-type »)
Les « entity-type » personnalisés peuvent alors être importés dans le portail v4.x via la commande Ant suivante :
ant data-import -Ddir="./V3-EXPORT/entity-type"
, avec Ddir ayant pour valeur le chemin vers le répertoire contenant les « entity-type » exportés.
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.x.
Import des « user »
Pour effectuer l'import dans le portail v4.x des utilisateurs depuis les données exportées en v3.x, il suffit juste de jouer la commande Ant ci-dessous :
ant data-import -Ddir="./V3-EXPORT/user"
, avec Ddir ayant pour valeur le chemin vers le répertoire contenant les « user » exportés depuis la version 3.2.
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.x.
Import des « group-membership »
Afin de pouvoir importer dans la version 4.x 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.x.
Modification de la configuration de la version 4.x
Les modifications permettant la mise en conformité des groupes concernent deux fichiers XML :
- Le premier : « PAGSGroupStoreConfig.xml », situé dans « UPORTAL_ROOT/ uportal-war/src/main/resources/properties/groups », permet de configurer la gestion des attributs des utilisateurs appartenant aux différents groupes.
- Le deuxième : « personDirectoryContext.xml », situé dans le répertoire « UPORTAL_ROOT/ uportal-war/src/main/resources/properties/contexts », permet quant à lui de définir les attributs des utilisateurs en fonction de leur source respective (utilisateur enregistré en base, utilisateur LDAP etc…)
Concernant le premier fichier « PAGSGroupStoreConfig.xml », le travail consiste à ajouter dans le fichier l’ensemble des groupes personnalisés (groupes LDAP entre autres) définis dans le fichier « PAGSGroupStoreConfig.xml » de la version 3.2. Il est donc juste nécessaire de réaliser une comparaison entre les deux fichiers afin d’inclure dans le fichier de la version 4.x tous les groupes ajoutés dans le fichier source de la version 3.2
Concernant le fichier « personDirectoryContext.xml », il est nécessaire également de réaliser une comparaison du fichier avec celui de la version 3.2 afin de vérifier si un bean Java supplémentaire est défini dans celui-ci. Ceci devrait d’ailleurs être le cas pour la gestion des attributs des utilisateurs synchronisés avec le LDAP. Dans ce cas, il est alors nécessaire d’ajouter le bean manquant dans le fichier de la nouvelle version et d’ajouter la référence à ce nouveau bean dans la liste des bean inclus dans la balise <property name="personAttributeDaos"> du bean « mergedPersonAttributeDao ».
Voici un exemple illustrant l’ajout de la gestion des attributs des utilisateurs LDAP :
Ajout du bean définissant les attributs LDAP utilisés pour les utilisateurs synchronisés avec un LDAP :
<bean id="cachinguPortalLdapUserSource" class="org.jasig.services.persondir.support.CachingPersonAttributeDaoImpl"> <property name="usernameAttributeProvider" ref="usernameAttributeProvider" /> <property name="cacheNullResults" value="true" /> <property name="userInfoCache"> <bean class="org.jasig.portal.utils.cache.MapCacheFactoryBean"> <property name="cacheFactory" ref="cacheFactory" /> <property name="cacheName" value="org.jasig.services.persondir.USER_INFO.ldap_person_dir" /> </bean> </property> <property name="cacheKeyGenerator" ref="userAttributeCacheKeyGenerator" /> <property name="cachedPersonAttributesDao" > <bean id="uPortalLdapAttributeSource" class="org.jasig.services.persondir.support.ldap.LdapPersonAttributeDao"> <property name="contextSource" ref="defaultLdapContext" /> <property name="baseDN" value="${ldap.baseDn}" /> <property name="queryAttributeMapping"> <map> <entry key="username" value="uid" /> </map> </property> <property name="resultAttributeMapping"> <map> <entry key="eduPersonPrimaryAffiliation"> <value>eduPersonPrimaryAffiliation</value></entry> <entry key="cn"> <value>cn</value></entry> <entry key="description"> <value>description</value></entry> <entry key="displayName"> <value>displayName</value></entry> <entry key="givenName"> <value>givenName</value></entry> <entry key="sn"> <value>sn</value></entry> <entry key="uid"> <value>uid</value></entry> <entry key="eduPersonAffiliation"> <value>eduPersonAffiliation</value></entry> <entry key="objectClass"> <value>Affiliation</value></entry> <entry key="ENTPersonContrib"> <value>ENTPersonContrib</value></entry> <entry key="ENTPersonAdmin"> <value>ENTPersonAdmin</value></entry> <entry key="ENTPersonAdminInstitutionnel"> <value>ENTPersonAdminInstitutionnel</value></entry> <entry key="ENTPersonContribInstitutionnel"> <value>ENTPersonContribInstitutionnel</value></entry> <entry key="ENTPersonCollectivite"> <value>ENTPersonCollectivite</value></entry> <entry key="ENTPersonServicesALaCarte"> <value>ENTPersonServicesALaCarte</value></entry> <entry key="ENTPersonAdminRessource"> <value>ENTPersonAdminRessource</value></entry> <!-- SYMPA --> <entry key="mail"><value>mail</value></entry> </map> </property> </bean> </property> </bean>Ajout de la référence à ce bean pour l’utiliser dans le cas des utilisateurs synchronisés avec le LDAP :
<bean id="mergedPersonAttributeDao" class="org.jasig.services.persondir.support.CachingPersonAttributeDaoImpl"> <property name="usernameAttributeProvider" ref="usernameAttributeProvider" /> <property name="cacheNullResults" value="true" /> <property name="userInfoCache"> <bean class="org.jasig.portal.utils.cache.MapCacheFactoryBean"> <property name="cacheFactory" ref="cacheFactory" /> <property name="cacheName" value="org.jasig.services.persondir.USER_INFO.merged" /> </bean> </property> <property name="cacheKeyGenerator" ref="userAttributeCacheKeyGenerator" /> <property name="cachedPersonAttributesDao" > <bean class="org.jasig.services.persondir.support.CascadingPersonAttributeDao"> <property name="usernameAttributeProvider" ref="usernameAttributeProvider" /> <property name="personAttributeDaos"> <list> <ref bean="uPortalAccountUserSource" /> <ref bean="uPortalJdbcUserSource" /> <!-- ADDITIONAL ATTRIBUTE SOURCES GET ADDED HERE --> <ref bean="cachinguPortalLdapUserSource"/> </list> </property> </bean> </property> </bean>
Une fois ces modifications effectuées, il est recommandé de redémarrer l’application en version 4.x afin de s’assurer que les modifications apportées n’ont pas affecté son bon fonctionnement.