Synchronizing Data from External Directories
Hipchat Server stores a cache of directory information in the application database to ensure fast recurrent access to user data. A synchronization task runs periodically to update the internal cache with changes from the external directory.
On this page:
How it works
Here is a summary of the caching functionality:
- The caches are held in the application database.
- When you connect a new external user directory to the application, a synchronization task will start running in the background to copy all the required users, groups and membership information from the external directory to the application database. This task may take a while to complete, depending on the size and complexity of your user base.
- Note that a user will not be able to log in until the synchronization task has copied that user's details into the cache.
- A periodic synchronization task will run to update the database with any changes made to the external directory. The default synchronization interval, or polling interval, is one hour (60 minutes). You can change the synchronization interval on the directory configuration screen.
- You can manually synchronize the cache if necessary.
- All authentication happens via calls to the external directory. When caching information from an external directory, the application database does not store user passwords.
- All other queries run against the internal cache.
After you synchronize a user directory, any users that were deleted from the directory still exist in Hipchat Server. Hipchat Server keeps the deleted users to preserve their chat histories. Deleted users do not count against the amount of users allowed for your license. To view the deleted users, choose Group admin > Users and select Show deleted.
If you remove the external directory itself (in Group admin > Authentication) users will no longer be able to log in.
Finding the time taken to synchronize
The 'External Directories' screen shows information about the last synchronization operation, including the length of time it took.
Manually synchronizing the cache
You can manually synchronize the cache by clicking 'Synchronize' on the 'User Directories' screen. If a synchronization operation is already in progress, you cannot start another until the first has finished.
Screen snippet: User directories, showing information about synchronization
In the unlikely event that the cache is corrupted, the only way to flush it is by clicking Disable then Enable. This step will briefly prevent users from logging in while the sync is running but will not disconnect any users that are online already.
Configuring the synchronization interval
The length you choose for your synchronization interval depends on:
- The length of time you can tolerate stale data.
- The amount of load you want to put on the application and the directory server.
- The size of your user base.
If you synchronize more frequently, then your data will be more up to date. The downside of synchronizing more frequently is that you may overload your server with requests.
If you are not sure what to do, we recommend that you start with an interval of 60 minutes (this is the default setting) and reduce the value incrementally. You will need to experiment with your setup.