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

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|#ADM.Integration.Integrate_organizational_model.Terminology]
* [Integrate the organizational model|#ADM.Integration.Integrate_organizational_model]
** [eXo Platform start-up|#ADM.Integration.Integrate_organizational_model.Platform_startup]
** [User login|#ADM.Integration.Integrate_organizational_model.User_login]
** [Manual sync|#ADM.Integration.Integrate_organizational_model.Manual_sync]
** [Scheduled/Periodic sync|#ADM.Integration.Integrate_organizational_model.Scheduled_periodic_sync]

h1. Terminology {anchor:id=ADM.Integration.Integrate_organizational_model.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.

h1. Integrate the organizational model {anchor:id=ADM.Integration.Integrate_organizational_model}

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. {anchor:id=ADM.Integration.Integrate_organizational_model.Integration_execution_use_cases}

h2. eXo Platform start-up {anchor:id=ADM.Integration.Integrate_organizational_model.Platform_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 eXo 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_:

{code:xml}
<component>
  <type>org.exoplatform.platform.component.organization.OrganizationIntegrationService</type>
  <init-params>
    ...
    <value-param>
      <name>synchronizeGroups</name>
      <value>false</value>
    </value-param>
  </init-params>
</component>
{code}

h2. User login {anchor:id=ADM.Integration.Integrate_organizational_model.User_login}

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

h2. Manual sync {anchor:id=ADM.Integration.Integrate_organizational_model.Manual_sync}

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.
{note}

h2. Scheduled/Periodic sync {anchor:id=ADM.Integration.Integrate_organizational_model.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: 

{code:xml}
<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.component.organization.OrganizationIntegrationJob"/>
				<property name="expression" value="0 45 23 * * ? *"/>
			</properties-param>
		</init-params>
	</component-plugin>
</external-component-plugins>
{code}

You need to modify the *expression* property value to change the period according to the [CRON Expression documentation|http://www.quartz-scheduler.org/docs/tutorial/TutorialLesson06.html]. The value presented above means that this job is executed at 23:45:00 everyday.

h3. Use REST {anchor:id=ADM.Integration.Integrate_organizational_model.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. {example} {example} - *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. {example}{example} - *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. {example} {example} - *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: {example} {example} - *ADDED* - Search for users who are added to the Organization data source, but not yet integrated. Those users will then be synchronized. {example} {example} - *UPDATED* - Search for users that are present in the Organization data source and already integrated into eXo Platform. Those profiles will be updated. {example} {example} - *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: {example} {example} - *ADDED* - Select this option if the group is not yet integrated into eXo Platform. This will integrate the group. {example} {example} - *UPDATED* - This option is not used any longer. {example} {example} - *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: {example} {example} - *ADDED* - Search for groups that are added to the Organization data source, but not yet integrated into eXo Platform. Those groups will be integrated. {example} {example} - *UPDATED*: This option is not used any longer. {example} {example} - *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: {example} {example} - *ADDED* - Search for memberships that are added to the Organization data source, but not yet integrated into eXo Platform. Those memberships will be integrated. {example} {example} - *UPDATED* - This option is not used any longer. {example} {example} - *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.

h3. Use JMX {anchor:id=ADM.Integration.Integrate_organizational_model.Use_JMX}

To access the Integration Service features via JMX, you can use JMX-compliant monitoring tools, such as [JConsole|http://download.oracle.com/javase/6/docs/technotes/guides/management/jconsole.html].
The name of the MBean is: exo:portal="portal",service=extensions,name=OrganizationIntegrationService,type=platform.

!images/integration/jmx_console.png!