Manuel d'intégration v1.0.0, v1.1.0, v1.2.0, v1.3.0

  1. Installation
  2. Configuration
    1. Définition des types de contenus
    2. Définition des "populations"
      1. Les types de contenus
      2. Les paramètres
      3. Les critères de recherche
      4. Les colonnes résultats
      5. Le mapping
      6. Attribut "boSource"
      7. Attribut "sourcePrevails"
    3. Cycle de vie des contenus
    4. Configuration des journaux de l'application

Installation

  • Arrêter le serveur
  • Télécharger les jars du plugin et ajouter-les (ametys-plugin-user-directory-1.0.0.jar et ametys-plugin-user-directory-resources-1.0.0.jar) dans le répertoire WEB-INF/lib de votre application Ametys

  • Ajouter les bouton permettant d'ouvrir l'outil de recherche et d'ouvrir sa propre fiche dans le fichier WEB-INF/params/cms-ribbon-default.xml.
    L'identifiant des boutons est org.ametys.plugins.user.directory.Search et org.ametys.plugins.user.directory.EditSelfCard.

    Il est conseillé de l'ajouter dans le groupe "Outils" de l'onglet Accueil.

    Attention
    Attention ! Si le groupe contient une description <large>, <medium> et <small> , il faut ajouter le bouton dans les 3


  • Dans ce même fichier, ajouter le bouton permettant de positionner la racine d'un annuaire sur une page : org.ametys.plugins.user.directory.SetRoot

  • Dans ce même fichier, importer le fichier de ribbon propre au contenus issus d'un annuaire plugin:user-directory://cms-ribbon.xm

    <tab label="RIBBON_TABS_TAB_HOME_LABEL">
	<groups>
		<group label="RIBBON_TABS_TAB_HOME_GROUPS_GROUP_TOOL_LABEL" icon="">
			<large>...</large>
			<medium>
				<control id="org.ametys.web.userinterface.Sitemap"/>
				[...]
                <control id="org.ametys.plugins.user.directory.Search"/>
				<control id="org.ametys.plugins.user.directory.EditSelfCard"/>
			</medium>
			<small>...</small>
		</group>
	</groups>
</tab>

[...]
<tab label="plugin.web:RIBBON_TABS_TAB_PAGE_LABEL" id="org.ametys.cms.page.Tab" contextualColor="2" contextualGroup="A" contextualLabel="plugin.web:RIBBON_TABS_TAB_PAGE_LABEL">
	<groups>
		[...]
		<group label="plugin.web:RIBBON_TABS_TAB_PAGE_GROUPS_GROUP_PAGE_LABEL" icon="">
			<large>...</large>
			<medium>
				<control id="org.ametys.plugins.user.directory.SetRoot"/>
			</medium>
			<small>...</small>
		</group>
		[...]
	</groups>
</tab>

<import>plugin:user-directory://cms-ribbon.xml</import>

Configuration

Définition des types de contenus

Chaque population d'utilisateurs définie le ou les types des contenus qui seront créés suite à une synchronisation.

Vous êtes libre de définir n'importe quel type de contenus. Le plugin Annuaires n'apporte aucun types de contenus, à vous de définir vos propres contenus correspondant à chacune des populations.

Pour vos types de contenus, vous devez respecter les règles suivantes :

  1. l'identifiant des types de contenus doit commencer par org.ametys.plugins.userdirectory.Content
  2. la classe Java associée aux types de contenus doit être org.ametys.plugins.userdirectory.contenttype.UserContentType
  3. les types de contenus doivent être déclarés privés
  4. les types de contenus doivent être déclarés dans votre propre plugin (conséquence de la règle n°2)

<extension point="org.ametys.cms.contenttype.ContentTypeExtensionPoint" 
           id="org.ametys.plugins.userdirectory.Content.employee" 
           class="org.ametys.plugins.userdirectory.contenttype.UserContentType">
	<cms:content-type private="true">
		<!-- Métadonnées et vues -->
	</cms:content-type>
</extension>

Voici un exemple de plugin définissant le type de contenu "org.ametys.plugins.userdirectory.Content.employee" et les paramètres de configuration nécessaires pour la connexion au serveur LDAP: employee.zip 
Il est fortement recommandé de partir de ce plugin et de le modifier selon vos besoins.

Définition des "populations"

Une population est un ensemble d'utilisateurs / membres issue d'une même source de données (LDAP, SQL, ...).

Les "populations" d'utilisateurs sont définies dans le fichier XML WEB-INF/param/user-populations.xml

