Prerequisites

Some tools and softwares are required in order to install ESCO­Grouper properly :

• Maven 2.2.1
• Apache ant 1.8.0
• Tomcat 5.5.27
• A text editor (ex : Notepad)

Maven, Tomcat and the project must be installed in a directory without blank caracter. By exemple :

Grouper 1.6.2/1.6.3 database must be accessible for the API to work.

Restriction

ESCOGrouper portlet is only compatible with uPortal 2.6 and https, and you can't use 2 ESCO­Grouper portlets on the same portal because of session's problems.

Installation

Obtain the sources

To obtain the sources of the application go on : https://sourcesup.cru.fr/frs/?group_id=824

The package ESCO-DynamicGroups must be compilated at the same level place of grouper-ws to deploy a grouper hooks for dynamic groups and the esco-subject-extension-1.2.jar must be deployed in the grouper-ws lib directory.

Setting and configuration

There is no setting or configuration modification with the DERBY database between v2.5.00, v2.6.00 and v2.6.07of the application.

Basic Installation

Prerequisites : _the Tomcat server which will host the application have to be started when the Ant tasks are run.

• Step 1 : Get ESCO­Grouper sources

• Step 2 : Set up Tomcat run arguments.

-Xms256m -Xmx512m -XX:PermSize=64M -XX:MaxPermSize=128M -Xss2048k -Xminf0.05 -Xminf0.40 -Xmaxf0.60
 -Djavax.net.ssl.trustStore=***emplacement du fichier*.cacerts si mode SSL***

NB : the run arguments related to language, encoding, and config directory are no more required since v.2.4.00.

• Step 3 : If you want to install ESCO­Grouper in Portlet mode (uPortal 2.6 + https), edit Tomcat “server.xml” file and add “emptySessionPath=true” for all the <connector> tags :

<Connector emptySessionPath="true" acceptCount="100" connectionTimeout="20000"

• Step 4 : Start Tomcat

• Step 5 : Set­up the configuration files :
  • ESCOGrouper/build.properties
  • ESCOGrouper/properties/ESCOGrouper.properties
  • Application's settings (DERBY database)
  • language files (labels, contextual help, exception)
  • Checking of the strategies
  • Checking of the profiles. These profiles can be modified directly on the server, but a restart of Tomcat will be necessary for the changes to take effect).
  • Checking of mail server settings.

• Step 6 : Build the project (Maven build) with the Ant script :
  • Initialization and compilation : Enter ESCO-Grouper directory and run :

ant init

Warning : if BUILD SUCCESSFUL shows up at the end of Ant script, it doesn't necessarily mean that the build is successfully completed. To be sure that all was fine, you must check that no “BUILD FAILED” appears in the Maven tasks.

• • deployment : Enter ESCO-Grouper directory and run :

ant deploy

• Step 7 : Modify the help files if necessary.

• Step 8 : For the portlet mode, it's mandatory to copy the css file in the portal themes. The file is located in ESCOGrouper/properties/css directory.

1st installation

If the application has never been installed and the memory database doesn't exist.

Enter ESCO­Grouper directory and run :

ant init
ant deploy

When Tomcat deploys your war file, the memory database is created with all the settings configured at step 5.

Tomcat reacts in two different ways (in local or remote mode) with a war file :

• In remote mode, it's automatic
• In local mode, a Tomcat restart is necessary

Deployment after properties' modification (other than DERBY ones)

If the application is already installed, the derby database already exists, and you just want to modify some files in the “properties” directory which are not derby ones (strategies for example), you must do the following :

Enter ESCO­Grouper directory and run :

ant init
ant deploy

When Tomcat deploys your war file, the memory database of your previous installation isn't modified.

Deployment after DERBY properties' modification

If the application is already installed, the derby database already exists, and you just want to modify derby properties, you must do the following.

Enter ESCO­Grouper directory and run :

ant dbinit
ant dbdeploy

The second task copies the generated files (sql + label), removes the derby database and create a new one with your new properties.

This applies for a deployment in local mode. In remote mode, you must refer to the next section.

For the i18n files to be loaded properly, you must restart Tomcat.

Deployment after properties' modification (DERBY and not DERBY properties)

If the application is already installed, the derby database already exists, and you want to modify all types of properties, you must do the following.

