Partager du contenu entre plusieurs Drupal c'est possible grâce à Entity Share !

Dans le cadre de ma mission au sein des équipes Orange en charge de la Boutique Pro, j'ai été amené à devoir mettre en place un PIM basé sur Drupal. L'une des problématiques principales fut le partage des entités.

Heureusement, un module contrib Drupal existe déjà. Son nom, Entity Share : https://www.drupal.org/project/entity_share

Nous allons voir ce que c'est Entity Share, comment le configurer et comment l'utiliser.

Entity Share, c'est quoi ?

Entity Share est un module contrib Drupal qui permet de synchroniser des entités de même type entre plusieurs Drupal. Il utilise JSON:API afin d'effectuer la synchronisation.

Entity Share se découpe en 2 sous modules principaux :

• Entity Share Server : Ce module permet d'exposer à des client Entity Share des listes d'entités par type (avec filtrage et tri possible) à travers ce qu'on appel des canaux.
• Entity Share Client : Ce module permet de synchroniser des entités depuis un serveur Entity Share.
  Pour fonctionner il est constitué de 2 configuration :
  • Site web distant (Remote website) : Il s'agit du lien vers le site Drupal qui est le serveur Entity Share. On peut aussi configurer une méthode d'authentification.
  • Configuration d'import (Import config) : Il s'agit comme son nom l'indique de la configuration d'import. C'est à dire comment ces données vont être analysées et traitées durant l'import (permet de déterminer si on doit ou non synchroniser une entité par exemple). C'est justement à ce niveau là qu'on va intervenir afin d'étendre Entity Share à travers des plugins, aussi appelé Processor dans la configuration.

Avec ces 2 composants, 2 Drupal peuvent partager des entités (à partir du moment où elles sont du même type).
Il est à noter qu'un client peut être serveur en même temps et vice versa.

Par serveur, on entend ici fournisseur de données/entités. Et par client, celui qui requête le serveur et qui réceptionne les données/entités.

Comment configurer Entity Share ?

Comme nous l'avons vu précédemment, Entity Share se découpe en 2 parties. Nous devrons donc configurer chacune d'elle.

Entity Share Server

Côté serveur, nous n'avons que les canaux (channels) à configurer.
Un canal, c'est une liste d'entités filtrées par Entity Type et Bundle. On peux aussi ajouter des critères de filtrage supplémentaires, des critères de recherche (utilisés par le client) et des critère de tri.

La configuration est simple :

1. Dans le Backoffice Drupal, se rendre sur Configuration > Services Web > Entity Share > Cannaux (/admin/config/services/entity_share/channel).

   Image

   

2. Ajouter ou éditer un canal.

   Image

   
3. Configurer le canal.
   1. Indiquer un label.
   2. Renseigner l'Entity Type que doit remonter le canal.
   3. Renseigner le Bundle que doit remonter le canal.
   4. Indiquer le nombre d'entités par page que le canal remontra.
   5. Configurer les droits d'accès :
      1. Autoriser uniquement les utilisateurs avec la permission Drupal.
      2. Autoriser certains rôles.
      3. Autoriser une liste donnée d'utilisateurs.

Image

Les critères de filtrage, recherche et tri ne sont paramétrables qu'une fois le canal créé.
Je n'ai cependant pas eu l'occasion d'approfondir cette partie de la configuration des canaux.

Entity Share Client

Côté client, nous avons 2 choses à configurer :

• Le site web distant (remote website) : Le ou Les Drupal fournisseurs (Entity Share serveur) que notre client va pouvoir contacter afin de se synchroniser.
• La configuration d'imports (import config) : La ou Les configurations d'import. Il s'agit de comment les données/entités vont être synchronisées.

Remote websites

La configuration des sites web distants est simple :

1. Dans le backoffice, se rendre dans Configuration > Services Web > Entity Share > Sites web distants (/admin/config/services/entity_share/remote).

   Image

   

2. Ajouter ou éditer une site web distant.

   Image

   
3. Configurer le site web distant.
   1. Indiquer un label.
   2. Renseigner l'URL du Drupal Entity Share serveur.
   3. Configurer la méthode d'autorisation.
      (On peut notamment opter pour "Basic authorization" avec le nom d'utilisateur (sur le Drupal Entity Share serveur) et son mot de passe associé afin d'exécuter la requête en tant que cet utilisateur).

Image

C'est tout !

Import config

Les configurations d'import consistent à définir les processors actifs, leur ordre/priorité d'exécution ainsi que leur paramétrage. 
Je vous invite a consulter le billet suivant pour mieux saisir ce que sont les processors Entity Share : https://www.iosan.fr/blog/etendre-entity-share-avec-des-plugins

Ainsi, pour configurer la config d'import il faut :

1. Dans le backoffice, se rendre dans Configuration > Services Web > Entity Share > Import config (/admin/config/services/entity_share/import_config).

   Image

   

