Mise en œuvre de l’Import / Export

JCMS 5.7.2 introduit un mécanisme d'import/export XML facilitant l'échange de contenus entre applications JCMS. Cette nouvelle fonctionnalité permet d'élaborer de nouveaux modes de diffusion des contenus, comme par exemple :

• Intranet/Extranet : production et validation de contenus sur l'intranet puis diffusion après validation sur le site Internet
• Référentiel commun : production de publications dans un référentiel commun et import total ou partiel par des sites partenaires.

L'import/export se base sur un format d'échange XML simple qui, complété avec l'API JCMS, rend possible le développement de nouveaux usages. Par exemple :

• Import de contenus issus de sources externes (base de données, flux RSS, sites web, ...)
• Export de contenus vers des sites partenaires
• Reprise de contenus existants

Cet article décrit comment mettre rapidement en œuvre l'import/export entre deux webapps JCMS 5.7.3.

1. Configuration

Après avoir installé et configuré deux webapps JCMS 5.7.3, renommez-les respectivement exportateur (celle qui exportera ses contenus) et importateur (celle qui les importera). Ces deux webapps doivent disposer des mêmes types de contenu Brève et Article.

Démarrez les deux webapps.

1.1 Configuration de l'Exportateur

Sur l’Exportateur, allez dans l'éditeur de propriétés. Dans l'onglet Site, renseignez le nom et l'URL d'accès de la webapp.

Dans l'onglet Import/Export, activez l’export. Si la webapp d’import se situe sur une autre plage d'adresses IP que 192.168.*, entrez son adresse IP dans le champ Filtre adresse IP.

Fig. 1. Propriétés de l’Exportateur.

1.2 Configuration de l'Importateur

Sur l’Importateur, allez dans l'éditeur de propriétés. Dans l'onglet Site, renseignez le nom et l'URL d'accès de la webapp.

Dans l'onglet Import/Export, activez l'import. Laissez les autres propriétés d’import à leur valeur par défaut.

Fig. 2. Propriétés de l’Importateur.

2. Import/export d’une publication

2.1 Export d’une publication

Sur l’Exportateur, créez une nouvelle Brève attachée à une catégorie (p. ex. Navigation > Demo export).

En utilisant le menu contextuel d’édition, sélectionnez Export XML. La vue d’export XML de la brève s'afficher. Copiez cette URL.

Fig. 3. Exemple d’export XML d’une brève.

2.2 Import d’une publication

Sur l’Importateur, allez dans l’Espace d’administration puis dans Gestion des imports. Cliquez sur le bouton Importer depuis une URL. Dans le champ texte, collez l’URL d’export XML de la brève et cliquez sur le bouton Importer.

Fig. 4. Interface d’import depuis une URL.

Un message indique que l’import s’est correctement déroulé et une nouvelle ligne a été ajoutée dans le journal des imports.

Fig. 5. Journal des imports après un premier import.

Si vous rencontrez un problème de connexion et que vous avez configuré un proxy de sortie, vérifiez que l'adresse IP de la webapp d'export est bien prise en compte par la clause d'exclusion (Sauf pour) de la configuration du proxy de sortie.

Allez dans l’Espace de travail par défaut. La brève importée apparait en italique avec l’icône . Une nouvelle branche de catégorie Import a été créée. Elle contient une première catégorie représentant la webapp source (Exportateur) puis les catégories liées à la brève importée (Navigation > Démo Export).

Fig. 6. Affichage de la brève importée.

Cliquez sur le menu contextuel d’édition de cette publication. Un nouveau menu Import vous permet d’agir sur cette donnée importée (réimporter, conversion en publication locale, gestion des conflits), de consulter cette publication sur son site d’origine et de connaître les métadonnées d’import (date, source, …).

Fig. 7. Accès aux métadonnées de la brève importée via le menu contextuel d’édition.

3. Import/export d’un ensemble de publications

