Manuel utilisateur v1.0.0

  1. Introduction
  2. Exécuter une extraction
    1. Liste des fichiers de définition
    2. Détails d'une extraction
    3. Exécution d'une extraction
    4. Téléchargement des résultats
  3. Définir une extraction
    1. Créer un fichier de définition
    2. Modifier un fichier de définition
      1. Créer un composant de type thesaurus
      2. Créer un composant de type requête
      3. Créer un composant de type compteur
      4. Créer un composant de type table de correspondance
      5. Les clauses
      6. Ajouter des variables de clause
      7. Ajouter des variables pour les colonnes optionnelles
      8. Modifier un nœud
      9. Supprimer un nœud
      10. Sauvegarder ou annuler les modifications
      11. Utiliser l'outil Fichiers de paramètres
    3. Renommer un fichier de définition
    4. Supprimer un fichier de définition

Introduction

Le plugin Extraction permet de définir et exécuter des requêtes élémentaires et de les imbriquer les unes dans les autres. 

Le plugin fournit également une interface graphique permettant de définir facilement une extraction, de l'exécuter et de télécharger les résultats.

Pour pouvoir utiliser le plugin, 2 droits sont nécessaires :

  • Le droit 'Exécuter les extractions' permet d'accéder à la liste des définitions, d'accéder aux informations détaillées d'une extraction donnée, d'exécuter une extraction et de télécharger les résultats des extractions lancées.
  • Le droit 'Modifier les extractions' permet de modifier les extractions existantes, d'en créer de nouvelles ou de les supprimer.

Une extraction est définie par un fichier XML, que l'on appellera par la suite 'fichier de définition'. Ce fichier contient toutes les requêtes, imbriquées ou non, qui seront ensuite exécutées.

Exécuter une extraction

Pour exécuter une extraction, vous devez avoir le droit 'Exécuter les extractions'.

Liste des fichiers de définition

Dans l'onglet Administration, cliquez sur le bouton 'Extractions' :

L'outil 'Extractions' s'ouvre, il contient la liste de tous les fichiers de définition existants. Les fichiers de définition se trouvent dans le répertoire WEB-INF/param/extraction :

Un onglet contextuel 'Extractions' s'affiche également dans le ruban :

Détails d'une extraction

Sélectionnez un fichier de définition et cliquez sur le bouton 'Ouvrir' de l'onglet 'Extractions' :

L'outil 'Détails de l'extraction' s'ouvre, il affiche les différents composants de l'extraction sous forme d'arbre. Le titre de l'outil est le nom du fichier de définition :

Exécution d'une extraction

Dans l'outil 'Extractions', sélectionnez un fichier de définition et cliquez sur le bouton 'Exécuter' de l'onglet 'Extractions'. Vous pouvez également cliquer sur le bouton 'Exécuter' depuis l'outil 'Détails de l'extraction'.

Certains paramètres sont nécessaires à l'exécution d'une extraction. Une boîte de dialogue s'affiche vous permettant de renseigner ces paramètres :

  • Format du résultat : Choisissez le format du fichier de résultat. Vous avez le choix entre XML ou PDF.
  • Feuille de style : Vous pouvez fournir une feuille de style (fichier XSLT) pour personnaliser le fichier de résultat. Les feuilles de styles doivent être placées dans le répertoire WEB-INF/styleshhets/extraction. Si vous avez choisi de générer un résultat au format PDF, il est obligatoire de fournir cette feuille de style.
  • variables de requêtes : Le fichier de définition peut définir des variables utilisées ensuite dans les clauses des requêtes. Les valeurs de ces variables sont des contenus que vous devez fournir en les sélectionnant ici. Regarder la création de variables de clause.
  • colonnes optionnelles : Le fichier de définition peut définir des variables utilisées pour définir les colonnes optionnelles. Pour chaque variable, vous devez indiquer si les colonnes qui en dépendent seront affichées dans le résultat ou non. Regarder la création de variables pour les colonnes optionnelles
  • Adresse email : Lorsque l'extraction sera terminée, un email sera envoyé à l'adresse que vous devez indiquer ici. Si l'extraction a échoué, l'email contiendra un résumé de l'erreur.

Dans l'espace d'administration, vous pouvez planifier une tâche 'Exécuter une extraction'. Les paramètres demandés seront les mêmes que ceux présentés ci-dessus. Les valeurs des variables de requêtes et des colonnes optionnelles sont à fournir au format JSON.


Téléchargement des résultats

Dans l'onglet 'Extractions', cliquez sur le bouton 'Résultats' :

 

