Guide de migration de Confluence vers XWiki : de l'exportation à la personnalisation

25 mai 2020 5 min read
Écrit par Stefana Nazare, Gestionnaire de compte

Mises à jour importantes

👉 Découvrez notre nouveau Migrateur Confluence (Pro) et le processus en 2 étapes pour migrer en douceur vers XWiki !

💻 Vous pouvez également consulter notre article de webinaire qui vous fournira un aperçu de toutes les nouvelles fonctionnalités du nouveau Confluence Migrator (Pro), une démonstration du processus de migration et la transcription de la session de questions réponses. 

Ce guide a été mis à jour le 9 août, 2023.

De nombreuses sociétés ont récemment choisi de migrer de Confluence à XWiki. D'après les retours, les fonctionnalités d'organisation, les données structurées, les tarifs attractifs, le contrôle complet de vos données, et l'extensibilité sont les facteurs de migration les plus cités.
Si vous envisagez, vous aussi, de migrer de Confluence à XWiki, mais que vous n'êtes pas encore tout à fait sûr de votre choix, vous pouvez consulter la comparaison complète entre ces deux produits.

Mais, si vous êtes prêt à sauter le pas, voici la marche à suivre !

Méthode avec migrateur dédié

Prérequis

  • une instance XWiki avec des droits d'administration
  • accès aux fichiers de configuration de votre instance XWiki

L'accès aux fichiers de configuration de XWiki n'est nécessaire que si vous exécutez la migration sur une instance installée sur site.

Profil de migration

Cliquez sur l'application de migration Confluence installée sur votre instance pour commencer le processus. Créez un profil de migration pour chaque espace que vous souhaitez migrer :

migrator-1.png

Remplir les informations suivantes : 

  • Titre de votre profil
  • Identifiant de votre compte d'utilisateur Confluence
  • Jeton Confluence
  • URL de votre instance Confluence
  • La clé de l'espace à migrer

migrator-2.png

Pour générer un jeton, cliquez sur le lien « Api Token ». Cela vous redirigera vers la section d'administration de sécurité de votre instance Confluence. Cliquez sur « Create API token » :

token-1.png

Remplissez le nom du jeton et cliquez sur Create :

token-2.png

Copiez le jeton API et assurez-vous de le conserver quelque part en sécurité. Vous ne pourrez plus voir le jeton dans votre instance de Confluence :

token-3.png

Retournez à votre instance XWiki, remplissez le jeton et sauvegardez le profil de migration. Cela vous redirigera vers une étape intermédiaire, où vous pourrez tester la connexion avec votre instance Confluence.

migrator-3.png

Si la connexion est réussie, lancez la migration. Dans le cas contraire, vérifiez à nouveau les informations renseignées dans le profil de migration et vérifiez que vous êtes toujours connecté à votre instance Confluence.

Si vous utilisez une installation XWiki supérieure à la version 14.x, la connexion à l'instance Confluence n'est pas nécessaire, car la conversion de la longue hiérarchie se fait automatiquement grâce à une nouvelle fonctionnalité de base.

migrator-4.png

1ʳᵉ étape

La première étape de la migration est consacrée à la préparation de l'instance XWiki du point de vue de l'infrastructure et des performances.

migrator-new-prerequisistes.png

La première partie de ce processus n'est nécessaire que si vous exécutez la migration sur une instance installée sur site.

1. Opérations qui nécessitent l'accès au fichier de configuration de XWiki

  • augmenter la quantité de mémoire allouée à votre instance XWiki
  • trouver le fichier xwiki.properties dans votre instance XWiki et définir notifications.enabled et notifications.emails.enabled comme false

migrator-5.2.png

Relancez votre instance XWiki.

2. Opérations effectuées dans l'instance XWiki

  • allez dans votre profil, dans la section Notifications et choisissez Never pour la surveillance automatique des pages. Désactivez également toute notification d'application que vous avez configurée.

notifications-1.png