2. Ajouter ou éditer une configuration d'import.

   Image

   
3. Configurer la config d'import.

   1. Donner un label et le nombre limite d'entités affichée par page.

      Image

      

   2. Activer les processors souhaités.

      Image

      

   3. Définir l'ordre d'exécution des processors.

      Image

      

   4. Paramétrer les processors paramétrables.

      Image

      

Ainsi, notre configuration d'import est prête !

Comment utiliser Entity Share ?

On a 2 façons principales d'utiliser Entity Share :

• Via le Backoffice Drupal
• En commande Drush

Utilisation manuelle depuis le Backoffice Drupal

L'utilisation manuelle présente plusieurs avantages :

• Visualiser le statut d'une entité (s'il est est synchronisée ou non)
• Synchroniser une ou plusieurs entités spécifiques qu'on sélectionnes manuellement.

Pour lancer une synchronisation manuellement depuis le backoffice il faut :

1. Se rendre sur Content > Entity Share ().
2. Sélectionner le site web distant (le Drupal sur lequel on veut synchroniser).
3. Sélectionner la configuration d'import.
4. Sélectionner le canal qu'on souhaite.
   A ce moment, on verra la liste des entités remontées par ce canal
5. Lancer la synchronisation :
   1. Sélectionner les entités souhaitées.
   2. Cliquer sur "Synchroniser les entités".

Image

Utilisations manuelle en commande Drush

Il existe de commande drush pour Entity Share :

• Une commande pour importer un canal spécifique : 

  www-data@drupalstack_web:~/html$ drush entity-share-client:pull-all --help
  Pull all channels from a remote website.
  
  Examples:
   drush entity-share-client:pull-all site_1 default                                  Pull all channels from a remote website. The "Include count in collection queries" option should be enabled on the 
                                                                                      server website. This option is provided by the JSON:API Extras module.                                             
   drush entity-share-client:pull-all site_1 default --ignore-channel-ids=nodes       Same as above, except the channel "nodes".                                                                         
   drush entity-share-client:pull-all site_1 default --ignore-channel-ids=nodes,terms Same as above, except the channels "nodes" and "terms".                                                            
  
  Arguments:
   remote_id        The remote entity ID.        
   import_config_id The import config entity ID. 
  
  Options:
   --ignore-channel-ids[=IGNORE-CHANNEL-IDS] Comma separated list of channel ids to be ignored. 
  
  Global options:
  -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug 
  -y, --yes            Auto-accept the default for all user prompts. Equivalent to --no-interaction.                      
  -l, --uri=URI        A base URL for building links and selecting a multi-site. Defaults to https://default.             
                       To see all global options, run `drush topic` and pick the first choice.

• Une commande pour importer l'ensemble des canaux du site web distant : 

  www-data@drupalstack_web:~/html$ drush entity-share-client:pull-all --help
  Pull all channels from a remote website.
  
  Examples:
   drush entity-share-client:pull-all site_1 default                                  Pull all channels from a remote website. The "Include count in collection queries" option should be enabled on the 
                                                                                      server website. This option is provided by the JSON:API Extras module.                                             
   drush entity-share-client:pull-all site_1 default --ignore-channel-ids=nodes       Same as above, except the channel "nodes".                                                                         
   drush entity-share-client:pull-all site_1 default --ignore-channel-ids=nodes,terms Same as above, except the channels "nodes" and "terms".                                                            
  
  Arguments:
   remote_id        The remote entity ID.        
   import_config_id The import config entity ID. 
  
  Options:
   --ignore-channel-ids[=IGNORE-CHANNEL-IDS] Comma separated list of channel ids to be ignored. 
  
  Global options:
  -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug 
  -y, --yes            Auto-accept the default for all user prompts. Equivalent to --no-interaction.                      
  -l, --uri=URI        A base URL for building links and selecting a multi-site. Defaults to https://default.             
                       To see all global options, run `drush topic` and pick the first choice.

   

Utilisation automatique

Pour une utilisation automatique nous avons le choix entre 2 solutions (ou de les coupler) :

CRON

Il suffit tout simplement d'ajouter les commandes drush dans les CRON.

Entity Share Websub

Installer et mettre en place le module contrib Entity Share Websub : https://www.drupal.org/project/entity_share_websub

Ce module permet de créer des souscription. C'est à dire que le client signifie au serveur qu'il souhaite notifié lorsqu'une entité est modifiée sur ce dernier. Ainsi, à la réception de cette notification, le client déclenche une synchronisation pour cette entités.

Conclusion

Entity Share est un outils efficace lorsqu'on souhaite partagés des entités entre plusieurs Drupal. Il est facilement extensible ce qui nous laisse une certaine marge de liberté sur son utilisation.

J’espère que ce billet saura vous aidé ou vous informé sur ce qu'est Entity Share !