L'outil 'Résultats' s'ouvre, il contient la liste de tous les fichiers de résultats existants. Le nom d'un fichier de résultats est construit à partir du nom du fichier de définition et de la date d'exécution :

Pour télécharger un fichier de résultats, sélectionnez le et cliquez sur le bouton Télécharger :

Définir une extraction

Créer un fichier de définition

Dans l'onglet 'Extractions', cliquez sur le bouton 'Nouveau' :

Renseignez le nom du fichier de définition, un nouveau fichier est créé dans le répertoire WEB-INF/param/extraction. L'outil 'Détails de l'extraction' s'ouvre, la racine de l'arbre est présente, ainsi que les nœuds qui permettent de définir des variables de clauses et des colonnes optionnelles. Vous pouvez maintenant créer les composants de votre extraction.

Modifier un fichier de définition

Créer un composant de type thesaurus

Dans l'outil 'Détails de l'extraction', sélectionnez un nœud et cliquez sur le bouton 'Thesaurus' de l'onglet 'Extractions' :


Une boîte de dialogue s'affiche vous permettant de renseigner les informations nécessaires à la création d'un composant de type thesaurus :

  • Nom du tag : Vous pouvez choisir le nom de l'élément XML qui sera créé dans le fichier de résultats pour ce composant. Ce nom doit respecter les règles de nommage des éléments XML. Seuls certains caractères sont autorisés comme les lettres, les chiffres, les tirets, ... Ce champ n'est pas obligatoire, s'il n'est pas renseigné, on utilisera le terme 'thesaurus'.
  • Thesaurus : Liste déroulante avec les noms des thesaurii disponibles. Choisissez le thesaurus sur lequel rechercher des termes. Ce champ est obligatoire.
  • Microthesarus : Liste déroulante avec les noms des microthesaurii disponibles pour le thesaurus choisi. Choisissez le microthesaurus sur lequel rechercher des termes. Si vous changez de thesaurus, ce champ se réinitialise. Ce champ est obligatoire.
  • Niveau maximum : Profondeur maximum à laquelle rechercher les termes spécifiques. L'autopostage descendant permettra de remonter les contenus correspondant aux termes spécifiques de niveaux inférieurs.

Un nœud Thesaurus est créé dans l'arbre, sous le nœud sélectionné.

Créer un composant de type requête

Dans l'outil 'Détails de l'extraction', sélectionnez un nœud et cliquez sur le bouton 'Requête' de l'onglet 'Extractions' :

Une boîte de dialogue s'affiche vous permettant de renseigner les informations nécessaires à la création d'un composant de type requête :

  • Nom du tag : Vous pouvez choisir le nom de l'élément XML qui sera créé dans le fichier de résultats pour ce composant. Ce nom doit respecter les règles de nommage des éléments XML. Seuls certains caractères sont autorisés comme les lettres, les chiffres, les tirets, ... Ce champ n'est pas obligatoire, s'il n'est pas renseigné, on utilisera le terme 'query'.
  • Clauses : Champ texte contenant une requête solr. Vous pouvez renseigner plusieurs requêtes, en cliquant sur le bouton '+'. Pour plus d'informations, Regarder les explications sur les clauses.
  • Groupes : Vous pouvez choisir de grouper les résultats d'une requêtes en fonctions des champs des contenus remontés. Les champs sont séparés par des virgules. L'autocomplétion vous permettra de renseigner les champs disponibles pour les types de contenu sélectionnés.
  • Type de requête : Spécifiez si vous souhaitez utiliser une requête enregistrée ou créer la requête de toutes pièces.

En fonction du type de requête sélectionné, de nouvelles informations doivent être renseignées :

Si vous souhaitez utiliser une requête sauvegardée :

  • Requête enregistrée : Liste déroulante avec les noms des requêtes enregistrées disponibles.
  • Utilisation des colonnes : Vous pouvez choisir de n'utiliser que les colonnes définies par la requête enregistrée, surcharger ces colonnes ou ajouter des colonnes à celles de la requête enregistrée.
  • Colonnes : Indiquez les champs qui doivent apparaitre dans le fichier de résultats pour ce composant. Les champs sont séparés par des virgules. Pour rendre une colonne optionnelle, renseignez entre parenthèse le nom de la variable dont l'affichage de la colonne dépend. Exemple :

    metadata_A (optianalA),metadata_B

    Regarder la création de variables pour les colonnes optionnelles. L'autocomplétion vous permettra de renseigner les champs disponibles pour les types de contenu sélectionnés.

  • Utilisation du tri : Vous pouvez choisir de n'utiliser que le tri défini par la requête enregistrée, surcharger ce tri ou ajouter des champs à la suite de ceux de la requête enregistrée.
  • Tri : Indiquez les champs sur lesquels les résultats doivent être triés. Les champs sont séparés par des virgules. Par défaut, le tri est ascendant. Vous pouvez renseigner l'ordre entre parenthèse. Exemple :

    metadata_A (DESC),metadata_B (ASC), metadata_C

