Some tools and softwares are required in order to install ESCOGrouper properly :
Maven, Tomcat and the project must be installed in a directory without blank caracter. By exemple :
CHEMIN |
CORRECT OU INCORRECT |
---|---|
C:/Program Files/Tomcat |
Incorrect |
C:/Tomcat |
Correct |
Grouper 1.6.2/1.6.3 database must be accessible for the API to work.
ESCOGrouper portlet is only compatible with uPortal 2.6 and https, and you can't use 2 ESCOGrouper portlets on the same portal because of session's problems.
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.
There is no setting or configuration modification with the DERBY database between v2.5.00, v2.6.00 and v2.6.07of the application.
Prerequisites : _the Tomcat server which will host the application have to be started when the Ant tasks are run.
-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.
<Connector emptySessionPath="true" acceptCount="100" connectionTimeout="20000" |
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.
ant deploy |
If the application has never been installed and the memory database doesn't exist.
Enter ESCOGrouper 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 :
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 ESCOGrouper directory and run :
ant init ant deploy |
When Tomcat deploys your war file, the memory database of your previous installation isn't modified.
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 ESCOGrouper 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.
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 ESCOGrouper 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.
This task can start cleaning projects in order to return to a pristine state before any new compilation.
This task runs a “dbinit”, copies the generated files in the project, and build the project.
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.
This task deploys the war created on your Tomcat.
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.
This task removes the war file and the deployment directory (in local and remote modes).
All the config files are located in the “ ESCOGrouper/properties” directory.
This is the environment's file, used by the Ant task.
Key |
Description |
Example |
---|---|---|
escogrouper.property.file |
File to use for the build, located in the “ESCO Grouper/properties” directory |
ESCOGrouper.properties |
javascript.compression |
Enable or disable the compression for Javascript files. |
true |
MAVEN |
|
|
maven.home |
Maven's directory |
/opt/apache-maven-2.2.0 |
maven.offline |
Enable or disable Maven's Offline mode compilation. |
false |
maven.quiet |
Enable or disable verbose build. “false” will display the errors. |
false |
TOMCAT |
|
|
tomcat.deploy.mode |
Configure the deployment mode : “local” or “remote”. |
local |
tomcat.webapps.directory |
Deployment directory (in local deployment mode) |
/opt/tomcat/webapps |
tomcat.host |
Tomcat Manager's url. (required in remote deployment mode) |
|
tomcat.user |
Login used to connect to the Manager (in remote mode) |
manager |
tomcat.password |
Password used to connect to the Manager (in remote mode) |
manager |
It's ESCOGrouper properties' file.
Key |
Description |
Example |
---|---|---|
APPLICATION |
|
|
application.version |
Application's version number (just an information) |
2.6.0 |
application.versionMajorNumber |
Major version number. (used by “application.xml” to show the version number on the footer) |
2 |
application.versionMinorNumber |
Minor version number. (used by “application.xml” to show the version number on the footer). |
6 |
application.versionUpdate |
Application's update version. (used by “application.xml” to show the version number on the footer). |
0 |
application.env |
Environment's name. (test, production, development), … |
test |
application.type |
Compilation type. (“servlet” or “portlet”) |
servlet |
application.portlet.name |
portlet's name (ignored in servlet mode) |
ESCOGrouperPortlet |
application.host |
Hostname of the server hosting the application. (IP address or hostname) |
escogrouper.esco-portail.org |
application.context |
Application's context name. |
ESCOGrouper |
application.port |
Port to access the application. |
443 |
CAS |
|
|
cas.mode |
Protocol used with CAS (http, https) |
https |
cas.host |
Cas hostname |
auth.esco-portail.org |
cas.port |
CAS port |
443 |
cas.uri |
Cas URI. (don't forget the leading slash “/”) |
/ |
cas.uri.login |
Login URI. (don't forget the leading slash “/”). |
/login |
cas.uri.logout |
Logout URI. (don't forget the leading slash “/”). |
/logout |
cas.uri.validate |
Cas validator URI. (don't forget the leading slash “/”). |
/proxyValidate |
cas.uri.proxyCallback |
Cas callback URI.(don't forget the leading slash “/”). |
/casProxyCallback |
LDAP |
|
|
ldap.host |
LDAP Hostname |
172.31.142.71 |
ldap.port |
LDAP port |
389 |
ldap.login |
LDAP Login |
admin |
ldap.password |
LDAP Password. |
passwd |
ldap.dn |
LDAP bind dn. |
cn=grouper,dc=esco-portail,dc=org |
ldap.dn.password |
LDAP password. |
passwd |
ldap.basedc |
LDAP Base “Dn”. |
dc=esco-portail,dc=org |
ldap.baseuid |
LDAP search branch. (branch containing ldap users = people branch). |
ou=people,dc=esco-portail,dc=org |
GROUPER DATABASE |
|
|
database.driver |
Grouper database driver |
com.mysql.jdbc.Driver |
database.username |
Grouper database username |
esco |
database.password |
Grouper database password |
passwd |
database.url |
Grouper database JDBC url |
jdbc:mysql://172.31.142.71:3306/grouper?characterEncoding=UTF-8 |
DERBY DATABASE (MEMORY DATABASE) |
|
|
derby.driver |
Derby database driver |
org.apache.derby.jdbc.ClientDriver |
derby.port |
Derby database port |
1527 |
derby.url |
Derby database jdbc url |
jdbc:derby://localhost:1527//opt/conf.dir/data/ESCODB;create=true; |
derby.username |
Derby database username |
sa |
derby.password |
Derby database password |
passwd |
derby.requireAuthentication |
Tells whether an authentication true is required to connect to the Derby database. (“true” or “false”) |
true |
GROUPER WS |
|
|
grouperClient.webService.url |
Not used at present |
|
grouperClient.webService.login |
Not used at present |
|
grouperClient.webService.password |
Not used at present |
|
GROUPER API service |
|
|
grouper.service |
Service used for Grouper API calls. 2 values possible :
|
grouperApiImplRecia |
grouper.helper.timeToIdle |
duration of inactivity from the cache before its regeneration (seconds) if the grouperApiImplRecia service is used |
60 |
grouper.helper.timeToLive |
maximum lifetime of the cache before its regeneration (seconds) if the grouperApiImplRecia service is used |
600 |
LOG4J |
|
|
log4j.level |
Log level for the whole application. (“DEBUG”, “INFO”, “WARN”, “ERROR”, “FATAL”) |
DEBUG |
log4j.appender.grouper_event.File |
Obsolete. Grouper events log file. To be used it is necessary to modify log4j file (ant/filters/log4j.filter.xml) |
|
log4j.appender.grouper_error.File |
Obsolete. Grouper errors log file. To be used it is necessary to modify log4j file (ant/filters/log4j.filter.xml) |
/home/grouper/logs/ESCOGrouper/grouper_error.log |
log4j.appender.grouper_debug.File |
Grouper debug log file |
|
log4j.appender.grouper_gb.File |
Obsolete. Grouper benchs log file. To be used it is necessary to modify log4j file (ant/filters/log4j.filter.xml) |
|
log4j.appender.escogrouper.File |
Specific ESCO-Grouper log file |
/home/grouper/logs/ESCOGrouper/escogrouper.log |
SMTP |
|
|
smtp.host |
SMTP hostname |
localhost |
smtp.port |
SMTP port |
25 |
smtp.username |
SMTP login |
|
smtp.password |
SMTP password |
|
smtp.adress |
Recipient's address |
ent@esco-portail.org |
smtp.name |
Recipient's name |
Administrator |
smtp.adressFrom |
Sender's address |
devel@esco-portail.org |
smtp.nameFrom |
Sender's name |
ESCO-Portail |
smtp.copyAdress |
Cc address (copy) |
julien.gribonvald@recia.fr |
error.level |
Error level to send mails |
ERROR |
DYNAMIC GROUPS |
|
|
dynamic.group |
Include the dynamic groups plugin to the project (“true” or “false”) |
true |
dynamic.database.attribute.field.ldaprequest |
Name of the grouper's attribute used to store the LDAP request defining the dynamic group. (name of the attribute in grouper_field table) |
rule |
dynamic.group.type |
Name of the custom grouper group type associated to dynamic groups. (name of the group type defined in “grouper_types” table). |
dynamic |
Application's settings are used in all pages of ESCOGrouper, 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 :
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.
This file allows to configure 2 types of parameters
“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.
This file allows to configure the search pages
*Folders search
This file allows to configure folders relative pages :
This file allows to configure groups relative pages :
*Group properties
This file allows to configure dynamic groups relative pages :
This file allows to configure persons relative pages :
The files containing the application's labels which are not created during the database generation step are located in :
You can configure different error messages on each screens. Here is the List of the prefixes you must use for the summary screens :
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 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= |
The “grouperapistrategy.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 :
The “grouperclientstrategy.xml” file allows to define the groups search strategy to use depending on an evaluated expression. This file is located in “ESCOGrouper/ext/grouperclient.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 :
The “groupdynamicstrategy.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 :
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 :
The profile mechanism is explained in « ESCOGrouper 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.
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.
<?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 ESCOGrouper.
You'll find at the end of that document all the available keys that could be used to define your profiles.
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 ESCOGrouper.
If you only have one SMTP server, the configuration should be done in “ESCOGrouper.properties” file.
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.
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; } }; |
The configuration files modified to install the application are the following :
This file contains filters used to create Grouper's configuration's files (“grouperclient.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.
Key |
Description |
Example |
---|---|---|
grouperClient.ldap.url |
LDAP URL for Grouper client |
ldap://172.31.142.71/dc=esco-portail,dc=org |
grouperClient.ldap.login |
LDAP admin login |
admin |
grouperClient.ldap.password |
LDAP admin password |
passwd |
grouperClient.webService.url |
Grouper web service URL |
|
grouperClient.webService.login |
Grouper webservice login |
grouper |
grouperClient.webService.password |
Grouper webservice password |
passwd |
Key |
Description |
Example |
---|---|---|
PROVIDER_URL |
LDAP server URL |
ldap://172.31.142.71:389 |
SECURITY_PRINCIPAL |
LDAP bind dn |
cn=admin,dc=esco-portail,dc=org |
SECURITY_CREDENTIALS |
LDAP password |
admin |
base |
LDAP base dn |
ou=people,dc=esco-portail,dc=org |
Key |
Description |
Example |
---|---|---|
hibernate_driver_class |
Grouper database driver |
com.mysql.jdbc.Driver |
hibernate_username |
Grouper database login |
grouper |
hibernate_password |
Grouper database password |
passwd |
hibernate_url |
Grouper database JDBC url |
jdbc:mysql://escogrouper:3306/grouper?characterEncoding=UTF-8 |
Key |
Description |
---|---|
log4j.appender.grouper_event.File |
Grouper events log file |
log4j.appender.grouper_error.File |
Grouper errors log file |
log4j.appender.grouper_debug.File |
Grouper debug log file |
This file is ESCOGrouper config file. It allows to configure the environment variables required by CAS and to define the relative paths of the medias.
Key |
Description |
Exemple |
---|---|---|
mediaPath.portlet |
Relative path to access the medias (in portlet mode) |
/ESCOGrouper/media |
mediaPath.servlet |
Relative path to access the medias (in servlet mode) |
../media |
cas.url.login |
CAS login URL |
|
cas.url.logout |
CAS logout URL |
|
cas.url.validator |
CAS Validation URL |
|
app.spring.ckeck |
Session's Checking URL |
https://localhost:8443/ESCOGrouper/j_spring_cas_security_check |
cas.service |
CAS URL |
|
casValidateUrl |
CAS proxy validation URL |
|
proxyCallbackUrl |
CAS proxy callback URL |
|
ldap.url |
LDAP URL |
ldap://0.0.0.0:389/ |
ldap.dn |
LDAP bind dn |
cn=admin,dc=esco-portail,dc=org |
ldap.password |
LDAP password |
admin |
ldap.basedc |
LDAP base dn |
dc=esco-portail,dc=org |
ldap.baseuid |
LDAP people branch |
ou=people,dc=esco-portail,dc=org |
ldap.basehasMember |
LDAP group branch |
ou=groups,dc=esco-portail,dc=org |
This is the Derby database (memory database) configuration file.
Key |
Description |
Example |
---|---|---|
environnement.type |
Environment type |
Dev |
version |
Application's version |
2.2.00 |
parameter.db.classname |
Database driver |
org.apache.derby.jdbc.ClientDriver |
parameter.db.port |
Database port |
1527 |
parameter.db.host |
Database host |
0.0.0.0.0 |
parameter.db.url |
Database JDBC URL |
jdbc:derby://localhost:1527/opt/tomcat/esco/data/ESCODB;create=true; |
parameter.db.username |
Database username |
sa |
parameter.db.password |
Database password |
manager |
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 “authform.xml” file.
The “dynConfig.properties” file of the dynamic group project must be configured to setup the dynamic group feature. It's located in “ESCOGrouper\metier\escomodule\dynamiquegroupe\src\main\resources\properties” directory
Key |
Description |
Example |
---|---|---|
dynamic.key.attribute.ldaprequest |
Name of the grouper's attribute used to store the request defining the dynamic group. (name of the attribute in grouper_field table) |
rule |
dynamic.value |
Name of the custom grouper group type associated to dynamic groups. (name of the group type defined in “grouper_types” table) |
dynamic |
tab.regpresent |
Replace in the tab the value «dynamique » with the one provided in the “dynamic.value” key. |
|
tab.group.regpresent |
Replace in the tab the value «dynamique » with the one provided in the “dynamic.value” key. |
|
Navigation area |
|
|
---|---|---|
org.esco.grouperui.web.areaNavigation |
Display or hide the navigation area |
|
Menu contextuel |
|
|
org.esco.grouperui.web.menu.createGroup |
Contextual menu for group creation |
|
org.esco.grouperui.web.menu.createStem |
Contextual menu for stem creation |
|
org.esco.grouperui.web.menu.search |
Contextual menu for simple search (depends of the navigation area) |
|
org.esco.grouperui.web.menu.administrate |
Contextual menu for group or stem administration |
|
org.esco.grouperui.web.menu.properties |
Contextual menu for group or stem properties |
|
org.esco.grouperui.web.menu.optin |
Contextual menu for subscribinf a group |
|
org.esco.grouperui.web.menu.optout |
Contextual menu for unsubscribing a group |
|
org.esco.grouperui.web.menu.delete |
Contextual menu for deleting a group or a stem |
|
Propriété de personnes |
|
|
org.esco.grouperui.web.person.properties |
Allow or not the access to person properties screen |
|
org.esco.grouperui.web.person.properties.tab.memberships |
Display or hide the memberships tab in the person properties screen |
|
org.esco.grouperui.web.person.properties.tab.privileges |
Display or hide the privileges tab in the person properties screen |
|
org.esco.grouperui.web.person.properties.tab.subscriptions |
Display or hide the subscription tab in the person properties screen |
|
Propriété de groupes |
|
|
org.esco.grouperui.web.group.properties |
Allow or not the access to group properties screen |
|
org.esco.grouperui.web.group.properties.tab.members |
Display or hide the members tab in the group properties screen |
|
org.esco.grouperui.web.group.properties.tab.memberships |
Display or hide the memberships tab in the group properties screen |
|
org.esco.grouperui.web.group.properties.tab.privileges |
Display or hide the privileges tab in the group properties screen |
|
Modification de groupes |
|
|
org.esco.grouperui.web.group.modification |
Allow or not the access to the group modify screen |
|
Propriété de dossiers |
|
|
org.esco.grouperui.web.stem.properties |
Allow or not the access to the stem properties screen |
|
Modification de dossiers |
|
|
org.esco.grouperui.web.stem.modification |
Allow or not the access to the modify stem screen |
|
org.esco.grouperui.web.stem.modification.tab.privileges |
Display or hide the privileges tab in the modify group screen |