notifications-1.2.png

  • désactivez manuellement les filtres de notification ou cliquez sur Clean Notification Preferences (Nettoyer les préférences de notification) pour effacer automatiquement les filtres de notification définis.

notifications-2.png

Vous pouvez réactiver et configurer les notifications à votre convenance une fois la migration effectuée.

  •  désactivez les listeners de notifications en cliquant sur chacun des 4 liens de cette section et en faisant passer le listener de ON à OFF.

Vous pouvez réactiver les listeners de notifications une fois la migration effectuée.

2ᵉ étape

Cette étape va effectuer une analyse de votre instance Confluence pour vérifier les hiérarchies qui sont trop longues et les pages qui ont déjà été importées dans votre instance XWiki.

Pour lancer l'analyse, cochez les cases et cliquez sur Start analysis.

migrator-6.png

Les hiérarchies trop longues peuvent ne pas être importées correctement. Si ce script trouve des hiérarchies trop longues, nous suggérons de raccourcir le nom des pages dans ces hiérarchies dans l'instance Confluence avant l'importation.

Si vous utilisez une installation XWiki supérieure à la version 14.x, vous pouvez sauter cette étape, car la conversion de la longue hiérarchie se fait automatiquement grâce à une nouvelle fonctionnalité de base.

3ᵉ étape

Cette étape vous accompagnera dans l'exportation de Confluence.

migrator-7.png

Une fois l'étape 2 effectuée, allez dans l'espace Confluence que vous souhaitez migrer et cliquez sur Space Settings dans le panneau à gauche. 

space-export-11.png

Cliquez sur Export space et choisissez le format XML.

space-export-2.png

space-export-3.png

Choisissez les pages que vous souhaitez exporter, téléchargez le fichier zip et retournez dans l'instance XWiki.

4ᵉ étape

C'est à cette étape que votre contenu Confluence est importé dans l'instance XWiki.

Cliquez sur Choose files et sélectionnez votre exportation zip de Confluence.

migrator-8.png

Si vous migrez sur une instance installée sur site, vous pouvez procéder à l'étape alternative suivante : Ne pas télécharger l'archive d'exportation de Confluence, mais cliquer sur Advanced setup, trouver le champ The source et remplir le chemin d'accès du fichier sur votre machine :

migrator-9-1.png

Cliquez sur Import et vérifiez les journaux.

migrator-10.png

5ᵉ étape

Au cours de cette étape, les documents importés sont vérifiés pour s'assurer que toutes les pages mères sont valides.

Lancez les tests et cliquez sur Fix invalid parents si vous trouvez des pages contenant des erreurs.

migrator-11-1.png

Si vous utilisez une installation XWiki supérieure à la version 14.x, vous pouvez sauter cette étape, car la conversion de la longue hiérarchie se fait automatiquement grâce à une nouvelle fonctionnalité de base.

6ᵉ étape

À ce stade de la migration, vos pages seront importées sous un seul parent. Cette étape organisera vos documents dans les mêmes hiérarchies que dans Confluence.

Tout d'abord, cliquez sur Compute Plan et regardez la hiérarchie proposée. Vous pouvez choisir de désélectionner certains documents afin qu'ils ne soient pas déplacés sous les pages mères.

migrator-12.png

Une fois que le plan est en ordre, cliquez sur Execute plan. Vos pages seront déplacées sous les parents corrects.

migrator-13.png

Une fois la migration des pages imbriquées achevée, cliquez sur Finish pour clôturer ce profil de migration. Vous serez redirigé vers la page de profil et vous verrez le document nouvellement importé et organisé dans l'arbre de navigation à gauche.

D'autres mentions

  • Vous pouvez voir tous les profils de migration qui ont été créés dans <yourxwiki>/xwiki/bin/view/Confluence/Migrator/Profiles/.
  • Un rapport complet sur toutes les analyses effectuées est disponible dans votre profil de migration.
  • Si vous souhaitez relancer une migration, cliquez sur le bouton Restart migration, au-dessus des flèches indiquant les étapes de la migration. Cela supprimera toutes les pages qui ont été importées via le profil de migration courant.