Chaque population doit définir :

  • sa source de données (un serveur LDAP par exemple)
  • la classe Java qui sera responsable de la synchronisation des contenus (ex: org.ametys.plugins.userdirectory.population.LDAPPopulation)
  • le ou les types de contenus à laquelle elle est liée
  • les champs de recherche et colonnes résultats possibles
  • un mapping entre les champs du type de contenus et les attributs de la source de données

Exemple de population

<populations>
    <population id="user.population.employee" class="org.ametys.plugins.userdirectory.population.LDAPPopulation" boSource="true" sourcePrevails="true">
        <label i18n="false">Annuaire du personnel</label>
        <content-types>
            <content-type id="org.ametys.plugins.userdirectory.Content.employee"/>
        </content-types>
        <parameters>
            <ldapBaseUrl>population.employee.ldap.url</ldapBaseUrl>
            <ldapUseSSL>population.employee.ldap.usessl</ldapUseSSL>
            <ldapBaseDN>population.employee.ldap.basedn</ldapBaseDN>
            <ldapFollowReferrals>population.employee.ldap.followreferrals</ldapFollowReferrals>
            <ldapAuthMethod>population.employee.ldap.auth</ldapAuthMethod>
            <ldapAdminDN>population.employee.ldap.admin.dn</ldapAdminDN>
            <ldapAdminPasswd>population.employee.ldap.admin.pwd</ldapAdminPasswd>
            <ldapAliasDereferencing>population.employee.ldap.deref</ldapAliasDereferencing>
            <ldapRelativeDN>population.employee.ldap.people.dn</ldapRelativeDN>
            <ldapBaseFilter>population.employee.ldap.filter</ldapBaseFilter>
            <ldapScope>population.employee.ldap.scope</ldapScope>
        </parameters>
        <search-criteria>
            <criteria metadata-ref="title" analyzed="false"/>
            <criteria metadata-ref="civility" />
            <criteria metadata-ref="firstname" analyzed="false"/>
            <criteria metadata-ref="lastname" analyzed="false"/>
            <criteria metadata-ref="affectation" />
        </search-criteria>
        <result-columns>
            <column metadata-ref="title" main="true"/>
            <column metadata-ref="lastname"/>
            <column metadata-ref="firstname"/>
            <column metadata-ref="affectation"/>
            <column metadata-ref="contact/phone"/>
            <column metadata-ref="contact/mail" type="email"/>
            <column metadata-ref="unlisted"/>
        </result-columns>
        <mapping>
            <id metadata-ref="login" attribute="uid" />
            <field metadata-ref="title" attribute="cn"/>
            <field metadata-ref="civility" attribute="supannCivilite" synchro="true"/>
            <field metadata-ref="firstname" attribute="givenName" synchro="true"/>
            <field metadata-ref="lastname" attribute="sn" synchro="true"/>
            <field metadata-ref="affectation" attribute="supannAffectation" synchro="true"/>
            <field metadata-ref="contact/mail" attribute="mail" synchro="false"/>
            <field metadata-ref="contact/phone" attribute="tel" synchro="false"/>
            <field metadata-ref="unlisted" attribute="supannListeRouge" synchro="true"/>
        </mapping>
    </population>
</populations>

Les types de contenus

La section <content-types> contient la liste des types de contenus (UserContentType) qui seront créés/synchronisés avec la source de données

Les paramètres

Les paramètres sont les paramètres nécessaires pour se connecter à la source de données.

Ils font référence à des identifiants de paramètres de configuration.

Les critères de recherche

La section <search-criteria> défini les métadonnées qui seront utilisées comme critère de recherche dans l'annuaire.

L'attribut "metadata-ref" contient le chemin vers la métadonnée.

L'attribut "analyzed" est optionel. Positionnez l'attribut à false pour ne pas utiliser d'analyseur textuel lors de l'indexation.

Les colonnes résultats

Si les résultats de recherche sur l'annuaire sont affichés sous forme d'un tableau, vous pouvez définir dans la section <result-columns> quelles seront les colonnes du tableau.

Comme pour les critères de recherche, l'attribut "metadata-ref" contient le chemin vers la métadonnée à afficher en colonne résultat.

La colonne portant l'attribut main="true", sera la colonne qui comportera le lien vers la fiche complète du membre de la population.

Si une colonne doit afficher un email, ajoutez l'attribut type="email" pour qu'il soit traité différemment lors de l'affichage afin de lutter contre les spams.

Le mapping

Le mapping définit quels champs (métadonnées du contenu) seront synchronisés avec les informations de la source externes.

