How to sync the AD Line Manager to DocRead using Powershell
In DocRead 2.1 (available mid-September) we introduced some new Powershell Cmdlets to help SharePoint Administrators synchronize the ‘Manager’ property from Active Directory to the DocRead database.
Please note, if you are not using SharePoint Foundation, you can ignore this as it’s very likely that the manager property is already propagated to the SharePoint User Profile using the User Profile Synchronization service.
Anyway, before showing you how this can be achieved, let’s spend a few moments explaining why this is needed.
What are the DocRead Line Manager features?
New functionality released in DocRead 2.0 allowed Line Managers to:
- Get notified (via email) when an employees required reading becomes overdue(or optionally assigned and/or completed).
- View 3 new Reports showing a break down of the status of all their employees required reading progress.
How we implemented the new Line Manager features
As you may know, for a variety of reasons (such as security, performance and scalability) DocRead has its own database to store information about Reading Tasks, Users, Groups / Audiences and Documents. This also offers a massive advantage because it allows a user to see all of their tasks from across the entire farm. This is a big restriction in SharePoint when attempting to display “cross-site” content as it can’t be done easily. With regard to Line Managers, this means they can see all of their employees tasks, regardless of where the original document resides in the Farm.
To offer the new functionality, we needed to store the employee / manager relationship within the DocRead database. However, to store it in DocRead we needed to pull the relationship from somewhere…
Active Directory also stores Line manager
In nearly all organizations, Active Directory is the main method used to store the relationship between employee and manager. For example, if you examine a users AD profile, you will notice this field below:
So now we know where it is, how do we get it into DocRead?
A Note about SharePoint User Profiles
In all versions of SharePoint (except Foundation), Microsoft have provided a convenient way to synchronise the user information from Active Directory into something known as the SharePoint User Profile. So when DocRead needs to know information about the user (such as name, email address etc.), we always get it from the SharePoint User Profile (not Active Directory).
When we implemented the Line Manager functionality in DocRead 2.0 we extracted the ‘Manager’ field from the User Profile and used it with DocRead. One reason for using the User Profile (not AD) is because the SharePoint API offers several convenient ways to retrieve the required information. However, the main reason is because some organizations don’t use Active Directory at all.
SharePoint Foundation – the snag
As stated above, SharePoint Foundation has no concept of a User Profile, which makes it impossible to offer the functionality to customers using DocRead on SharePoint Foundation (in version 2.0) as there is was no way to retrieve the ‘Manager’ field.
As side note, as there is no user profile sync in Foundation, this also means that it’s not possible to update even the basic information (name, email) from AD into the SharePoint user record. However, there are tools out there to help such as the ‘SharePoint Foundation Synchronization’ tool on Codeplex. (Big thanks to fellow SharePoint Community Rep, Trevor Seward for that).
Powershell to the rescue!
So, if we can’t rely on SharePoint to grab the ‘Manager’ from AD how can we achieve the same result? Powershell to the rescue!
Assuming you have installed version DocRead 2.1, you will now have access to 2 new Cmdlets called:
This Cmdlet is responsible for returning all of the users from the DocRead database. This is very useful if you have a very large AD (many 1000’s of users) and a smaller number who have reading tasks assigned. It’s more efficient to loop through the DocRead users than the other way around!
The Set-DRLineManager Cmdlet will update a specified users Line Manager within the DocRead database.
Putting it all together into a custom script
You can use these 2 commands with your own Powershell script to query your AD, get users manager and then update DocRead. The script below illustrates how this could be achieved.
One last note on permissions
To use the new Powershell cmdlets you will need to ‘run as‘ a user who has been granted the SPShellAccess DB Role. (This can be achieved using ‘Add-SPShellAdmin‘).
In addition to this, you will also need to add the user into the ‘Powershell User Accounts’ section in Central Admin. (see below).