eXo Platform 3.5

## Chapter 10. Organization Integration

The eXo Platform integration with another 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 enteprise directory is done via picketlink IDM. You can refer to PicketLink IDM Integration chapter for 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, through the following topics:

- Terminology

- Sync Platform with an existing Directory

  - Sync at startup

  - Sync at login time

  - Sync on demand

  - Scheduled/Periodic sync

  - Use Legacy Organization Models

## Terminology

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.

## Sync Platform with an existing Directory

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 related to your needs.

Pick up one of the following use cases of integration execution related to your needs.

### Sync at startup

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.

In case you want to disable groups synchronization at start-up, and proceed manually to the system groups synchronization, you must modify an init param of 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>

### Sync at login time

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

### Sync on demand

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.

### Scheduled/Periodic sync

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.

#### Use REST

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/syncAllUser?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.

#### Use JMX

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.

## Use Legacy Organization Models

If you used one of those Organization Data Models.

- LDAP Organization Service

- Active Directory

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

LDAP 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://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>