Enter ESCO­Grouper directory and run :

ant init
ant dbdeploy
ant deploy

The second task copies the generated files (sql + label), removes the derby database and create a new one with your new properties.

For the i18n files to be loaded properly, you must restart Tomcat.

Ant tasks

ant clean

This task can start cleaning projects in order to return to a pristine state before any new compilation.

ant init

This task runs a “dbinit”, copies the generated files in the project, and build the project.

ant dbinit

This task generates the SQL file (from the properties files and the i18n files) which will be used to fill the DERBY database.

Some warnings concerning “duplicate keys” could show up. Often, this is normal because some keys are used for the same attribute on different pages.
For example, the “extension” attribute is used in the group property page and in the folder property page. The same label (extension.label) is used.

Cette tâche permet de générer le fichier sql permettant d’alimenter la base de données mémoire à partir des fichiers de paramétrage ainsi que les fichiers d’internationalisation.

ant deploy

This task deploys the war created on your Tomcat.

• In remote mode, the existing application is undeployed (if it has the same name) and the new war is deployed. Tomcat will automatically load your war file.
• In local mode, the war is copied in the configured directory. You must restart Tomcat for the changed to take effect.

ant dbdeploy

This task copies the generated files, remove the database, and creates a new one from the newly generated files. Tomcat must be started when running this task.

ant undeploy

This task removes the war file and the deployment directory (in local and remote modes).

ESCO-Grouper Configuration

All the config files are located in the “ ESCO­Grouper/properties” directory.

build.properties

This is the environment's file, used by the Ant task.

ESCOGrouper.properties

It's ESCO­Grouper properties' file.

Application's settings (Derby database)

Application's settings are used in all pages of ESCO­Grouper, to decide whether the elements must be showed.
This technical part have to be the most open and the easiest possible. For those reasons, using a memory database is recommended in those cases, because :

• It's Flexible, because it allows a remote access ;
• It's Accessible from as many modules as you want ;
• It allows settings' hot modifying (without restarting Tomcat).

Some configuration files allow to easily fill the database and to create the corresponding internationalization files.
Each file contains properties defining the way to setup the different pages (see the files provided with the sources).

The files are referenced in the “build.xml” file.
You can edit that file, and change the properties' file names or even add some others files.

MyParameters.properties

This file allows to configure 2 types of parameters

• Parameters required by the database generation step.
• Parameters required by the whole application.

“global.lang” allows to define the application's languages. It can be used to check, during the internationalization files generation step, that all labels are filled in each language.

“default.rule.regexp.*” defines the regular expression used if no expression is defined for fields validation.

MySearch.properties

This file allows to configure the search pages

• Subjects search :
  • Persons
  • Persons in a group
  • Groups

*Folders search

MyStem.properties

This file allows to configure folders relative pages :

• Folder properties
  • Attributes

• Folder's creation, Folder's update
  • Attributes
  • Extension's update
  • Privileges

MyGroup.properties

This file allows to configure groups relative pages :
*Group properties

• • Members
  • Attributes
  • Privileges
  • Memberships

• Group's creation, Group's update
  • Attributes
  • Custom type
  • Default rights
  • Privileges

MyGroupDynamic.properties

This file allows to configure dynamic groups relative pages :

• Dynamic group tab
• Rule's test page

MyPerson.properties

This file allows to configure persons relative pages :

• person's properties :
  • Attributes
  • Memberships
  • Privileges
  • Subscription

Internationalization

Labels

The files containing the application's labels which are not created during the database generation step are located in :

• /ESCO-Grouper/metier/esco-web/src/main/resources/properties/i18n/bundles/screen/
• /ESCO-Grouper/metier/esco-web/src/main/resources/properties/i18n/bundles/
• /ESCO-Grouper/metier/esco-module/dynamique-groupe/src/main/resources/properties/i18n/plugins/screen/

Exceptions

You can configure different error messages on each screens. Here is the List of the prefixes you must use for the summary screens :

• org.esco.grouperui.group.resume. : group's properties summary screen.
• org.esco.grouperui.person.resume. : person's properties summary.
• org.esco.grouperui.stemmodification.resume. : folder's administration's summary screen.
• org.esco.grouperui.groupmodification.resume. : group's administration's summary screen.