Si vous souhaitez créer une requête de toutes pièces :

  • Types de contenu : Arbre contenant de types de contenu disponibles. Vous pouvez sélectionner plusieurs types de contenus. Ce champ est obligatoire.

  • Colonnes : Indiquez les champs qui doivent apparaitre dans le fichier de résultats pour ce composant. Les champs sont séparés par des virgules. Pour rendre une colonne optionnelle, renseignez entre parenthèse le nom de la variable dont l'affichage de la colonne dépend. Exemple :

    metadata_A (optianalA),metadata_B

  • Tri : Indiquez les champs sur lesquels les résultats doivent être triés. Les champs sont séparés par des virgules. Par défaut, le tri est ascendant. Vous pouvez renseigner l'ordre entre parenthèse. Exemple :

    metadata_A (DESC),metadata_B (ASC), metadata_C

 

 


Un nœud Requête est créé dans l'arbre, sous le nœud sélectionné.

Créer un composant de type compteur

Dans l'outil 'Détails de l'extraction', sélectionnez un nœud et cliquez sur le bouton 'Compteur' de l'onglet 'Extractions' :

Une boîte de dialogue s'affiche vous permettant de renseigner les informations nécessaires à la création d'un composant de type compteur.

Un composant de type compteur correspond à un composant de type Requête. Les paramètres à renseigner sont globalement les mêmes.

La différence vient du fait que pour un composant de type compteur, on ne remonte que le nombre de contenus renvoyés par la requête. Aucun paramètre correspondant aux colonnes et au tri ne sont donc demandés.

Un nœud Compteur est créé dans l'arbre, sous le nœud sélectionné.

Créer un composant de type table de correspondance

Dans l'outil 'Détails de l'extraction', sélectionnez un nœud et cliquez sur le bouton 'Requête de correspondance' de l'onglet 'Extractions' :

Une boîte de dialogue s'affiche vous permettant de renseigner les informations nécessaires à la création d'un composant de type requête de correspondance.

Un composant de type requête de correspondance correspond à un composant de type Requête. Les paramètres à renseigner sont globalement les mêmes.

La différence vient du fait que les contenus renvoyés par la requête d'un composant de type requête de correspondance ne sont pas affichés. La requête de correspondance est invisible. De ce fait, aucun paramètre correspondant aux groupe, aux colonnes et au tri ne sont demandés. Le paramètre concernant le nom du tag n'est pas demandé non plus.

Un nœud Requête de correspondance est créé dans l'arbre, sous le nœud sélectionné.

Les clauses

Une clause peut contenir des variables, définies dans un autre nœud de l'arbre. Regarder la création de variables de clause. Le nom de la variable est mise entre accolades, précédées du signe '$'. Exemple :

${le_nom_de_ma_variable}

Une clause peut également servir à faire une joiture avec les composants parents. Le lien vers le composant parent est mis entre accolades, précédé du signe '$'. Utilisez la notation '..' pour remonter au parent direct. Pour remonter aux parents plus lointains, utilisez autant de fois que nécessaire "../". Vous pouvez également indiquer le nom d'une metadonnée du parent ciblé. Exemples :

${..}

 

Contenu du parent direct

${../../../..}

 

Contenu du parent N+4

${../metadata_A}

 

Metadaonnée metadata_A du contenu du parent direct

${../../metadata_A.metadata_B}

 

Metadonnée metadata_B du contenu lié par la metadonnée metadata_A du contenu du parent N+2

Lors d'une jointure sur une metadonnée multivaluée ou lors de l'autopostage pour les thesaurii, la requête spécifiée peut être modifiée avant son exécution pour tester toutes les valeurs attendues. Exemple, la requête suivante :

my_metadata_A:${../my_parent_multivalued_metadata_A}

 

 devient

my_metadata_A:my_parent_metadata_A_value_1 OR my_metadata_A:my_parent_metadata_A_value_2 OR ...

Vous pouvez ajouter des groupes qui permettent de ne dupliquer que certaines parties des requêtes et non les requêtes entière. Cela permet que ces requêtes, exécutées un certain nombre de fois soient beaucoup plus performantes. Le groupe est mis entre accolades, précédé du signe '#' :