Meilleures pratiques

1. Lors de la migration, créez une feuille avec tous les espaces que vous souhaitez importer et l'état de chacun d'entre eux. Voici un exemple : 

migration-execution-best-practice.png

2. Si un espace a des pages qui n'ont pas été correctement importées (ça arrive généralement s'il y a des caractères spéciaux non pris en charge dans le contenu ou si la page est créée par un éditeur non pris en charge), veuillez corriger les pages dans Confluence. Ensuite, créez une exportation personnalisée (avec les pages corrigées), puis les importer via un deuxième profil dans XWiki. Par exemple, disons que nous faisons une première importation pour l'espace DOC, via le profil Documents 1 et que nous avons 120 pages au total, mais que 3 pages ont été ignorées parce qu'elles contenaient des caractères non pris en charge. Après avoir corrigé les pages dans Confluence, nous exportons l'espace DOC, via l'exportation personnalisée, nous sélectionnons uniquement les 3 pages corrigées et nous nommons notre exportation DOC2. Ensuite, du côté de XWiki, il faut créer le profil Documents 2 et importer l'export DOC2, contenant les 3 pages corrigées.

3. Si vous utilisez XWiki à partir de la version 14.x, vous pouvez sauter la connexion à Confluence et les étapes 2 et 5.

4. Après avoir lancé l'importation (étape 4) et la migration des pages imbriquées (étape 6), assurez-vous que les tâches sont terminées avant d'en lancer une autre. Pour vérifier si les tâches d'importation ou de migration des pages imbriquées ont été effectuées, assurez-vous que les conditions suivantes soient remplies : 

  • vous avez reçu les messages Current conversion - Done et respectivement The plans have been executed!
  • vous ne voyez pas de nouveaux processus apparaître dans le navigateur Network.

migrator-process.png

Méthode manuelle

Prérequis

  • Une instance Confluence : Assurez-vous d'avoir le droit d'exporter des pages sur cette instance afin de pouvoir effectuer l'exportation.
  • Une instance XWiki : Vous aurez besoin d'un serveur avec XWiki installé et d'accès à ce serveur.
    • Une installation réalisée sur site : Pour en savoir plus et choisir la méthode d'installation qui vous convient, vous pouvez consulter notre guide d'installation.
    • Une installation réalisée par des spécialistes d'XWiki, sur un serveur qui vous appartient. En effet, si vous ne souhaitez pas vous charger de l'installation, mais souhaitez tout de même disposer de vos données sur site, les ingénieurs de XWiki SAS peuvent réaliser son installation et sa configuration pour vous.
    • Une installation cloud : Si votre instance est hébergée sur un cloud, vous devez contacter l'équipe de support qui pourra ajouter les fichiers exportés sur le serveur.

Préparez vos fichiers

  • Exportez le contenu de Confluence que vous souhaitez ensuite importer dans XWiki au format XML.
  • Uploadez le fichier zip obtenu sur le serveur XWiki. Assurez-vous qu'il est accessible à l'utilisateur qui a lancé le processus Java. Si votre instance est hébergée sur le cloud, vous pouvez contacter l'équipe de support qui peut s'en charger pour vous.
  • Installez les extensions Confluence XML module et Filter Streams Converter Application sur votre instance XWiki en utilisant le Gestionnaire d'extensions.
    • Pour Filter Streams Converter Application, assurez-vous de sélectionner la version équivalente à votre version de XWiki.
  • Si vous avez des Espaces dans votre instance Confluence, créez leur équivalent en sous-wikis dans votre instance XWiki.

Lancez la migration

Après avoir installé les deux extensions ci-dessus, cliquez sur l'entrée "Filter Stream Converter" sur le menu d'Application XWiki.

