Groupe 3 (services applicatifs)
Date de création :	16 octobre 2003
Dernière modification :	14 Janvier 2004
Diffusion :	internet

Utilisatin du canal annuaire

Ce document décrit le fichier de configuration utilisé par le canal annuaire, donne une trame des écrans qui devraient être générés à partir d'un fichier de configuration exemple.

Les sources sont disponibles dans le zip : esup-canal-annuaire-1.0.6.zip

La version 2 est disponible en version : esup-canal-annuaire-2.1-RC-3.zip et la documentation spécifique ce cette version est sur https://www.esup-portail.org/consortium/espace/Comm_2D/annuaireV2/sommaire.html

Installation

Configuration

Utilisation

Limitation

Exemples

Installation

Les librairies utilisées

Ce canal utilise les librairie "commons-beanutils","commons-digester".

Mise en place du canal

Préparation du fichier de configuration CAnnuaire.xlm.: mettre les renseignements relatifs aux serveurs et aux attributs importants.

Préparation du déploiement : modifier le deploy.home du fichier build.properties.

Lancement de la commande "ant deploy", pour déployer le canal dans les bons répertoires.

L'administrateur peut maintenant publier les canaux dont il a besoin en fonction du paramètre d'instanciation : "serverView". Pour cela, il y a 2 méthodes :

La plus simple étant de publier le canal de manière normale, par l'interface WEB prévue à cet effet.

La seconde étant d'utiliser la commande "ant pubchan -Dchannel=CAnnuaireGlobal.xml". Ce fichier CAnnuaireGlobal.xml remplace toute la démarche de publication. Il faut le déposer dans le répertoire {uPortal}/properties/chanpub. Les informations nécessaires à la publication sont décrites dans des tags XML, vous permettant ainsi même spécifier l'attribut "serverView".

La configuration

Structure générale

La configuration de ce canal est décrite dans un fichier xml : CAnnuaire.xml. Une dtd lui est associée : CAnnuaire.dtd.

Le fichier CAnnuaire.xml décrit est bien sûr un exemple. Deux documents xml associés à cet exemple sont également disponible : ListeDisciplines.xml et ListeFormations.xml.

La dtd de l'annuaire contient de nombreux commentaires; il est recommandé de les consulter.

Le fichier CAnnuaire.xml décrit le paramétrage du ou des annuaire(s) qui sont accessibles à ce canal. Il est lu une seule fois au démarrage du portail.

Sa structure générale est la suivante (la cardinalité de chaque élément est indiquée) :

Description des éléments, et attributs

Facultatif. Cet élément permet de décrire et de remplir des tables mémoire qui seront utilisées par le canal annuaire.

Les tables sont bien sûr constituées de plusieurs enregistrements (items).
Un item comprend une valeur (value) et éventuellement un code associé (code).

pas d'attributs

Décrit et donne les informations pour remplir une table.

Il existe 3 types de tables

• static : le contenu est décrit dans ce fichier 'CAnnuaire.xml'.
• ldap : la table est construite à l'aide d'une requête ldap
• xml : la table est construite à l'aide d'un fichier xml externe

Pour ces 2 derniers cas, les tables sont raffraichies périodiquement (paramètre ttl de directories). Ceci n'est pas encore traité.

attributs :