#{my_metadata_A:${../my_parent_mutlivalued_metadata_A}} OR {!ametys join=linkContent->my_metadata_B q=#{id:${../my_parent_multivalued_metadata_B}}}

devient

(my_metadata_A:my_parent_metadata_A_value_1 OR my_metadata_A:my_parent_metadata_A_value_2 OR ...) OR ({!ametys join=linkContent->my_metadata_B q=(id:my_parent_metadata_A_value_1 OR id:my_parent_metadata_A_value_2 OR ...)})

Plusieurs règles sont à connaître :

  • S'il n'y a pas de groupe dans la clause, la clause elle-même est considérée comme un groupe.
  • S'il y des groupes dans la clause, aucune variable ne peut être utilisée en dehors d'un groupe.
  • A l'intérieur d'un groupe, on peut utiliser plusieurs fois la même variable de jointure.
  • A l'intérieur d'un groupe, on ne peut pas utiliser plusieurs variables de jointure différentes.


Ajouter des variables de clause

Une variable de clause est définie par un nom et un type de contenu. Sa valeur est fournie à l'exécution via un contenu appartenant au type de contenu spécifié. La valeur peut ensuite être utilisée dans les clauses des composants.

Le noeud Variable de clause contient toutes les variables de clause. Il est automatiquement créé lors de la création du fichier de définition.

 Dans l'outil 'Détails de l'extraction', sélectionnez le noeud Variables de clause et cliquez sur le bouton 'Modifier' de l'onglet 'Extractions'. Une boîte de dialogue s'affiche vous permettant d'ajouter des variables de clause ou de modifier les variables existantes :

  • Nom : nom de la variable, à utiliser ensuite dans les clauses.
  • Type de contenu : Liste déroulante contenant de types de contenu disponibles. Ce champ est obligatoire.

Vous pouvez ajouter des variables en cliquant sur le bouton '+'.



Ajouter des variables pour les colonnes optionnelles

Pour rendre une colonne optionnelle, on utilise des variables. A l'exécution, l'utilisateur choisit pour chaque variable si les colonnes qui dépendent de cette variable seront affichées ou non.

Le nœud Colonnes optionnelles contient toutes ces variables. Il est automatiquement créé lors de la création du fichier de définition.

Dans l'outil 'Détails de l'extraction', sélectionnez le nœud Colonnes optionnelles et cliquez sur le bouton 'Modifier' de l'onglet 'Extractions'. Une boîte de dialogue s'affiche, vous permettant de créer une ou plusieurs variables pour les colonnes optionnelles :

  • Noms : nom des variables pour les colonnes optionnelles, séparées par une virgule.

Modifier un nœud

Dans l'outil 'Détails de l'extraction', sélectionnez un nœud et cliquez sur le bouton 'Modifier' de l'onglet 'Extractions' :

Une boîte de dialogue s'affiche vous permettant de modifier les informations du nœud sélectionné. Les champs de la boîte de dialogue dépendent du nœud sélectionné.

Supprimer un nœud

Dans l'outil 'Détails de l'extraction', sélectionnez un nœud et cliquez sur le bouton 'Supprimer' de l'onglet 'Extractions' :


Après confirmation de votre part, le nœud sélectionné et tous ses enfants sont supprimés.

Sauvegarder ou annuler les modifications

Lorsque vous effectuez une modification sur une extraction, une étoile s'affiche dans le nom de l'outil 'Détails de l'extraction' correspondant. Vous pouvez sauvegarder les modifications apportées à l'extraction en cliquant sur le bouton 'Sauvegarder' de l'onglet 'Extractions' :


Sinon, vous pouvez annuler ces modifications en cliquant sur le bouton 'Annuler' de l'onglet 'Extractions' :

Utiliser l'outil Fichiers de paramètres

Les fichiers de définitions se trouvent dans le répertoire WEB-INF/param/extraction. Vous pouvez donc les modifier directement en utilisant l'outil Fichiers de paramètres. Pour cela, cliquez sur le bouton Fichiers de paramètres :


Renommer un fichier de définition

Dans l'outil 'Extractions', sélectionnez un fichier de définition et cliquez sur le bouton 'Renommer' de l'onglet 'Extractions' :

Vous pouvez également cliquer sur le bouton 'Renommer' depuis l'outil 'Détails de l'extraction'.

Supprimer un fichier de définition

Dans l'outil 'Extractions', sélectionnez un fichier de définition et cliquez sur le bouton 'Supprimer' de l'onglet 'Extractions' :