Suivez les instructions comme indiqué dans la capture d'écran ci-dessous. Cette extension n'est pas traduite, mais nous allons vous guider ici, si besoin n'hésitez pas à traduire la documentation.

  • Choisissez l'input type "Confluence XML input stream (confluence+xml)"
  • Remplissez dans le champ The Source "file:" suivi du chemin du fichier zip des données Confluence situé sur la machine sur laquelle XWiki est installé.
  • Choisissez l'output type "XWiki instance output stream (xwiki+instance)" pour importer le contenu du fichier dans XWiki.

filterconverter.png

Une fois ces étapes terminées, cliquez sur le bouton Convert. Vous verrez ensuite la progression de la conversion s'afficher.

Cela ressemblera à ceci :

file-streams-conversion-done.png

Après un rafraîchissement de la page, vous retrouverez votre contenu dans le panneau de navigation (par défaut sur la gauche de l'écran).

Organisez le nouveau contenu

  • Voici venu le moment idéal pour s'attarder un peu sur l'architecture de votre nouvelle instance XWIki. Une bonne organisation du contenu est un des prérequis au succès de votre projet. Elle permet à vos utilisateurs de créer, trouver et partager l'information facilement. Vous pouvez présenter les sections principales de votre wiki, décider si vous allez par la suite utiliser des sous-wikis ou des espaces d'un même wiki, créer une application App Within Minutes, réfléchir aux liens entre vos documents, tags, hiérarchie des pages. Vous pouvez aussi en profiter pour éventuellement faire du nettoyage et archiver les documents qui n'ont pas été utilisés récemment.
  • Une fois mis en place la structure de vos pages sur l'instance XWiki, utilisez l'extension Nested Pages Migrator pour créer l'arborescence de vos pages. Certaines pages deviendront alors "pages mères" (espaces) et auront des "pages enfant".
  • Enfin, faites un bilan rapide du résultat obtenu et déplacez les pages là où elles conviennent le mieux.

Après la migration

Résoudre les éventuels problèmes de compatibilité

Dans XWiki et Confluence, vous avez la possibilité d'utiliser des macros. XWiki offre plus de 170 macros pour mettre en forme le contenu, afficher des données sous une certaine forme, créer des tableaux de bord, entre autres. Certaines macros Confluence ont leur équivalent dans XWiki, d'autres non. Dans le cas des macros inexistantes dans XWiki, vous allez devoir créer des macros et faire la connexion, ou les recréer dans XWiki.

Vous pouvez lancer une recherche Database Search pour vérifier combien de fois sont utilisées les macros que vous avez importées de Confluence. Cela pourra vous aider à choisir si vous devez les réécrire ou non.

Gestion des utilisateurs et des droits

Vous pouvez maintenant recréer les utilisateurs et le schéma des droits avec toute la finesse que permet le Système de gestion des droits XWiki. Cela signifie définir qui peut voir, commenter, modifier, écrire des scripts, supprimer, administrer ou programmer, par groupes ou par utilisateur. Et ce au niveau global, pour un sous-wiki, ou par espace, voire pour chaque page.

Ensuite, vous pourrez mettre en place éventuellement une méthode d'authentification alternative comme l'Active Directory, le login par réseau social, un SSO ou autre authentificateur personnalisé.

Encore besoin d'aide ?

Les architectes de XWiki SAS peuvent vous aider à migrer et organiser votre contenu Confluence dans votre nouvelle instance XWiki ou créer les macros relais dont vous avez besoin. De plus, nous proposons des services de conseildéveloppement ou design, à travers desquels nous configurons et personnalisons votre instance de manière à répondre parfaitement à vos besoins.

Une fois que XWiki est en place, jetez un coup d’œil à nos offres de support qui vous apportent toute l'aide technique requise pour atteindre vos objectifs. Notre service de support vous garantie le bon fonctionnement de votre instance, car nous avons une équipe dédiée qui corrige les problèmes rencontrés, et peut vous assister dans l'utilisation de votre wiki.

Souhaitez-vous une évaluation de votre projet ?

PRENDRE RENDEZ-VOUS AVEC UN SPÉCIALISTE XWIKI
 

Articles similaires :