Example :
The default behavior when the ESCOGroupNotSaveException is fired is to display the message : “Le groupe n'a pas été enregistré”.
You can change that message by changing the corresponding key. For example, if you wanna change that message for the group's properties summary screen, you just have to create the following key in the Error_XX file :

org.esco.grouperui.group.resume.ESCOGroupNotSaveException=Mon nouveau message

Contextual help

Contextual help labels are located in the internationalization files and have their keys ending with “_TITLE”.
If the key is missing, something like “???KEY???” will shows up.
If you don't wanna display the contextual help for an element, simply remove the value of the key. For example :

STEM_CREATE_GROUP_TITLE=

Stratégies

Persons Search

The “grouper­api­strategy.xml” file allows to define the persons search strategy to use depending on an evaluated expression.

<bean id="defaultStrategySubjectLocator" class="org.esco.grouperui.services.grouper.internal.locator.DefaultStrategySubjectLocator">
	<property name="evaluator" ref="evaluator" />
	<property name="defaultSearchStrategies" >
		<map>
			<entry key=" evaluator.regexp('(esco:Etablissements:(([Installation Guide (en)^_]+)_(\\d{5,7}\\w?))(:[Installation Guide (en)^:]+)*)|(esco:admin:.+)|
(esco:Applications:.+)', path)" value-ref="UAIStrategySubjectSearch"></entry>
			<entry key="evaluator.regexp('(.*)', term)" value-ref="defaulStrategySubjectSearch"></entry>
		</map>
	</property>
</bean>

In the above example, the "UAIStrategySubjectSearch" strategy will be used for all groups which have their path matching the provided regular expression.
The variables you can use in the expression are the following ones :

• term : the search term, which could contain joker characters ;
• path : the path from which the search is run ;
• person : the person executing the search.

Groups search

The “grouper­client­strategy.xml” file allows to define the groups search strategy to use depending on an evaluated expression. This file is located in “ESCO­Grouper/ext/grouper­client.fragment/src/main/ressources/spring” directory.

<bean id="defaultStrategyGroupLocator" class="org.esco.grouperui.services.grouper.internal.locator.DefaultStrategyGroupLocator">
	<property name="evaluator" ref="evaluator" />
	<property name="defaultSearchStrategies" >
		<map>
			<entry key="evaluator.regexp('(.*)', term)" value-ref="defaulStrategyGroupSearch"></entry>
		</map>
	</property>
</bean>

In the above example, there is only a default strategy declared.
The variables you can use in the expression are the following ones :

• field : the attribute on which the user is searching. (values can be “name”, “displayName” and “extension”) ;
• type : search type (simple or for adding purpose). Values can be “SIMPLE” or “ADD” ;
• path : the path from which the search is run ;
• term : the search term, which could contain joker characters ;
• subject : the person executing the search.

Default rule displayed when creating a dynamic group

The “group­dynamic­strategy.xml” file allows to define the default rule which will be displayed when creating a dynamic group. Again, it's based on a regular expression which will be evaluated.

<bean id="defaultStrategyRequestLocator" class="org.esco.grouperui.services.dynamicgroup.internal.DefaultStrategyRequestLocator">
	<property name="evaluator" >
		<bean class="org.esco.grouperui.services.dynamicgroup.internal.ExpressionEvaluator" />
	</property>
	<property name="strategies" >
		<map>
			<entry key="evaluator.regexp('esco:Etablissements:(([Installation Guide (en)^_]+)_(\\d{5,7}\\w?))(:[Installation Guide (en)^:]+)*', stem.getName())">
				<bean class="org.esco.grouperui.services.dynamicgroup.internal.UAIStrategyRequestFactory" />
			</entry>
			<entry key="evaluator.regexp('(.*)', stem.getName())">
				<bean class="org.esco.grouperui.services.dynamicgroup.internal.DefaultStrategyRequestFactory" />
			</entry>
		</map>
	</property>
</bean>

In the above example, the "UAIStrategyRequestFactory" strategy is used for the folders matching the provided regular expression.
The variables you can use in the expression are the following ones :

• stem : the folder where the user is creating the group ;
• person : the person executing the search.

Profiles management

