The eXo Platform integration with other systems is very important. To make eXo Platform work with predefined organizational data properly, it is necessary to initialize some backend settings for each organizational element. Operations involved in synchronizing eXo Platform's backend settings with the organizational entities are called organizational model integration.
By default, the integration with an enterprise directory is done via picketlink IDM. You can refer to the PicketLink IDM Integration section for further details. The goal of this chapter is to instruct you how to connect eXo Platform to a populated organizational data source, such as LDAP Server, MS ActiveDirectory, or Database, via the following topics:
The commonly used terms when integrating the organizational model.
Synchronize eXo Platform with an existing directory
Instructions on how to activate the service, sync usecases, Scheduled/Periodic sync by using REST or JMX.
Use Legacy Organization Models
Steps to configure Legacy Organization Services, to hibernate Organization Service configuration; and introduction to LDAP Organization Service and AD Organization Service configurations.
Before learning about how to integrate the organizational model, you should be aware of the following terms:
Organizational data are information of users, user profiles, groups, memberships and membership types.
Organizational element refers to a user, user profile, group, membership or membership type.
Active organizational element is an organizational element that eXo Platform has already integrated, and so can be used by eXo Platform's features.
Predefined organizational data are organizational data which are fulfilled in the data source without using eXo Services.
Listener is a part of eXo Platform organization management. When an organizational element is added, a set of listeners is triggered to integrate it into eXo Platform. For example, when a user is added to eXo Platform, there is a listener which will add its private and public drives.
See also
The typical ways to activate a Kernel component named OrganizationIntegrationService.
Instructions on how to synchronize at startup, login time, and on demand.
Instructions on how to do a Scheduled/Periodic sync by using REST or JMX.
When an external organizational data source (LDAP server, MS ActiveDirectory) is used, eXo Platform must be notified of any changes on organizational entities, including addition, deletion and update. These changes are reflected in the backend settings of eXo Platform. These notifications are performed thanks to several means provided by eXo Platform.
Pick up one of the following use cases of integration execution related to your needs.
See also
Out of the box, eXo Platform is configured to leverage the IDM database. If you want to integrate eXo Platform with a user directory, you will need to synchronize this remote directory by activating a Kernel component named OrganizationIntegrationService.
There are 2 typical ways to activate it.
The first way: Adding the entry below to the configuration.xml file which is in the following paths:
| Tomcat | JBoss |
|---|---|
| $PLATFORM_TOMCAT_HOME/gatein/conf/portal/portal/configuration.xml | $PLATFORM_JBOSS_HOME/server/default/conf/gatein/portal/portal/configuration.xml |
<component>
<type>org.exoplatform.platform.organization.integration.OrganizationIntegrationService</type>
<init-params>
<value-param>
<name>workspace</name>
<value>collaboration</value>
</value-param>
<value-param>
<name>homePath</name>
<value>/</value>
</value-param>
<value-param>
<name>synchronizeGroups</name>
<value>true</value>
</value-param>
</init-params>
</component>
<external-component-plugins>
<target-component>org.exoplatform.services.organization.OrganizationService</target-component>
<component-plugin>
<name>organization.initializer.group.event.listener</name>
<set-method>addListenerPlugin</set-method>
<type>org.exoplatform.platform.organization.integration.NewGroupListener</type>
<description>This Listener is invoked when a Group is updated/added. Its purpose is to ensure that OrganizationServiceIntegration does not apply Organization Model Data listeners twice.</description>
</component-plugin>
<component-plugin>
<name>organization.initializer.user.event.listener</name>
<set-method>addListenerPlugin</set-method>
<type>org.exoplatform.platform.organization.integration.NewUserListener</type>
<description>This Listener is invoked when a User is updated/added. Its purpose is to ensure that OrganizationServiceIntegration does not apply Organization Model Data listeners twice.</description>
</component-plugin>
<component-plugin>
<name>organization.initializer.membership.event.listener</name>
<set-method>addListenerPlugin</set-method>
<type>org.exoplatform.platform.organization.integration.NewMembershipListener</type>
<description>This Listener is invoked when a Membership is updated/added. Its purpose is to ensure that OrganizationServiceIntegration does not apply Organization Model Data listeners twice.</description>
</component-plugin>
<component-plugin>
<name>organization.initializer.profile.event.listener</name>
<set-method>addListenerPlugin</set-method>
<type>org.exoplatform.platform.organization.integration.NewProfileListener</type>
<description>This Listener is invoked when a User Profile is updated/added. Its purpose is to ensure that OrganizationServiceIntegration does not apply Organization Model Data listeners twice.</description>
</component-plugin>
</external-component-plugins>
The second way: Add the same entry as in the first way to the WEB-INF/conf/configuration.xml file through a custom extension. The path to the file is independent on JBoss and Tomcat.
Note
In case the configuration.xml file does not exist, you might create a new one.
Next, you can start synchronizing your directory with eXo Platform by using one of the methods described below.
At the start-up of eXo Platform, all groups are synchronized. This means that the groups which have been added/deleted will be integrated. This operation is mandatory because some of eXo Platform features require some system groups to be integrated, such as the system group of Social spaces.
Note
You can skip the synchronization when restarting the server by modifying the synchronizeGroups parameter as below in the configuration to activate OrganizationIntegrationService.
<component>
<type>org.exoplatform.platform.organization.integration.OrganizationIntegrationService</type>
<init-params>
...
<value-param>
<name>synchronizeGroups</name>
<value>false</value>
</value-param>
</init-params>
</component>
Once users have logged in, their profile, memberships and related groups will be auto-synchronized. Also, administrators can activate the synchronization process manually without depending on the users' login. (See the next sections for more details).
You could enforce the integration of some organizational elements via REST or JMX. See the operations you can perform in the following table.
| Operation | Description |
|---|---|
| invokeAllListeners | Synchronize and integrate all organizational elements. |
| invokeGroupsListeners | Synchronize and integrate all groups stored in the data source. |
| invokeGroupListeners | Synchronize and integrate a selected group stored in the data source. |
| invokeUsersListeners | Synchronize and integrate all users stored in the data source. |
| invokeUserListeners | Synchronize and integrate a selected user stored in the data source. |
| invokeMembershipListeners | Synchronize and integrate a specific membership. |
Note
For invokeAllListeners, invokeGroupsListeners and invokeUsersListeners, it may take few hours if the organizational data source contains thousands of users.
You can select the periodic integration of the whole organizational elements which are not integrated yet. This feature is not activated automatically in the eXo Platform distribution. To do so, you will have to add this configuration:
<external-component-plugins>
<target-component>org.exoplatform.services.scheduler.JobSchedulerService</target-component>
<component-plugin>
<name>OrgInitializerCronJob</name>
<set-method>addCronJob</set-method>
<type>org.exoplatform.services.scheduler.CronJob</type>
<description>Schedule the organization integration operation</description>
<init-params>
<properties-param>
<name>cronjob.info</name>
<description>Invoke initializer periodically</description>
<property name="jobName" value="OrgInitializerCronJob"/>
<property name="groupName" value="group"/>
<property name="job" value="org.exoplatform.platform.organization.integration.OrganizationIntegrationJob"/>
<property name="expression" value="0 45 23 * * ? *"/>
</properties-param>
</init-params>
</component-plugin>
</external-component-plugins>
You need to modify the expression property value to change the period according to the CRON Expression documentation. The value presented above means that this job is executed at 23:45:00 everyday.
The organization integration management API is also exposed as REST. You need to login as an administrator first, then use one of those links:
/portal/rest/management/orgsync/syncUser?username=USERNAME&eventType=EVENT
| Para-value | Description |
|---|---|
| USERNAME | Select a username. |
| EVENT |
Select one of the following values.
- ADDED - Select this option if the user is not yet integrated into eXo Platform. This will integrate the use and his/her memberships and groups. - UPDATED - Select this option if the user field or membership has been modified/added/deleted. This will update the user profiles integrated into eXo Platform and all related memberships.
- DELETED - Select this option if the user has been deleted from the organization data source. So the user profile will be deleted from eXo Platform. |
/portal/rest/management/orgsync/syncAllUsers?eventType=EVENT
| Para-value | Description |
|---|---|
| EVENT |
Select one of the following values:
- ADDED - Search for users who are added to the Organization data source, but not yet integrated. Those users will then be synchronized.
- UPDATED - Search for users that are present in the Organization data source and already integrated into eXo Platform. Those profiles will be updated.
- DELETED - Search for users that are deleted from the Organization data source, but their profiles are still always existing in eXo Platform. Those profiles are then deleted. |
Also, you can request for synchronizing all users.
/portal/rest/management/orgsync/syncGroup?groupId=GROUP_ID&eventType=EVENT
| Para-value | Description |
|---|---|
| GROUP_ID | Select a groupId, such as /platform/users. |
| EVENT |
Select one of the following values:
- ADDED - Select this option if the group is not yet integrated into eXo Platform. This will integrate the group.
- UPDATED - This option is not used any longer.
- DELETED - Select this option if the group has been deleted from Organization data source. The group profile is then deleted from eXo Platform. |
/portal/rest/management/orgsync/syncAllGroups?eventType=EVENT
| Para-value | Description |
|---|---|
| EVENT |
Select one of the following values:
- ADDED - Search for groups that are added to the Organization data source, but not yet integrated into eXo Platform. Those groups will be integrated.
- UPDATED: This option is not used any longer.
- DELETED - Search for groups that are deleted from the Organization data source, but their profiles are still existed in eXo Platform. Those profiles are then deleted. |
You can also request for synchronizing all groups.
/portal/rest/management/orgsync/syncMembership?groupId=GROUP_ID&username=USERNAME&eventType=EVENT
| Para-value | Description |
|---|---|
| GROUP_ID | Select a groupId, such as /platform/users. |
| USERNAME | Select a username. |
| EVENT |
Select one of the following values:
- ADDED - Search for memberships that are added to the Organization data source, but not yet integrated into eXo Platform. Those memberships will be integrated.
- UPDATED - This option is not used any longer.
- DELETED - Search for memberships that are deleted from the Organization data source. This will synchronize user's memberships related to the selected group. |
/portal/rest/management/orgsync/syncAll: This will synchronize all groups and users.
To access the Integration Service features via JMX, you can use JMX-compliant monitoring tools, such as JConsole. The name of the MBean is: exo:portal="portal",service=extensions,name=OrganizationIntegrationService,type=platform.
If you use one of the Organization Data Models (LDAP Organization Service, Active Directory or Hibernate) in a previous version of eXo Platform, you will be able to keep working with them on eXo Platform 3.5.
Configure Legacy Organization Services
1. Add a new file named configuration.xml in ${exo.conf.dir.name}/portal/portal/ with the following configuration.
<configuration xmlns="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd http://www.exoplaform.org/xml/ns/kernel_1_2.xsd">
<import>legacy-organization-configuration.xml</import>
<!-- Remove unnecessary Picket LINK Services -->
<remove-configuration>org.exoplatform.services.organization.idm.PicketLinkIDMCacheService</remove-configuration>
<remove-configuration>org.exoplatform.services.organization.idm.PicketLinkIDMService</remove-configuration>
</configuration>
2. Add a new file named legacy-organization-configuration.xml in ${exo.conf.dir.name}/portal/portal with one of the contents below.
Hibernate Organization Service configuration
<configuration xmlns="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd http://www.exoplaform.org/xml/ns/kernel_1_2.xsd">
<component>
<key>org.exoplatform.services.organization.OrganizationService</key>
<type>org.exoplatform.services.organization.hibernate.OrganizationServiceImpl</type>
</component>
<external-component-plugins>
<target-component>org.exoplatform.services.database.HibernateService</target-component>
<component-plugin>
<name>add.hibernate.mapping</name>
<set-method>addPlugin</set-method>
<type>org.exoplatform.services.database.impl.AddHibernateMappingPlugin</type>
<init-params>
<values-param>
<name>hibernate.mapping</name>
<value>org/exoplatform/services/organization/impl/UserImpl.hbm.xml</value>
<value>org/exoplatform/services/organization/impl/MembershipImpl.hbm.xml</value>
<value>org/exoplatform/services/organization/impl/GroupImpl.hbm.xml</value>
<value>org/exoplatform/services/organization/impl/MembershipTypeImpl.hbm.xml</value>
<value>org/exoplatform/services/organization/impl/UserProfileData.hbm.xml</value>
</values-param>
</init-params>
</component-plugin>
</external-component-plugins>
<import>classpath:/conf/portal/organization-configuration.xml</import>
</configuration>
Configure LDAP Organization Service
<configuration xmlns="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd http://www.exoplaform.org/xml/ns/kernel_1_2.xsd">
<component>
<key>org.exoplatform.services.ldap.LDAPService</key>
<type>org.exoplatform.services.ldap.impl.LDAPServiceImpl</type>
<init-params>
<object-param>
<name>ldap.config</name>
<description>Default ldap config</description>
<object type="org.exoplatform.services.ldap.impl.LDAPConnectionConfig">
<field name="providerURL"><string>ldap://127.0.0.1:389,10.0.0.1:389</string></field>
<field name="rootdn"><string>CN=Manager,DC=exoplatform,DC=org</string></field>
<field name="password"><string>secret</string></field>
<field name="version"><string>3</string></field>
<field name="minConnection"><int>5</int></field>
<field name="maxConnection"><int>10</int></field>
<field name="referralMode"><string>follow</string></field>
<field name="serverName"><string>default</string></field>
</object>
</object-param>
</init-params>
</component>
<component>
<key>org.exoplatform.services.organization.OrganizationService</key>
<type>org.exoplatform.services.organization.ldap.OrganizationServiceImpl</type>
<component-plugins>
<component-plugin>
<name>init.service.listener</name>
<set-method>addListenerPlugin</set-method>
<type>org.exoplatform.services.organization.ldap.OrganizationLdapInitializer</type>
<description>this listener populate organization ldap service create default dn</description>
</component-plugin>
</component-plugins>
<init-params>
<value-param>
<name>ldap.userDN.key</name>
<description>The key used to compose user DN</description>
<value>cn</value>
</value-param>
<object-param>
<name>ldap.attribute.mapping</name>
<description>ldap attribute mapping</description>
<object type="org.exoplatform.services.organization.ldap.LDAPAttributeMapping">
<field name="userLDAPClasses"><string>top,person,organizationalPerson,inetOrgPerson</string></field>
<field name="profileLDAPClasses"><string>top,organizationalPerson</string></field>
<field name="groupLDAPClasses"><string>top,organizationalUnit</string></field>
<field name="membershipTypeLDAPClasses"><string>top,organizationalRole</string></field>
<field name="membershipLDAPClasses"><string>top,groupOfNames</string></field>
<field name="baseURL"><string>dc=exoplatform,dc=org</string></field>
<field name="groupsURL"><string>ou=groups,ou=portal,dc=exoplatform,dc=org</string></field>
<field name="membershipTypeURL"><string>ou=memberships,ou=portal,dc=exoplatform,dc=org</string></field>
<field name="userURL"><string>ou=users,ou=portal,dc=exoplatform,dc=org</string></field>
<field name="profileURL"><string>ou=profiles,ou=portal,dc=exoplatform,dc=org</string></field>
<field name="userUsernameAttr"><string>uid</string></field>
<field name="userPassword"><string>userPassword</string></field>
<field name="userFirstNameAttr"><string>givenName</string></field>
<field name="userLastNameAttr"><string>sn</string></field>
<field name="userDisplayNameAttr"><string>displayName</string></field>
<field name="userMailAttr"><string>mail</string></field>
<field name="userObjectClassFilter"><string>objectClass=person</string></field>
<field name="membershipTypeMemberValue"><string>member</string></field>
<field name="membershipTypeRoleNameAttr"><string>cn</string></field>
<field name="membershipTypeNameAttr"><string>cn</string></field>
<field name="membershipTypeObjectClassFilter"><string>objectClass=organizationalRole</string></field>
<field name="membershiptypeObjectClass"><string>organizationalRole</string></field>
<field name="groupObjectClass"><string>organizationalUnit</string></field>
<field name="groupObjectClassFilter"><string>objectClass=organizationalUnit</string></field>
<field name="membershipObjectClass"><string>groupOfNames</string></field>
<field name="membershipObjectClassFilter"><string>objectClass=groupOfNames</string></field>
<field name="ldapCreatedTimeStampAttr"><string>createdTimeStamp</string></field>
<field name="ldapModifiedTimeStampAttr"><string>modifiedTimeStamp</string></field>
<field name="ldapDescriptionAttr"><string>description</string></field>
</object>
</object-param>
</init-params>
</component>
<external-component-plugins>
<target-component>org.exoplatform.services.database.HibernateService</target-component>
<component-plugin>
<name>add.hibernate.mapping</name>
<set-method>addPlugin</set-method>
<type>org.exoplatform.services.database.impl.AddHibernateMappingPlugin</type>
<init-params>
<values-param>
<name>hibernate.mapping</name>
<value>org/exoplatform/services/organization/impl/UserProfileData.hbm.xml</value>
</values-param>
</init-params>
</component-plugin>
</external-component-plugins>
</configuration>
AD Organization Service configuration
<configuration xmlns="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_2.xsd http://www.exoplaform.org/xml/ns/kernel_1_2.xsd">
<component>
<key>org.exoplatform.services.ldap.LDAPService</key>
<type>org.exoplatform.services.ldap.impl.LDAPServiceImpl</type>
<init-params>
<object-param>
<name>ldap.config</name>
<description>Default ldap config</description>
<object type="org.exoplatform.services.ldap.impl.LDAPConnectionConfig">
<field name="providerURL"><string>ldap://192.168.2.88:389</string></field>
<field name="rootdn"><string>CN=Administrator,CN=Users, DC=exoplatform,DC=org</string></field>
<field name="password"><string>Secret1234</string></field>
<field name="version"><string>3</string></field>
<field name="minConnection"><int>5</int></field>
<field name="maxConnection"><int>10</int></field>
<field name="referralMode"><string>ignore</string></field>
<field name="serverName"><string>active.directory</string></field>
</object>
</object-param>
</init-params>
</component>
<component>
<key>org.exoplatform.services.organization.OrganizationService</key>
<type>org.exoplatform.services.organization.ldap.OrganizationServiceImpl</type>
<component-plugins>
<component-plugin>
<name>init.service.listener</name>
<set-method>addListenerPlugin</set-method>
<type>org.exoplatform.services.organization.ldap.OrganizationLdapInitializer</type>
<description>this listener populate organization ldap service create default dn</description>
</component-plugin>
</component-plugins>
<init-params>
<object-param>
<name>ldap.attribute.mapping</name>
<description>ldap attribute mapping</description>
<object type="org.exoplatform.services.organization.ldap.LDAPAttributeMapping">
<field name="userLDAPClasses"><string>top,person,organizationalPerson,user</string></field>
<field name="profileLDAPClasses"><string>top,organizationalPerson</string></field>
<field name="groupLDAPClasses"><string>top,organizationalUnit</string></field>
<field name="membershipTypeLDAPClasses"><string>top,group</string></field>
<field name="membershipLDAPClasses"><string>top,group</string></field>
<field name="baseURL"><string>DC=test,DC=man</string></field>
<field name="groupsURL"><string>ou=groups,ou=portal,DC=test,DC=man</string></field>
<field name="membershipTypeURL"><string>ou=memberships,ou=portal,DC=test,DC=man</string></field>
<field name="userURL"><string>ou=users,ou=portal,DC=test,DC=man</string></field>
<field name="profileURL"><string>ou=profiles,ou=portal,DC=test,DC=man</string></field>
<field name="userUsernameAttr"><string>sAMAccountName</string></field>
<field name="userPassword"><string>unicodePwd</string></field>
<field name="userFirstNameAttr"><string>givenName</string></field>
<field name="userLastNameAttr"><string>sn</string></field>
<field name="userDisplayNameAttr"><string>displayName</string></field>
<field name="userMailAttr"><string>mail</string></field>
<field name="userObjectClassFilter"><string>objectClass=user</string></field>
<field name="membershipTypeMemberValue"><string>member</string></field>
<field name="membershipTypeRoleNameAttr"><string>cn</string></field>
<field name="membershipTypeNameAttr"><string>cn</string></field>
<field name="membershipTypeObjectClassFilter"><string>objectClass=group</string></field>
<field name="membershiptypeObjectClass"><string>group</string></field>
<field name="groupObjectClass"><string>organizationalUnit</string></field>
<field name="groupObjectClassFilter"><string>objectClass=organizationalUnit</string></field>
<field name="membershipObjectClass"><string>group</string></field>
<field name="membershipObjectClassFilter"><string>objectClass=group</string></field>
<field name="ldapCreatedTimeStampAttr"><string>createdTimeStamp</string></field>
<field name="ldapModifiedTimeStampAttr"><string>modifiedTimeStamp</string></field>
<field name="ldapDescriptionAttr"><string>description</string></field>
</object>
</object-param>
</init-params>
</component>
<external-component-plugins>
<target-component>org.exoplatform.services.database.HibernateService</target-component>
<component-plugin>
<name>add.hibernate.mapping</name>
<set-method>addPlugin</set-method>
<type>org.exoplatform.services.database.impl.AddHibernateMappingPlugin</type>
<init-params>
<values-param>
<name>hibernate.mapping</name>
<value>org/exoplatform/services/organization/impl/UserProfileData.hbm.xml</value>
</values-param>
</init-params>
</component-plugin>
</external-component-plugins>
</configuration>
See also