Après avoir importé une brève unitairement, nous allons importer un ensemble de publications.

3.1 Export d’un ensemble de publications

Allez sur l’exportateur :

1. Créez deux nouveaux articles et placez-les dans la même catégorie que la brève précédemment créée ;
2. Assurez-vous que les deux articles soient dans l’état publié ;
3. Faites aussi une mise à jour du titre de la brève.

Allez dans l’interface de recherche avancée, sélectionnez la catégorie dans laquelle se trouve les trois contenus et lancez la recherche. Cliquez sur le lien XML pour obtenir l’URL d’export XML de cette requête. Copiez cette URL.

Fig. 8. Export d’un ensemble de contenus.

3.2 Import d’un ensemble de contenus

Sur l’Importateur, allez dans la Gestion des imports, cliquez sur le bouton Importer une URL, copiez l’URL d’export et cliquez sur le bouton Importer. Un message indique que 3 données ont été traitées : 2 créations (les deux articles) et une mise à jour (la brève).

Fig. 9. Journal des imports après l’import d’un ensemble de contenus.

Allez dans l’Espace de travail par défaut, les 2 nouveaux articles sont présents et le titre de la brève a été mis-à-jour.

Fig. 10. Liste des nouveaux contenus importés.

4. Ajout d’une source d’Import

Les précédents imports ont nécessité une intervention manuelle. Pour automatiser cette tâche, nous allons maintenant mettre en œuvre une Source d’import qui va permettre de déclencher un import régulier des nouveaux contenus de l’Exportateur.

Sur l’Importateur, allez dans la Gestion des imports et cliquez sur le bouton Ajouter une source. Renseignez le formulaire :

• Donnez un nom à la source (p. ex. Exportateur) ;
• Indiquez l’URL à importer (la même que nous avons utilisé pour l’export des résultats de la recherche) ;
• Laissez les options d’import par défaut ;
• Activez la planification et paramétrez une fréquence de 10 minutes ;
• Cliquez sur le bouton Enregistrer.

Fig. 11. Formulaire d’édition d’une source d’import.

Un nouvel onglet Sources apparait au même niveau que le journal des imports et liste toutes les sources d’import. A partir de maintenant, toutes les 10 minutes l'Importateur déclenchera une requête d’import vers l'Exportateur.

Vous pouvez aussi utiliser la source pour déclencher manuellement un import en cliquant sur le bouton Importer (import incrémental) ou sur le bouton Importer en totalité (import complet). L'import complet importe tous les contenus correspondant aux critères de recherche définis dans l'URL. Les contenus déjà importés seront ignorés (sauf si ils ont été mis-à-jour). L'import incrémental envoie à l'Exportateur la date du dernier import et ne reçoit dans le flux XML que les nouveaux contenus et les contenus mis-à-jour

Fig. 12. Affichage de la source d’import.

5. Import des fichiers attachés

En plus d’importer les principaux champs des publications ainsi que leur catégories, le mécanisme d’import peut déclencher l’import des fichiers attachés à la publication, quelque soit le mode de référencement de ces fichiers (champ Document, Image, Média, images dans une zone de texte riche ou dans une zone Wiki). Pour cela, le flux XML contient l’ensemble des URL des fichiers à télécharger.

Pour illustrer l’import des fichiers attachés, allez sur l’Exportateur et ajoutez une image dans le champ contenu de la brève.

Sur l’Importateur, déclenchez l’import via la source Exportateur (ou attendez 10 minutes).

Fig. 13. Journal des imports après l’import de la brève et de son image.

Allez dans l’Espace de travail par défaut, la brève a été mise à jour et un Document correspondant à l’image attachée à la brève a été créé.

Fig. 14. Liste des contenus après import de la brève et de son image.

6. Gestion des conflits

Un conflit peut survenir lors d’un réimport si une publication importée a été modifiée concurremment sur les deux webapps. JCMS détecte ces conflits et les traitent de deux manières selon la nature de la modification locale :