To be able to configure the application depending of which user is connected, you can configure different profiles.
The profile can be retrieved in both ways :

• By giving the profile parameter to the URL (profile=*profile­name*) if the application is in servlet mode
• By retrieving it from the portal if the application is in portlet mode.

The profile mechanism is explained in « ESCO­Grouper ­ Manuel de développement v1.00.pdf ».
The important thing to know is that there are some “*Profile.xml” files you can modify to allow or deny features depending on users.

Adding a profile

To add a profile, you just have to add an XML file in the profiles directory. It will be loaded automatically when the application starts.

Content of a profile

<?xml version="1.0" encoding="UTF-8" ?>
<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:context="http://www.springframework.org/schema/context"
	xsi:schemaLocation="http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop.xsd
		http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
		http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd">

<bean id="testProfile" class="org.esco.grouperui.web.beans.profile.UserProfile">
	<property name="name" value="testProfile"></property>
	<property name="functions">
		<map>
			<!--entry key="*uneClef*" value="*unBooléen*"></entry-->
			<entry key="org.esco.grouperui.web.stem.properties" value="true"></entry>
		</map>
	</property>
</bean>

<bean class="org.esco.grouperui.web.beans.profile.UserProfileAggregator">
	<description>Add the profile to the list of profiles or modify if exist.</description>
	<property name="profiles">
		<list>
			<ref bean="testProfile"></ref>
		</list>
	</property>
</bean>
</beans>

This example file will create a “testProfile” profile which will allow users to access folders properties in ESCO­Grouper.
You'll find at the end of that document all the available keys that could be used to define your profiles.

SMTP server

The SMTP server is used to send mails when technical errors occurs.
The “smtp.xml” file should only be modified when you want to use several SMTP servers with ESCO­Grouper.
If you only have one SMTP server, the configuration should be done in “ESCOGrouper.properties” file.

Online Help

The Help_XX.properties file, located in “ESCOGrouper/metier/escoweb/src/main/resources/properties/i18n/bundles/screen”, is in charge of the mapping between the screen aliases and the files containing the help contents.
For example, here is the key associated to the navigation's area online help :

ONLINE_HELP_NAVIGUATION_AREA_URL=/ESCOGrouper/stylesheets/onlineHelp/en/navigationArea.html

The HTML files can be hot modified on the Tomcat server.

Warning : As the files can be placed anywhere on the server, you must be careful to the path you set, mostly if the deployment context is different.

Banner management

To display the banner, you must set to true the displaying parameter in the "/ESCO-Grouper/metier/esco-web/src/web/webapp/media/js/esco/option.js" file.

To hide it, set the parameter to false.

/**
 * Class to show banner or not
*/
var Banner  = {
	displaying : true,
	isDisplayed : function(){
		return this.displaying;
	}
};

Annexes

Environnements

The configuration files modified to install the application are the following :

• \ESCOGrouper\metier\esco-web\src\main\filters\filters.properties
• \ESCOGrouper\metier\esco-web\src\main\resources\properties\config.properties
• \ESCOGrouper\metier\esco-web\src\main\resources\properties\env.properties
• \ESCOGrouper\metier\esco-web\src\main\resources\properties\applicationContext.xml

filter.properties

This file contains filters used to create Grouper's configuration's files (“grouper­client.properties”, “sources.xml”, “grouper.hibernate.properties” and “log4j.properties”). When you'll compile the project with Maven, these variables will be replaced in the corresponding files.

Environment variables required in “grouper.client.properties”

Environment variables required in “sources.xml”

Environment variables required in “grouper.hibernate.properties”

Environment variables required in “log4j.properties”

config.properties

This file is ESCO­Grouper config file. It allows to configure the environment variables required by CAS and to define the relative paths of the medias.

env.properties

This is the Derby database (memory database) configuration file.

applicationContext.xml

This is the main Spring beans definition file. It allows to define the authentication type for the application (local with specific users or CAS). The users in local authentication are defined in “auth­form.xml” file.

Dynamic groups

The “dynConfig.properties” file of the dynamic group project must be configured to setup the dynamic group feature. It's located in “ESCOGrouper\metier\esco­module\dynamique­groupe\src\main\resources\properties” directory

Summary table of possible keys for the profile management