• name : obligatoire. Le nom de la table
• type : facultatif. le type de table : static, ldap ou xml. static par défaut
• base : facultatif . Nécessaire si LDAP. C'est la base de recherche LDAP
• scope : facultatif. Utile uniquement si LDAP. C'est l'étendue de la recherche LDAP. sub, one base. Valeur par défaut : sub (subtree, donc recherche dans toute l'arborescence fille).
• filter : facultatif. Nécessaire si LDAP. C'est le filtre de recherche LDAP associé à cette table.
• attrCode : facultatif. Utile uniquement si LDAP, mais pas nécessaire. Précise l'attribut LDAP qui sera utilisé pour enrichir le 'code' de la table.
• attrValue : facultatif. Nécessaire si LDAP. Précise l'attribut LDAP qui sera utilisé pour enrichir le 'value' de la table.
• file : facultatif. Nécessaire si table de type xml. Il contient le nom du fichier xml associé.

remarque :

Dans le cas d'une table xml : le format de celle-ci est figé (voir cet exemple) ; il est de la forme :

<list>
  <item code="CNU01" value="Droit Privé et Sciences Criminelles" /> 
  <item ...>
</list>

l'attribut 'code' est facultatif. S'il n'est pas présent, il ne doit l'être dans aucun 'item'.
L'attribut 'value' contient la valeur de cet item.

Voir l'élément 'item' du fichier CAnnuaire.xml : la structure est identique

C'est un enregistrement d'une table de type static.

attributs :

• value : obligatoire. Va enrichir la partie 'valeur' de l'enregistrement.
• code : facultatif. Va enrichir la partie 'code' de l'enregistrement.
  S'il n'est pas présent, il ne doit l'être pour aucun item de cette table

C'est l'élément racine.

attributs :

• ttl. facultatif. C'est la période de raffraichissement des tables dynamiques (ldap ou xml), en secondes.
  par défaut : 86400 (donc un jour)

Décrit un annuaire particulier.

attributs :

• name : obligatoire. Un 'code' qui identifie un annuaire particulier (ex : name="Pers").
• title : obligatoire. C'est l'intitulé de l'annuaire, tel qu'il apparaîtra.
• link : facultatif. Contient une url http qui pointe vers un annuaire externe plus conséquent.

Précise les paramètres de connexion LDAP pour cet annuaire.

attributs :

• url : obligatoire. l'url LDAP de connexion. Peut prendre en compte la redondance de serveurs LDAP (réplicas)
  ex : ldap://ldap1.univ.fr/dc=univ,dc=fr ldap://ldap2.univ.fr/dc=univ,dc=fr
• binddn : facultatif. le DN de connexion dans l'annuaire, si non anonyme.
• bindpass : facultatif. Le mot de passe associé au DN précédent
• secure : facultatif. Valeurs : true ou false. implicite = false. true si utilisation de SSL ou TLS pour la connexion

Cet élément permet de définir la requête LDAP à générer pour la recherche dans l'annuaire.
Il permet également de construire le formulaire d'interrogation.

Il est composé d'elemOfRequest. La requête sera composée d'un et (&) avec chaque élément de requête non vide généré.

attributs :

• base : obligatoire. C'est la base de recherche dans l'annuaire
• scope : facultatif. C'est l'étendue de la recherche : base, one, sub. Par défaut : sub.
• maxEntries : facultatif. C'est le nombre maximum d'entrées qu'on accepte de retourner.
• identifiant : facultatif. Obligatoire si on veut passer de moder tableau au mode fiche dans les résultats. C'est le nom du champ LDAP qui permet d'identifier une personne.

C'est un élément d'une requête. Il permet d'une part, de construire éventuellement un champ du formulaire de saisie, et d'autre part, un élément de la requête finale.

Il existe 4 types d'éléments :

• type direct. Contient un élément de recherche 'statique', non paramétrable. Dans ce cas, l'élément de requête n'est pas visible dans le formulaire de saisie.
• type text. Donne lieu à affichage d'un champ de saisie (text en html). La requête sera construite à l'aide du champ de saisie associé (%s), si celui-ci est non vide.
• type listTable. Donne lieu à affichage d'une liste déroulante (select - option en html).il y a utilisation d'une table prédéfinie. Les 'valeurs' de la table permettront de générer la liste déroulante ; Si un élément de la liste est sélectionné, il y aura génération d'un élément de requête, contruit grâce au code (%c) ou a la valeur (%v) séléctionnée.
• type textTable. Donne lieu à affichage d'un champ de saisie (text). Le contenu de ce champ, s'il est saisi, donne lui à recherche dans les valeurs de la table associée.
  • Si un seul item de la table correspond au critère de recherche, l'élément de requête sera générée à l'aide du code (%c) ou de la valeur (%v) de l'item concerné.
  • Si aucun item ne correspond, la requête globale ne retournera aucune entrée.
  • Si n items correspondent à ce critère (n > 1), l'élément de requête sera un 'ou' LDAP avec les n sous-éléments de requête générés. Voir l'exemple en fin de document pour mieux comprendre l'utilité.

attributs :

• type : facultatif. direct, text, listTable, textTable. par défaut : text.
• label : facultatif. Obligatoire si type != direct. C'est le 'label' associé avec cette requête ; IL sera affiché en label dans le formulaire de saisie.
• table : facultatif. Obligatoire si type=listTable ou textTable. C'est le nom de la table associée.
• filter : obligatoire. C'est l'élément de filtre ldap associé.
  • si type=text : l'expression "%s" est remplacée par la valeur du champ saisi.
  • si type=listTable ou textTable : l'expression "%c" est remplacé par le code de l'élément de table sélectionné, et "%v" par sa valeur.
• searchValue : facultatif. Obligatoire si type = textTable. C'est le critère de recherche dans les 'valeurs' de la table associée. La recherche n'est pas sensible à la casse. Le caractère "*" est autorisé.
• minChar : Facultatif. Utile pour les type text et textTable. C'est le nombre minimal de caractère qu'on accepte pour ce champ de saisie (si celui-ci est saisi).
• delStar : Facultatif. false ou true. par défaut : true. Utile pour les type text et textTable. Si true, retire tous les caractères "*" qui seraient éventuellement présents dans la saisie de l'utilisateur.
• approx : facultatif. false ou true. par défaut : false. Si true, un bouton de 'recherche approximative' est proposé dans le formulaire; si ce bouton est coché par l'utilisateur, un algo de recherche approximative est généré pour cet élément.
  Il ne peut y avoir au maximum qu'un seul élément ayant approx=true; cet élément est nécessairement de type text.

card

Permet de définir la fiche finale de l'utilisateur, et éveuellement, le tableau intermédiaire si plusieurs utilisateurs répondent au critére de la recherche.

attributs :

• maxCard : facultatif. Nombre maximum de fiche par page avant de passer en mode tableau.
• tri :facultatif. Champs LDAP qui sert de tri
• link : facultatif. contient un lien http vers un annuaire externe plus détaillé. Le symbole "%uid" sera remplacé par la valeur de l'identifiant de la personne à afficher.

C'est une ligne de la fiche finale.

2 types :

• direct : le résultat est directement l'affichage d'un attribut LDAP
• table : un attribut LDAP contient la clé ou la valeur d'une table ci-dessus. C'est la valeur associée à cette clé qui sera affichée.

attributs :

• type : facultatif. direct ou table. Par défaut : direct
• label : obligatoire. C'est le label associé à cette ligne. Il sera affiché.
• table : facultatif. Obligatoire si type table. C'est le nom de la table associée à cette ligne.
• attribute : obligatoire. contient le nom de l'attribut LDAP qui servira à l'affichage.
  • si type = direct : attribute contient le nom de l'attribut correspondant; c'est cela qui sera affiché.
  • si type = table : voir linkTable
• list : facultatif. false ou true. défaut = false. Si true, cette 'line' servira également à l'élaboration de la liste intermédiaire dans le cas de réponses multiples.
• linkTable : facultatif. code ou value. Défaut = code. N'est utile que pour type=table. Indique que l'attribut 'attribute' permet une recherche dans la table sur le code ou sur la valeur.
• tabToCard : facultatif. false ou true. défaut = false. Si true, ce champ sera clicable depuis la feuille de présentation des résultats par tableau pour acceder à la fiche détaillée. Si ce champ est rempli, il faut obligatoirement remplir le champ "identifiant" du request.

Utilisation

Lors de la déclaration du canal par l'administrateur, celui-ci peut saisir le 'code' (cf name dans la configuration) de l'annuaire concerné dans le parametre "serverView". Il peut éventuellement saisir une liste de code,séparés par des virgules, voire "*" pour tous les annuaires. Dans ces cas, un menu déoulant permet à l'utilisateur de choisir l'annuaire de travail. Par défaut, si le paramètre n'est pas saisi, cela équivaut à mettre "*".

Le menu déroulant s'affiche dans le même ordre que celui saisi par l'administrateur. Le premier annuaire est celui par défaut.

Limitations

Dans un premier temps, afin de limiter la complexité, nous ne traitons pas les requêtes sur l'appartenance à un groupe LDAP.

Exemples

1/Résultats sous forme de fiches

On part du fichier CAnnuaire.xml passé en exemple.

L'affichage initial, dans le cas de l'annuaire du personnel ressemblerait à celà (le stype à part, bien sûr) :

Ici, nous avons supposé que l'utilisateur a saisi 'ma', choisi 'CRI' comme composante et n'a pas utilisé la discipline comme critère de recherche.
On suppose également qu'il n'y a pas d'élément de requête ayant l'attribut 'approx' à la valeur true.

La requête générée serait celle-ci :

• base de recherche : ou=people,dc=univ-nancy2,dc=fr
• étendue de la recherche : subtree
• nombre maximum d'entrées : 500
• filtre généré : (&(objectclass=classPers)(supannListeRouge=FALSE)(sn=ma*) (composante=CRI)" )

La fiche résultat serait la suivante :

On voit qu'il y a un lien actif sur l'affichage au bas de chaque fiche ; c'est un lien vers un annuaire externe plus complet.

2/Résultat sous forme de tableau

S'il y avait eu trop de résultats à la requête, ici strictement plus que 3 (cf maxCard de la config), une liste intermédiaire aurait été générée. Pour celà, recherchons les personnes dont le nom commence par "ma" mais sans se limiter à la composante CRI :

3/ Utilisation de textTable

Dans le fichier de configuration, si on modifie l'attribut "type" de l'"ElemOfRequest" composante du serveur du personnel en "textTable", le formulaire obtenu sera :

On peut remarquer que la liste déroulante des composantes est devenu un zone de texte. Cela permet de laisser la saisie libre. Au lieu de chercher une valeur (dans notre exemple : "CRI") das une liste avec beaucoup d'options, il suffit de saisir le nom ou une partie du nom de la valeur que l'on cherche (par exemple "cri").
Alors la recherche compte une étape de plus. En effet, dans un premier temps, le canal va rechercher les entrées de la table dont les valeurs correspondantes à la zone de texte (suivant l'attribut searchValue). Puis le filtre est généré avec un "OU" global sur chacun des codes trouvés. Et enfin, la recherche continue normalement, pour afficher les résultats :

4/ Idées d'utilisations

La possibilité de déclarer plusieurs "directory" permet de nombreuses utilisations. Rappellons que chaque "directory" possède ses propres caractéristiques de connexion, de formulaire, d'affichage de réponse. Alors il est tout à fait possible (ce cas est fournit en exemple ici) d'avoir un "directory" pointant sur le serveur du personnel avec dans les champs du formulaire un "ElemOfRequest" type "direct" spécifiant une recherche dans les personnes n'étant pas en liste rouge et un autre "directory" sans ce champ. De là vous pouvez publier un canal avec le paramètre "serverView = persPublic" pour rechercher dans l'annuaire public et publier un canal avec le paramètre "serverView = persPrive" pour les personnes authentifiées.

Création : 16 octobre 2003 - Vincent MATHIEU
Modifications : 22/10/2003 : Vincent Mathieu 14/01/2004 : Sébastien GAUDIN