1. Modification des méta-données : ce type de conflit survient si les métadonnées ont été localement modifiées (auteur, espace de travail, catégories, droits, dates de publication, état du workflow, …). JCMS résout automatiquement ces conflits. Les métadonnées locales sont ajoutées à la nouvelle version importée.
2. Modification du contenu: ce type de conflit survient si la modification concerne l’un des champs importés (titre, champ textuel, nombre, …). Dans ce cas, JCMS ne met pas à jour le contenu mais produit une copie de conflit. Cette copie contient la nouvelle version importée et permet de faire une réintégration manuelle.

6.1 Fusion automatique des mises-à-jour

Pour illustrer la fusion automatique des mises-à-jour, allez sur l’Exportateur et modifiez le titre de la brève. Puis allez sur l’Importateur et ajoutez de nouvelles catégories locales à la même brève. De retour dans la liste des contenus, la brève apparait avec l’icône qui indique que le contenu a été localement modifié. Déclenchez un réimport par le menu contextuel d’édition. JCMS fusionne les métadonnées locales avec la nouvelle version importée : le titre de la brève est mis-à-jour et elle contient les catégories locales et les catégories importées.

Fig. 15. Liste des contenus après un import avec fusion automatique des métadonnées.

6.2 Résolution manuel d’un conflit

Pour illustrer la résolution manuelle d’un conflit sur le contenu, allez sur l’Exportateur et modifiez à nouveau le titre de la brève. Puis allez sur l’Importateur et modifiez le titre et le chapeau de la brève. Déclenchez un réimport par le menu contextuel d’édition. Le message d’information indique qu’il y a eu un conflit, le titre de la brève n’a pas été changé et l’icône apparait pour indiquer qu’il y a un conflit.

Fig. 16. Liste de contenus après détection d’un conflit sur le contenu.

Cliquez sur l’icône (ou sélectionner Afficher les conflits par le menu contextuel) afin de comparer la version actuelle et la nouvelle version importée. Le texte ajouté par la nouvelle version importée apparait en orange, celui de la version actuelle apparait en vert barré.

Fig. 17. Comparaison entre la nouvelle version importée et la version actuelle.

Pour ignorer les changements locaux et repartir sur la nouvelle version importée, il suffit de cliquer sur le bouton Remplacer par la version importée.

Pour ignorer la nouvelle version importée, il suffit de cliquer sur le bouton Conserver la version actuelle.

Si par contre, vous souhaitez fusionner les deux versions en prenant le nouveau titre mais en gardant le texte du chapeau modifié localement, il faut éditer la version actuelle et recopier manuellement le nouveau titre. Pour cela, éditez la nouvelle version importée, copier le texte du titre. Puis ouvrez la version actuelle et collez-le dans le titre. Une fois enregistrée, la page de comparaison n’indique plus de différences sur le titre. Vous pouvez alors valider la résolution du conflit en cliquant sur le bouton Conserver la version actuelle.

Fig. 18. Comparaison entre la nouvelle version importée et la version actuelle après la résolution manuelle.

7. Conversion en publication locale

A chaque nouvel import, les publications précédemment importées sont susceptibles soit d’être mises-à-jour soit d’engendrer une copie de conflits. Si vous souhaitez qu’une publication importée n’évolue plus, vous pouvez la transformer en publication locale. Elle perdra alors toutes ses métadonnées d’import (source, date d’import, …) et sera sortie de l’index des publications importées. Si lors d’un import, JCMS reçoit une nouvelle version de cette publication, ceci entrainera la création d’une nouvelle publication.

Pour convertir une publication importée en publication locale, dans la section Import du menu contextuel, sélectionnez Convertir en publication locale. L’icône marquant qu'il s'agit d'une publication importée disparait et le titre de la publication apparait comme une publication locale.