Le mapping contient nécessairement un tag <id> identifiant la métadonnée et l'attribut/colonne de la source de données permettant de garantir l'unicité du contenu.

Pour les autres champs (métadonnées), il est possible de dire si la valeur distante, doit être synchronisée ou doit écraser la métadonnée locale (synchro = "true|false"):

  • si synchro="true", alors la métadonnée associée possédera 2 valeurs: la valeur locale, modifiable, et la valeur distante, extraite de la source de donnée, non modifiable.
    En édition, le contributeur pourra choisir d'utiliser la valeur locale (Ametys) ou la valeur distante (BD) :

  • si synchro="false", la métadonnée n'a qu'une seule valeur, qui sera toujours synchronisée avec la valeur de la source de donnée.

 

Attribut "boSource"

Si une population est liée à la même population d'utilisateurs pouvant se connecter au back-office, ajoutez l'attribut boSource=true.

Ceci permet de donner accès au bouton "Ouvrir ma fiche personnelle", pour les utilisateurs cette population.

Attribut "sourcePrevails"

Cet attribut est important lors de la synchronisation d'une population. Il signifie "faire confiance à la source de donnée". 
Ainsi lors de la synchronisation d'une population, si un contenu créé par une précédente synchronisation, est lié à un identifiant/login qui n'existe plus dans la source de donnée, il sera supprimé d'Ametys si sourcePrevails = true.

Pour aller plus loin
Le plugin Annuaires fournit une seule classe Java pour la synchronisation d'une population issue d'un annuaire LDAP : org.ametys.plugins.userdirectory.population.LDAPPopulation.
Cette classe est suffisante pour une population issue d'un serveur LDAP dans le cas général suivant :
- la source de donnée est un annuaire LDAP
- la synchronisation avec l'annuaire donne lieu à la création d'un seul type de contenu
- une métadonnée est synchronisée avec un seul attribut de l'annuaire
Vous devrez définir votre propre classe Population dès que votre cas d'usage ne rentre pas dans le cas général. Par exemple, si vous souhaitez créer plusieurs types de contenus à partir de la même population, si une métadonnée doit être synchronisée avec 2 ou plus attributs LDAP, etc ...
Pour ce faire, votre classe devra étendre la classe org.ametys.plugins.userdirectory.population.AbstractPopulation ou org.ametys.plugins.userdirectory.population.LDAPPopulation et définir sa propre méthode #populate.
La méthode #populate a pour but d'extraire les "membres" de la source de donnée et de créer/synchroniser des contenus Ametys. 

Cycle de vie des contenus

Les contenus Ametys issus d'une population possède leur propre workflow.

Téléchargez le fichier de description du workflow pour ces contenus et copier-le dans le répertoire WEB-INF/param de votre application.
Modifiez ensuite le fichier WEB-INF/param/workflows.xml afin d'ajouter la référence à ce fichier en utilisant le nom "user-directory", comme ci-dessous:

<workflows>
  <workflow name="content" type="file" location="workflow.xml"/>
  <workflow name="newsletter" type="file" location="workflow-newsletter.xml"/>
  <workflow name="ugc" type="file" location="workflow-ugc.xml"/>
  <workflow name="blog" type="file" location="workflow-blog.xml"/>
  <workflow name="user-directory" type="file" location="workflow-user-directory.xml"/>
</workflows>

Configuration des journaux de l'application

Il est possible et très conseillé de configurer une catégorie de journaux spécifique à l'import/synchronisation des populations.

Pour cela, ajoutez les lignes ci-dessous dans le fichier WEB-ING/log4j.xml

<!-- Ajout d'un nouvel appender -->
<appender name="population-synchro" class="biz.minaret.log4j.DatedFileAppender">
        <param name="Directory" value="${context-root}/WEB-INF/logs" />
        <param name="Prefix" value="population-synchro-" />
        <param name="Suffix" value=".log" />
        <param name="Append" value="true" />
        <layout class="org.apache.log4j.PatternLayout">
            <param name="ConversionPattern" value="%d %-5p %m%n" />
        </layout>
        <filter class="org.ametys.runtime.util.AmetysExceptionFilter" />
</appender>
 
<!-- Logger en INFO -->
<category name="org.ametys.plugins.userdirectory.synchronize.UserDirectoryPopulateEngine" additivity="false">
        <priority value="info" />
        <appender-ref ref="population-synchro" />
</category>

Les messages relatifs à la synchronisation des populations seront ainsi consultables dans un fichier WEB-INF/logs/population-synchro-[date].log 

Retour en haut

User directory