Integration manual v1.0.0, v1.1.0, v1.2.0, v1.3.0

  1. Installation
  2. Configuration
    1. Defining content types
    2. Definition of "populations
      1. Content types
      2. Parameters
      3. Search criteria
      4. Results columns
      5. Mapping
      6. boSource" attribute
      7. SourcePrevails" attribute
    3. Content lifecycle
    4. Application log configuration

Installation

  • Stop the server
  • Download jars from plugin and add them (ametys-plugin-user-directory-1.0.0.jar and ametys- plugin-user-directory-resources-1 .0.0. jar ) in the WEB-INF/lib directory of your application. Ametys

  • Add buttons to open the search tool and to open your own card in the file. WEB-INF/params/cms-ribbon-default.xml.
    The button identifier is org.ametys.plugins.user.directory.Search and org.ametys.plugins.user.directory.EditSelfCard.

    It is advisable to add it to the "Tools" group of the Home.

    Attention
    Please note! If the group contains a description <large>, <medium> and <small> button must be added to the 3


  • In the same file, add a button to position the root of a directory on a page: org.ametys.plugins.user.directory.SetRoot

  • In the same file, import the ribbon file specific to directory content 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

Defining content types

Each user population defines the type(s) of content that will be created following synchronization.

You are free to define any type of content. The plugin directories don't provide any type of content, so it's up to you to define your own content for each population.

The following rules apply to your content types:

  1. content type identifiers must begin with org.ametys.plugins.userdirectory.Content
  2. the Java class associated with content types must be org.ametys.plugins.userdirectory.contenttype.UserContentType
  3. content types must be declared as private
  4. content types must be declared in your own plugin (consequence of rule no. 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>

Here's an example of plugin defining the content type "org.ametys.plugins.userdirectory.Content.employee" and the configuration parameters required to connect to the LDAP server: employee.zip
We strongly recommend that you start from this plugin and modify it to suit your needs.

Definition of "populations

A population is a set of users/members from the same data source (LDAP, SQL, ...).

User "populations" are defined in the XML WEB-INF/param/user-populations file.xml

Each population must define :

  • its data source (a server LDAP , for example)
  • the Java class responsible for synchronizing content (e.g. org.ametys.plugins.userdirectory.population.LDAPPopulation)
  • the type(s) of content to which it is linked
  • search fields and possible results columns
  • mapping between content type fields and data source attributes

Population example

<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>

Content types

The section <content-types> contains the list of content types (UserContentType) that will be created/synchronized with the data source

Parameters

Parameters are those required to connect to the data source.

They refer to configuration parameter identifiers.

Search criteria

The section <search-criteria> defines the metadata to be used as search criteria in the directory.

The "metadata-ref" contains the path to the metadata.

The "analyzed" is optional. Set the attribute to false to avoid using a text analyzer during indexing.

Results columns

If directory search results are displayed in tabular form, you can define in the section <result-columns> which columns the table will contain.

As with search criteria, the "metadata-ref" attribute contains the path to the metadata to be displayed in the result column.

The column with the main="true"will be the column containing the link to the complete population member record.

If a column is to display a email, add the attribute type="email" so that it is treated differently when displayed, to combat spam.

Mapping

Mapping defines which fields (content metadata) will be synchronized with external source information.

The mapping necessarily contains a <id> identifying the metadata and attribute/column of the data source used to guarantee the uniqueness of the content.

For other fields (metadata), you can specify whether the remote value should be synchronized or overwrite the local metadata (synchro = "true|false"):

  • if synchro="true"then the associated metadata will have 2 values: the local value, which can be modified, and the remote value, extracted from the data source, which cannot be modified.
    For editing, the contributor can choose to use the local value (Ametys) or the remote value (BD) :

  • if synchro="false", the metadata has only one value, which will always be synchronized with the value of the data source.

 

boSource" attribute

If a population is linked to the same population of users who can connect to the back-office, add the attribute boSource=true.

This gives access to the "Open my personal file" button, for users of this population.

SourcePrevails" attribute

This attribute is important when synchronizing a population. It means "trust the data source".
So, when synchronizing a population, if content created by a previous synchronization is linked to an identifier/login that no longer exists in the data source, it will be deleted fromAmetys if sourcePrevails = true.

Further information
plugin Directories provides a single Java class for synchronizing a population from a LDAP directory: org.ametys.plugins.userdirectory.population.LDAPPopulation.
This class is sufficient for a population from a LDAP server in the following general case:
- the data source is a directory LDAP
- synchronization with the directory results in the creation of a single type of content
- a metadata is synchronized with a single directory attribute
You'll need to define your own Population class whenever your use case doesn't fit into the general case. For example, if you wish to create several types of content from the same population, if a metadata must be synchronized with 2 or more LDAP attributes, etc...
To do this, your class will need to extend the org.ametys.plugins.userdirectory.population.AbstractPopulation or org.ametys.plugins.userdirectory.population.LDAPPopulation and define its own #populate method.
The purpose of the #populate method is to extract "members" from the data source and create/synchronize content Ametys. 

Content lifecycle

Content Ametys from a population has its own workflow.

Download the workflow description file for these contents and copy it into your application's WEB-INF/param directory.
Then modify the WEB-INF/param/workflows file .xml to add the reference to this file using the name "user-directory", as shown below:

<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>

Application log configuration

It is possible and highly recommended to configure a specific log category for population import/synchronization.

To do this, add the lines below to the WEB-ING/log4j file. 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>

Messages relating to population synchronization can be consulted in a WEB-INF/logs/population-synchro-[date].log file.

Back to top

User directory