Fig. 19. Affichage de la brève après sa conversion en publication locale.

8. Contraintes techniques

Les webapps s’échangeant des publications par le mécanisme d’import/export doivent respecter plusieurs contraintes techniques :

• Elles doivent utiliser la même langue principale ;
• Elles doivent avoir un URID distinct (cette contrainte devrait être levée dans une prochaine version de JCMS) ;
• Les horloges des machines doivent être synchronisées avec un protocole tel que NTP (si le protocole d’import incrémental est utilisé) ;
• Il est possible d’utiliser le protocole de réplication JSync sur les webapps d’import. Sur les webapp d’export, si JSync est utilisé les écritures doivent être centralisées pour permettre l’import incrémental ;
• La webapp d’import doit disposer des types de publication qu’elle importe.

9. Evolutions futures

Le mécanisme d’import/export fourni avec JCMS 5.7.3 est opérationnel et stable. Cependant, il existe quelques limitations qui feront l’objet d’évolution dans les prochaines versions de JCMS.

9.1 Evolution sur l’Export

Sources d’export

Actuellement, pour exporter un ensemble de publication, on utilise une requête de recherche. Ceci est très générique et permet d’exporter tout type de contenu. Néanmoins, sauf à effectuer des développements spécifiques (à base d’ExportPolicyFilter et de QueryFilter) il n’est pas possible de restreindre ce qui est exportable. De plus, ceci nécessite que l’importateur connaisse la structuration de contenu qu’il souhaite importer. Si cette structuration évolue, tous les importateurs doivent mettre à jour l'URL d’export. Dans une prochaine version de JCMS, il sera possible de définir des Sources d’export qui masqueront le détail de la requête d'export. Par exemple, on pourra définir une source d’export New associée à une certaine requête locale (p. ex. les Articles de la catégorie News). Les importateurs utiliseront cette source pour faire leur import. Ainsi, l’exportateur pourra faire évoluer la requête associée à cette source (p. ex. ouvrir à d'autres catégories) sans que les importateurs aient besoin de mettre à jour l’URL d’export.

Export des fichiers attachés

Dans JCMS 5.7.3, l’export des fichiers se fait sous-forme d’URLs de téléchargement attachées à chaque donnée exportée. C’est à la charge de l’importateur d’effectuer les téléchargements. Il est prévu de faire une évolution permettant de grouper dans une archive Zip le fichier XML d’export et l’ensemble de fichiers associés à cet export. La fonction d’import sera mise-à-jour pour prendre en charge ces fichiers Zip.

Authentification

En standard, seules les publications publiques (c’est-à-dire dans un état visible et consultable sans être authentifié) peuvent être exportées. Il est néanmoins possible d’ajouter dans l’URL d’export le login et le mot de passe d’un utilisateur authentifié afin que l’export se fasse en son nom. Dans une prochaine version, un mécanisme permettra de déclencher des imports authentifiés sans avoir à fournir les identifiants du compte utilisateurs.

Export des publications importées

Les publications importées ne sont pas exportables. Cette limitation devrait être levée dans une prochaine version du mécanisme d’import.

9.2 Evolution sur l’Import

Rétablissement des liens

Avec la version actuelle de l’import, les liens entre publications importées ne sont pas rétablis. Par exemple, si l’on importe des FaqEntry elles ne seront pas rattachées à leur Faq. De même si l’on importe deux publications qui se référencent au travers d’un lien dans un champ wysiwyg ou wiki, ce lien ne sera pas rétabli. Cette fonctionnalité sera prise en charge par la prochaine version du mécanisme d’import.

Arrêt des mises-à-jour

Une publication importée est susceptible d’être mise-à-jour lors de chaque import. La conversion en publication locale permet de conserver un état de cette publication mais les nouvelles versions seront à nouveau importées en tant que nouvelle publication. Il est prévu de proposer une option permettant d’indiquer qu’une publication ne doit plus être réimportée.